Verify with Health Checks
A Rollout with health checks marks a deploy succeeded once its checks stay healthy for the bake time, and fails it if a check turns unhealthy or deployTimeout passes first. Without deployTimeout, a build that never turns healthy waits in Deploying and holds newer releases.
On this page
Works with: Flux Kustomizations (built into rollout-controller), Datadog monitors and incidents (datadog-controller), and Prometheus alerts (prometheus-controller).
Add a health check
A HealthCheck reports Healthy, Unhealthy or Pending in status.status; its spec.class names the controller that fills it in. This one follows a Flux Kustomization:
apiVersion: kuberik.com/v1alpha1
kind: HealthCheck
metadata:
name: hello-world
namespace: hello-world
labels:
app: hello-world # the Rollout selects this
annotations:
healthcheck.kuberik.com/kustomization: "hello-world"
spec:
class: kustomizationThe annotation takes the Kustomization’s name, or <namespace>/<name> for one in another namespace.
Select health checks from the Rollout
Set healthCheckSelector on the Rollout, and a bake time the checks must hold:
apiVersion: kuberik.com/v1alpha1
kind: Rollout
metadata:
name: hello-world
namespace: hello-world
spec:
releaseSourceRef:
name: hello-world
bakeTime: 10m # healthy this long
deployTimeout: 15m
healthCheckSelector:
selector:
matchLabels:
app: hello-worldEach deploy, and each retry, then goes through these rules:
| Moment | What happens |
|---|---|
| Deploy starts | Every selected HealthCheck is reset to Pending and its lastErrorTime is cleared, and the deploy’s bakeStatus is Deploying |
Every check is Healthy again | Bake starts: bakeStatus is InProgress |
| Any check reports an error after the deploy started | The deploy fails (bakeStatus Failed, Ready reason BakeTimeFailed), before or during bake |
deployTimeout passes before bake starts | The deploy fails (“Deploy timeout reached before bake could start”) |
bakeTime passes with no error | The deploy succeeds. Without bakeTime, it succeeds as soon as bake starts |
deployTimeout fails the deploy if bake has not started by then; without it, the deploy waits. A Rollout without healthCheckSelector has no checks: bake starts at once.
Hold deploys on an unhealthy check
While a check is unhealthy, new automatic deploys wait. You do not configure this: while any selected HealthCheck is Unhealthy, the Rollout reports DeploymentBlocked=True with reason UnhealthyHealthChecks; Pending does not block. The very first deploy and manual deploys (a pin in spec.wantedVersion or rollout.kuberik.com/force-deploy) are not held.
After a deploy fails, the Rollout starts no new automatic deploy until you retry it, set rollout.kuberik.com/unblock-failed: "true", or deploy a version by hand (Operate with kubectl).
A manual deploy made while a check is Unhealthy, and any deploy that follows one that did not succeed, sets BakeFailureDisabled=True (reasons DeployedWithUnhealthyHealthChecks and PreviousBakeFailed). For that deploy, health-check errors and deployTimeout do not fail it, so a fix can land during an incident.
kubectl -n hello-world get rollout hello-world -o jsonpath='{range .status.conditions[*]}{.type}={.status} ({.reason}){"\n"}{end}'Choose how a Kustomization is checked
With spec.wait: false (the default) on the Kustomization, the check reads the Kustomization and every resource it manages with kstatus. With spec.wait: true, it reads only the Kustomization’s Ready condition and assumes kustomize-controller runs with the CancelHealthCheckOnNewRevision feature gate (Flux 2.7 or later); without it, a failing revision holds the next one until spec.timeout.
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: hello-world
namespace: hello-world
spec:
interval: 10m
prune: true
wait: true # health from Ready only
timeout: 5m
sourceRef:
kind: OCIRepository
name: hello-worldFlux lists which Ready reasons count as unhealthy.
Select health checks in other namespaces
Add namespaceSelector to read HealthChecks from every namespace whose labels match, for example checks a platform team keeps in a shared namespace. It replaces the Rollout’s own namespace, so label that namespace too if its checks should still count.
apiVersion: kuberik.com/v1alpha1
kind: Rollout
metadata:
name: hello-world
namespace: hello-world
spec:
releaseSourceRef:
name: hello-world
healthCheckSelector:
selector:
matchLabels:
app: hello-world
namespaceSelector:
matchLabels:
kuberik.com/health-checks: "true"A deploy resets each selected check to Pending and clears its lastErrorTime. A check that several Rollouts select through namespaceSelector resets whenever any of them deploys, so keep the label selector narrow enough that each Rollout selects only its own checks.
Check the result
List the checks and the latest deploy’s bake state:
kubectl -n hello-world get healthchecks -o custom-columns=NAME:.metadata.name,STATUS:.status.status,MESSAGE:.status.message
kubectl -n hello-world get rollout hello-world -o jsonpath='{.status.history[0].bakeStatus}: {.status.history[0].bakeStatusMessage}{"\n"}'NAME STATUS MESSAGE
hello-world Healthy Kustomization and all managed resources are healthy
InProgress: Bake started, monitoring for errors.A failed deploy lists the checks that failed it in status.history[0].failedHealthChecks.
The rollout page’s Health checks card lists every check the Rollout selects and its state:


Troubleshoot
| Symptom | Cause | Fix |
|---|---|---|
| Bake never starts | A selected check stays Pending or Unhealthy | Read its status.message; set deployTimeout so the deploy fails instead of waiting |
| New releases are not deployed | DeploymentBlocked=True, reason UnhealthyHealthChecks | Fix the failing check, or deploy a version by hand |
New releases are not deployed, and no check is Unhealthy | The last deploy failed (bakeStatus Failed) | Retry it, set rollout.kuberik.com/, or pin a version |
| A check never changes | No controller handles its spec.class | Use kustomization, or install datadog-controller for the datadog classes and prometheus-controller for prometheus-alert |
Next steps
- Integrations Flux Let Kuberik choose the version Flux applies, through a Kustomization substitute or an OCIRepository tag, and gate deploys on Kustomization health.
- Integrations Datadog Fail a deploy when a Datadog monitor alerts, and hold deploys while a Datadog incident is open.
- Ship releases Roll Out with a Canary Shift traffic to a new version in steps, with a bake time and a test Job holding each step.