Rollouts
A Rollout deploys the builds of one OCI artifact into one environment, one build at a time, and holds further deploys when a build fails its health checks. The artifact is either your container image or the rendered manifests for that environment.
On this page
How a build is chosen
A Rollout reads its releases from a ReleaseSource, which lists the tags of an OCI repository. Every release newer than the deployed one is a candidate. The Rollout deploys the newest candidate that every gate allows, by writing the version to the Flux source it owns: a Kustomization substitution variable or an OCIRepository tag. It then bakes the build and records the outcome in status.history.
Kuberik deploys one version at a time. If 1.2.0 is deploying or baking when 1.3.0 and 1.4.0 arrive, both wait as candidates. When 1.2.0 succeeds, the Rollout deploys the newest candidate the gates allow, 1.4.0, and skips 1.3.0.
Rollout resource
apiVersion: kuberik.com/v1alpha1
kind: Rollout
metadata:
name: hello-world
namespace: hello-world
spec:
releaseSourceRef:
name: hello-world
versionHistoryLimit: 5
deployTimeout: 10m # healthy within 10m
bakeTime: 15m
healthCheckSelector:
selector:
matchLabels:
app: hello-world| Field | Purpose |
|---|---|
releaseSourceRef | The ReleaseSource that provides new versions, in the Rollout’s namespace. |
releasesImagePolicy | Deprecated and ignored. Use releaseSourceRef. |
versionHistoryLimit | How many past deployments to keep in status.history (default 10). |
bakeTime | How long the build must stay free of health-check errors once the bake starts (e.g., 5m, 1h). |
deployTimeout | How long to wait for the health checks to become healthy after a deploy. When it passes before the bake starts, the deploy fails. Unset means wait indefinitely. |
healthCheckSelector | Label selector (and optional namespace selector) for the HealthCheck resources to evaluate. |
wantedVersion | Pins the Rollout to one tag: it deploys that tag and nothing else until you clear the field. See Operate with kubectl. |
Rollout status


kubectl -n hello-world get rollout hello-world -o yamlhistory: deployments, newest first.history[0].version.tagis the running version; each entry records itsmessage,triggeredByandbakeStatus(Deploying,InProgress,Succeeded,FailedorCancelled).candidates: the newest releases newer than the deployed one (20 by default, set by the controller flag--release-candidates), plus any tag a gate, the pin or an action annotation names, up to 64. Gates and selection see every release; this list is what the status shows.gated: truemeans every gate lets the release through;blockedBynames the gates that hold it.gates: each gate that targets this Rollout, whether it is passing, and the versions it allows.conditionsincludeReady,GatesPassing,DeploymentBlocked(a health check is unhealthy),BakeFailureDisabled(see When a bake fails), andReleasesUpdatedandReleaseSourceReady(whether releases can be read from the ReleaseSource).
What a Rollout propagates
A Rollout does not care what its versions point at. Annotate a Kustomization and Kuberik substitutes the version into it; annotate an OCIRepository and Kuberik moves its tag. Gating, health checks and bake time work the same way in both cases. See Propagation Modes for the trade-offs and for running both at once.
When a deploy is held
Before an automatic deploy, the build must be allowed by every gate that targets the Rollout. A gate either lets a build through or holds it; a held build is evaluated again whenever a gate changes, and nothing is rejected for good. Gates never hold deploys you start by hand. On a Rollout’s first deploy they never hold either: it deploys the newest release the gates allow, or the newest release if they allow none.
Automatic deploys also wait while any selected health check reports Unhealthy. The Rollout then sets DeploymentBlocked=True with the name of the check. A check that is still Pending holds nothing, and a Rollout’s first deploy and deploys you start by hand go ahead regardless.
How a deploy is verified
After a deploy, the history entry starts in Deploying. The bake starts (InProgress) once every selected health check is Healthy and has changed state since the deploy, so a check that was healthy before the deploy does not count until it reports on the new build. The deploy:
- succeeds when
bakeTimepasses after the bake started, with no error; - fails when a health check reports an error at any point after the deploy, before or during the bake;
- fails when
deployTimeoutpasses before the bake starts; - is cancelled when a deploy you start by hand replaces it.
A Rollout with no bakeTime, deployTimeout or healthCheckSelector marks each deploy Succeeded straight away.
When a bake fails
Kuberik does not roll back. When a bake fails, the failed build keeps running, the Rollout sets Ready=False, and no newer build deploys automatically until a person pins a version, deploys a build by hand, sets rollout.kuberik.com/unblock-failed, or retries the bake. Operate with kubectl shows each of these.


When a deploy starts, the Rollout sets the BakeFailureDisabled condition for it. The condition is True, and health-check errors and deployTimeout do not fail that deploy, in two cases:
| Reason | When |
|---|---|
PreviousBakeFailed | The previous deploy did not end with a successful bake: it failed, or this deploy cancelled its bake. |
DeployedWithUnhealthyHealthChecks | A deploy you started by hand began while a selected health check was Unhealthy. |
The bake still has to start: it starts the first time every check is Healthy after the deploy, and the deploy succeeds bakeTime later. Errors during that window do not fail it, so a recovery deploy is not verified the way a normal one is. If the checks never turn healthy, it stays in Deploying and the next build has to be deployed by hand. The condition holds until the next deploy starts.
Related
- Concepts Propagation Modes Move an image tag or rendered manifests through your environments.
- Concepts How Gates Work What holds a deploy back: RolloutGates, schedules, approvals, service dependencies and health checks.
- Operate Operate with kubectl Pin a version, roll back, deploy a specific build, let a build past its gates, or resume after a failed bake.