Concepts

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
  1. How a gate holds a release
  2. Schedules
  3. Manual approvals
  4. Service dependencies
  5. Health checks
  6. The GatesPassing condition
  7. When gates are skipped
  8. Related
Every gate is a RolloutGate; the Rollout deploys only what every gate lets throughFour writers make RolloutGates: a RolloutSchedule sets passing (schedule-gate-…), an ApprovalPolicy with RolloutApprovals sets allowedVersions (approval-gate-…), a RolloutDependency sets allowedVersions to the releases whose required contract its provider serves (dependency-<name>), and you or an Environment write one directly. The Rollout reads them all and reports the GatesPassing condition: AllGatesPassing, SomeGatesBlocking or NoAllowedVersions. Separately, an Unhealthy HealthCheck holds automatic deploys with DeploymentBlocked=True.RolloutSchedulea time windowpassingApprovalPolicy+ RolloutApprovalallowedVersionsRolloutDependencyprovider serves contractallowedVersionsYou or an Environmentwrite one directlyeither fieldRolloutGateschedule-gate-…approval-gate-…dependency-<name>your name, ghd-…RolloutGatesPassingAllGatesPassingSomeGatesBlockingNoAllowedVersionsHealthCheckUnhealthyDeploymentBlocked=True Every gate is a RolloutGate; the Rollout deploys only what every gate lets throughFour writers make RolloutGates: a RolloutSchedule sets passing (schedule-gate-…), an ApprovalPolicy with RolloutApprovals sets allowedVersions (approval-gate-…), a RolloutDependency sets allowedVersions to the releases whose required contract its provider serves (dependency-<name>), and you or an Environment write one directly. The Rollout reads them all and reports the GatesPassing condition: AllGatesPassing, SomeGatesBlocking or NoAllowedVersions. Separately, an Unhealthy HealthCheck holds automatic deploys with DeploymentBlocked=True.RolloutSchedulea time windowpassingApprovalPolicy+ RolloutApprovalallowedVersionsRolloutDependencyprovider servescontractallowedVersionsYou, Environmentwrite one directlyeither fieldeach writes oneRolloutGateschedule-gate-…approval-gate-…dependency-<name>your name, ghd-…RolloutGatesPassingAllGatesPassingSomeGatesBlockingNoAllowedVersionsHealthCheckUnhealthyDeploymentBlocked=True
Every gate is a RolloutGate; a release deploys only when every gate lets it through, and an Unhealthy HealthCheck holds it on a separate path.

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.

rolloutgate.yamlYAML
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 deploy

A 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.

ReasonStatusMeaning
AllGatesPassingTrueA waiting release passes every gate, or no release is waiting (even behind a closed gate).
SomeGatesBlockingFalseA release is waiting and a gate has passing: false.
NoAllowedVersionsFalseReleases are waiting, but none is in every gate’s allowedVersions.
GatesBypassedTrueA 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 Unhealthy hold is skipped too, because nothing runs yet.
  • On a deploy by hand. Setting spec.wantedVersion or the rollout.kuberik.com/force-deploy annotation skips the gates and the Unhealthy hold.
  • For one bypassed build. The rollout.kuberik.com/bypass-gates annotation 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. Add rollout.kuberik.com/bypass-gates-only with 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