gagarinDocumentation

Why coherence

The complaint this all started from: your agent writes code faster than it used to, and shipping takes exactly as long as it always did. Cluster settings, ingress, egress, pod counts, rollout strategy. That is where the day goes.

The diagnosis

The stock answer is that clouds are complicated. It is the wrong word, and the wrong word leads somewhere: wrappers, generators, one more coat of paint over the same mess.

The right word is incoherent. A cloud has ten years of decisions in it and has thrown none of them away, so you can change your infrastructure from a dashboard, from a manifest, from a CLI, or by pushing to git. All four write to the same state. None of them outranks the others. The source of truth is whatever happens to be running at the time.

DigitalOcean’s App Platform is the case worth looking at. There is a manifest — but delete a resource by hand in the dashboard and the manifest quietly becomes a lie. It is not idempotent, it is not immutable, and it is not the system. It is a description of the system bolted on beside it, competing with three other ways to change the same thing.

AS IT IS NOWdashboardmanifestCLIauto-deploy?whatever is running nowfour writers,none authoritativeAS IT IS HEREagentCLICIAPIplatform databasesource of truthclusterconverged to itone gatewayfor everyone
fig. 1 · It was never about how many ways there are to make a change. It is about how many places the truth lives. Above, none. Below, one.

Why this is one problem and not two

Agents handle incoherence no better than people do. Building a cloud an agent can operate takes a particular discipline: one way to do each thing, state in one place, words at the level of the problem, none of the fifteen-year sediment. That is the same discipline that makes a cloud a person can read.

Everything else follows from that. We build for the agent not because it is fashionable, but because an agent is a merciless reader. It will not guess. It will not lean over and ask a colleague. It will not remember that last time you had to go and click something in a dashboard. Having to be legible to a machine turns out to be the same thing as having to be legible.

What that buys you, concretely

  • State lives in one database and the API is the only thing that can change it. The CLI, and whatever interface comes next, are thin wrappers over the same call.
  • There are no manifests at all. You cannot fall out of step with a file that was never written, which is a great deal stronger than promising to keep one up to date.
  • The words stay human: projects, services, resources, dependencies. “What is in here?” gets answered in those, not in security groups and service accounts.

What we are not claiming

That your deploys stop breaking. One class of failure goes away — bad configuration, a manifest that would not assemble, an image nobody can find. Containers still crash-loop and migrations still fail to apply. What changes is that you get told which of the two pictures disagrees with the other.