How Gates Work
A gate decides which releases a Rollout may deploy next. Schedules, approvals and service dependencies all work through one resource, the RolloutGate, while health checks hold deploys their own way.
On this page
How a gate holds a release
A RolloutGate points at one Rollout in its namespace and carries two fields. passing: false holds every release. allowedVersions lists the release tags the gate lets through. If the field is absent, the gate does not filter releases. If the list is empty, nothing gets through.
apiVersion: kuberik.com/v1alpha1
kind: RolloutGate
metadata:
name: release-freeze
namespace: hello-world
spec:
rolloutRef:
name: hello-world
passing: true
allowedVersions: ["1.4.0", "1.4.1"] # only these may deployA release deploys only when every gate of the Rollout passes and every gate that sets allowedVersions lists it. Of the releases that pass, the Rollout deploys the newest. A held Rollout does not poll. It is evaluated again when a gate, a HealthCheck or the release list changes.
You can write gates yourself, or let a controller own them. An Environment promotes a release by writing allowedVersions on its own gate. The sections below cover the controllers that write gates for you.
Schedules
A RolloutSchedule (one namespace) or ClusterRolloutSchedule (namespaces picked by a selector) opens or closes a time window. Its rules match times of day, days of the week or date ranges in an IANA timezone (UTC by default). With the default action Deny, the gate holds while a rule matches. With Allow, it holds while no rule matches. The controller creates one gate per matched Rollout, named schedule-gate-…, and flips its passing field.
Set one up in Set Deployment Windows.
Manual approvals
An ApprovalPolicy (one namespace) or ClusterApprovalPolicy (namespaces picked by a selector) requires a person to approve each release. The controller creates one gate per matched Rollout, named approval-gate-…. Its allowedVersions is the set of versions named by RolloutApproval objects for that Rollout. Approving a version therefore means creating a RolloutApproval with spec.rolloutRef and spec.version. The approval can name a version that does not exist yet.
Set one up in Require a Manual Approval.
Service dependencies
A RolloutDependency holds a consumer Rollout until a provider Rollout serves the contract version the consumer needs. Each consumer release declares its requirement in the com.kuberik.rollout.requires.<contract> OCI annotation. The controller writes the releases it admits to a gate named dependency-<name>, so it holds only the releases whose requirement is unmet. A provider release counts once its bake has succeeded. The dependency’s Satisfied condition reads WaitingForProvider while a release waits, or RequirementUnevaluable when the annotation cannot be parsed.
Set one up in Wait for Service Dependencies.
Health checks
A HealthCheck selected by the Rollout’s healthCheckSelector is not a gate. It holds a deploy in a different way. While any selected HealthCheck reports Unhealthy, automatic deploys stop, and the Rollout’s DeploymentBlocked condition turns True with reason UnhealthyHealthChecks. Pending does not hold anything. The same HealthChecks then judge each deploy during its bake. A failed bake holds automatic deploys until someone acts.
Set them up in Verify with Health Checks.
The GatesPassing condition
The Rollout reports the combined result of its gates in the GatesPassing condition. kubectl get rollout shows it in the Gates column. status.gates lists each gate with its message. Each entry in status.candidates shows gated, and blockedBy lists the gates that hold that release.
| Reason | Status | Meaning |
|---|---|---|
AllGatesPassing | True | A waiting release passes every gate, or no release is waiting (even behind a closed gate). |
SomeGatesBlocking | False | A release is waiting and a gate has passing: false. |
NoAllowedVersions | False | Releases are waiting, but none is in every gate’s allowedVersions. |
GatesBypassed | True | A bypass lets one named build through. |
When gates are skipped
Gates do not hold every deploy.
- On the first deploy. Gates never hold a Rollout’s first deploy, by design: it deploys the newest release the gates allow, or the newest release if they allow none. The
Unhealthyhold is skipped too, because nothing runs yet. - On a deploy by hand. Setting
spec.wantedVersionor therollout.kuberik.com/force-deployannotation skips the gates and theUnhealthyhold. - For one bypassed build. The
rollout.kuberik.com/bypass-gatesannotation lets one named build past the gates once. The build must be a release newer than the deployed one. The controller removes the annotation after the next deploy, whichever build it ships. Addrollout.kuberik.com/bypass-gates-onlywith a comma-separated list of gate names to skip only those gates; the annotations then stay until the named build deploys. A bypass does not skip health checks or a failed bake.
None of these skips the bake. It still waits for the health checks to turn Healthy, and fails on a HealthCheck error or on deployTimeout. The exceptions are a deploy that follows a bake that failed or did not finish, and a deploy by hand made while a HealthCheck is Unhealthy: their bakes ignore health check errors (BakeFailureDisabled).
The Annotations reference lists the exact values.
Related
- Concepts Rollouts How a Rollout picks a version, gates it, deploys it and verifies it during bake time.
- Gate Deploys Hold a deploy until health checks, people, time windows or other services allow it.
- Operate Troubleshoot Match what the dashboard or kubectl shows to its fix, from a blocked release to a roll back.