Deployments and containers

The problem

A container is a running thing: it has an identity, a lifetime, and it dies. What you actually want to describe is not one container but the intent behind it — this image, this many copies, reachable here, shaped like this — and to have something else keep that intent true while individual containers come and go.

The gap between the two is where most orchestration mistakes live. Edit the wrong thing and you have changed a running container that will be replaced in an hour. Edit the right thing carelessly and you have replaced containers you only meant to relabel.

How the platform solves it

A deployment is the description. A container is one running copy of it. You edit the description; the platform decides what that means for the copies.

That decision is computed, not judged. Everything that shapes a container is hashed, and a change to the hash means the container is replaced rather than adjusted. A change to anything outside it — the orchestration around the container, the record-keeping — takes effect without touching what is running. The reference tables carry that answer per field, in the mutability column, and it is measured by running the hash function rather than asserted in a sentence: see the deployment manifest.

The description is also the whole of the intent. The platform does not read the running container back and adopt what it finds. If a container drifts, the description wins.

Sending part of a description

An update may carry part of a deployment rather than all of it, and the rule has two halves that are easy to conflate.

A field you leave out keeps its stored value. That is what makes an image change a one-field request: nothing else has to be read first, and nothing else moves.

A field you send replaces the stored one outright. Collections are not merged. Sending a map of one environment variable does not add that variable to the stored map — it becomes the whole map, and everything else in it is gone. The same is true of volumes, networks, labels and secret references.

So changing one entry of a collection means reading the stored collection, changing it locally, and sending it back whole. This is deliberate — sending a field means “this is now its value” — but it is the one place where a partial request can remove configuration nobody meant to remove, which is why it is stated here rather than left to be discovered.

A removed secret reference is the case worth naming: the container then starts without that credential rather than failing loudly.

Not this

This page does not enumerate the fields, their types or their defaults. Those are generated from the schema and live in the deployment manifest reference; restating them here would create a second copy that can disagree with the first.

It also does not cover work that runs to completion rather than staying up — see scheduled work — or how a change is rolled out, which is rollouts.

Where to see it

• Every field of a deployment: deployment manifest.
• What a refused change tells you: rejections and alterations.