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
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.
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.
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.
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.paymentsrolloutRef 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 aRolloutGatecan only reference a Rollout in its own namespace. The provider may live elsewhere viaspec.providerRef.namespace. - The provider’s
org.opencontainers.image.versionmust be a semantic version. A git SHA there cannot be ordered against a constraint. - One
RolloutDependencycovers 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.
kubectl get rolloutdependency -n hello-worldNAME ROLLOUT PROVIDER PROVIDED SATISFIED AGE
checkout-needs-payments checkout payments 1.64.0 False 2dstatus.blockedReleases names each held release and the constraint it needs.
kubectl get rolloutdependency checkout-needs-payments -n hello-world -o jsonpath='{.status.blockedReleases}'[{"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.


Once the provider bakes, the consumer follows a few seconds later, unprompted.
Next steps
- Concepts How Gates Work What holds a deploy back: RolloutGates, schedules, approvals, service dependencies and health checks.
- Gate deploys Require a Manual Approval Hold each new build of a Rollout until a person approves it in the dashboard or with kubectl.
- Operate Troubleshoot Match what the dashboard or kubectl shows to its fix, from a blocked release to a roll back.