Gate deploys

Wait for Service Dependencies

Hold a service until the service it depends on has shipped the version it needs, in every environment, without hand-sequencing deploys.

On this page
  1. Declare the contract on the images
  2. Connect the Rollouts
  3. Know the limits
  4. Check the result
  5. Next steps

Works with Rollouts that take their releases from a ReleaseSource, which reads the contract annotations from the images.

A RolloutDependency connects a consumer Rollout to a provider Rollout. Each consumer release says which provider version it was built against, and the controller admits it only once the provider has successfully deployed a release that satisfies that constraint.

Declare the contract on the images

The dependency lives on the images, not in the manifests. The provider announces the contract version it serves in the standard OCI version annotation, and the consumer adds one annotation per contract it requires.

Terminal
docker buildx build --push -t ghcr.io/acme/payments:rel-64 \
  --annotation "index:org.opencontainers.image.version=1.64.0-64" .
docker buildx build --push -t ghcr.io/acme/checkout:rel-64 \
  --annotation "index:org.opencontainers.image.version=2.64.0-64" \
  --annotation "index:com.kuberik.rollout.requires.payments=^1.64.0" .

The annotation key is com.kuberik.rollout.requires.<contract>. The value is a Masterminds/semver constraint, applied verbatim: ^1.64.0, ~1.64.0, >=1.64.0 <2.0.0 and 1.64.x all work.

A bare version such as 1.64.0 is an exact match, not a floor. A release that tolerates later providers has to say so: publish ^1.64.0.

The -64 suffix is a per-build ordinal. Attach it as a SemVer pre-release identifier so builds of the same triple still sort by build order, and keep org.opencontainers.image.revision as the real git SHA. The controller strips that numeric ordinal before evaluating the constraint. A real pre-release such as 1.64.0-rc.1 is kept and fails ^1.64.0, because the triple has not shipped yet.

Connect the Rollouts

Create one object per consumer and contract, in the consumer’s namespace.

checkout-needs-payments.yamlYAML
apiVersion: kuberik.com/v1alpha1
kind: RolloutDependency
metadata:
  name: checkout-needs-payments
  namespace: hello-world
spec:
  rolloutRef:
    name: checkout
  providerRef:
    name: payments
  contract: payments  # matches com.kuberik.rollout.requires.payments

rolloutRef names the consumer being gated. contract defaults to the provider Rollout’s name, and providerRef.namespace defaults to the dependency’s namespace. Apply the object in every environment that has both Rollouts. Each environment waits on its own copy of the provider: production’s checkout waits for production’s payments, not for staging’s.

The controller compares each consumer release’s requirement with the contract version of the most recent provider deploy whose bake succeeded. It publishes the verdict as a RolloutGate named dependency-<name>, whose allowedVersions lists the admitted releases. A dependency therefore holds back only the releases whose requirement is unmet. Older releases stay deployable, so you can roll back while a newer release waits.

A provider with no bakeTime, deployTimeout or healthCheckSelector records its bake as succeeded the moment the deploy is written, before the workload has rolled out, so its consumers can start before the contract is live. Give every provider health checks, so its consumers wait until the provider is healthy. A bakeTime alone only delays them by a fixed time, because without health checks the bake starts as soon as the deploy is written.

Gates never hold a Rollout’s first deploy: a brand-new consumer deploys the newest release the dependency admits, or the newest release if it admits none.

Know the limits

  • The consumer must be in the same namespace as the RolloutDependency, because a RolloutGate can only reference a Rollout in its own namespace. The provider may live elsewhere via spec.providerRef.namespace.
  • The provider’s org.opencontainers.image.version must be a semantic version. A git SHA there cannot be ordered against a constraint.
  • One RolloutDependency covers one contract. A consumer that requires two services gets two objects.

Check the result

kubectl get shows the version the provider serves and whether any consumer release waits on it.

Terminal
kubectl get rolloutdependency -n hello-world
OutputText
NAME                      ROLLOUT    PROVIDER   PROVIDED   SATISFIED   AGE
checkout-needs-payments   checkout   payments   1.64.0     False       2d

status.blockedReleases names each held release and the constraint it needs.

Terminal
kubectl get rolloutdependency checkout-needs-payments -n hello-world -o jsonpath='{.status.blockedReleases}'
OutputJSON
[{"reason":"ConstraintNotSatisfied","requiredVersion":"^1.66.0","tag":"rel-66"}]

The dashboard shows the same on the rollout’s Gates tab: what the consumer waits on, the version it needs against the version running, and the contract across every environment. The home page and the Environments page name the provider on every held card.

The Gates graph of checkout-api in staging: the development promotion passes, and of 4 gates only the payments-svc dependency holds, because payments-svc runs 2.4.1 where checkout-api needs ^3.0.0; the identity-svc dependency, Business hours and a Release approval by wyatt pass. The checkout-api staging node runs 4.43.0-43 with 4.45.0-45 and 4.44.0-44 held there, and production eu-central waits downstream until staging deploys 4.45.0-45The Gates graph of checkout-api in staging: the development promotion passes, and of 4 gates only the payments-svc dependency holds, because payments-svc runs 2.4.1 where checkout-api needs ^3.0.0; the identity-svc dependency, Business hours and a Release approval by wyatt pass. The checkout-api staging node runs 4.43.0-43 with 4.45.0-45 and 4.44.0-44 held there, and production eu-central waits downstream until staging deploys 4.45.0-45
The provider still runs 2.4.1, so checkout-api holds its newer builds in staging until payments-svc ships 3.0.0.

Once the provider bakes, the consumer follows a few seconds later, unprompted.

Next steps