Roll out a change without downtime

Goal

A new image serving traffic with no gap, and an automatic return to the previous one if it does not become healthy.

Before you start

• A deployment with a health check of type exec that really runs. Readiness is unknowable without one, and the precondition is checked.
• No read-write named volume, no writable bind mount and no published node port: two versions cannot share those.
• Your own attestation that two versions may briefly run at once. It is never inferred.

Dashboard

Steps

1. Open the deployment and choose Update strategy.
2. Choose the rolling strategy, confirm that concurrent versions are allowed, and set the surge and unavailable counts.
3. Set the health timeout, the dwell time and the deadline for the whole rollout.
4. Choose what happens if it does not finish: pause, or roll back.
5. Change the image and deploy.

YAML manifest

Steps

1. Add an update block to the spec, with the strategy, the attestation and the timings.
2. Change the image in the same document.
3. Apply it. Field names and defaults are in the deployment reference.

REST API

Steps

1. PUT /api/v1/deployments/{name} carrying the update policy and the new image.
2. GET /api/v1/deployments/{name} to watch replicas hand over.
3. POST /api/v1/deployments/{name}/rollback to return to the previous revision by hand.

CLI

Steps

1. odysseus rollback and odysseus history inspect and reverse a rollout.
2. The change itself goes through the API or the dashboard: odysseus deploy writes the legacy flat path the control plane no longer reconciles, and says so when you run it.

Verify

The replica count never drops below your stated minimum during the change, and the deployment ends on the new image with every replica healthy.

Evidence this worked

GET /api/v1/deployments/{name}/history lists the revision that was created, and the deployment’s current image is the new one. A rollback that fired leaves the previous revision current — the history is how you tell the difference between “it worked” and “it was reverted for you”.

When it fails

• The rollout is refused at apply. A gradual strategy has four preconditions and the refusal names the one that failed. The commonest is the missing attestation that two versions may coexist.
• The health check is present but produces no probe. That is refused now, and it is why the precondition became meaningful — see health checks and process reaping.
• The rollout stops partway. It hit the deadline you set and took the failure action you chose.
• Every code: rejections and alterations.