In a microservice architecture, deploy ordering isn't just an operational nicety — it's the difference between a clean rollout and a cascade of 503s. When service A calls service B which calls service C, deploying them in alphabetical order (or in CI commit order) is a guaranteed path to contract violations at runtime. Getting the ordering right requires understanding the call graph before the deploy starts, not after the incident happens.
This post is about dependency-aware rollout sequencing: how to model it, how Kubestead enforces it, and where the approach has real limitations you need to plan around.
The Dependency Cascade Problem
The canonical failure mode: you're deploying a new version of your user authentication service that changes its response schema. The services that call it — 4 of them, scattered across the mesh — haven't been updated yet to handle the new schema. You deploy auth first. Downstream services start receiving 200 responses with a payload they don't recognize. Half of them silently fail on deserialization. The cascade hits your API gateway three minutes later.
The correct ordering was to deploy the downstream consumers first (updating them to handle both old and new schema), then deploy the auth service. The downstream services are deployed in a backward-compatible state — they can talk to the old auth and the new auth. Once auth is promoted, the downstream services use the new schema and the old fallback path is unreachable.
This is the "consumer before producer" ordering principle for breaking changes. It requires knowing which services are consumers and which are producers for any given deploy — information that typically lives in a service catalog or dependency graph, not in the deployment manifest itself.
How Kubestead Models Dependencies
Kubestead's rollout spec includes an optional dependsOn block that declares deploy-time ordering constraints. This is not a runtime dependency map — it's a deploy sequencing hint:
rollout:
name: auth-service
dependsOn:
- service: user-profile-service
requiredPhase: canary-promoted # wait until canary is at 100%
- service: notification-service
requiredPhase: canary-healthy # wait until canary passes analysisWhen a multi-service rollout plan is submitted, Kubestead's orchestrator constructs a directed acyclic graph of the deploy sequence, checks for cycles, and schedules each service's rollout only after its dependencies have cleared the specified phase. The requiredPhase options are: canary-started, canary-healthy (analysis passing), canary-promoted (at 100%), and stable (complete rollout window elapsed).
For a team deploying a coordinated change across 12 services, this reduces a potentially dangerous simultaneous rollout to a serialized sequence that respects the call graph. The total deploy time is longer, but the risk of cross-service contract violations is eliminated.
The Hard Case: Circular Dependencies
Real service graphs have cycles. Service A calls Service B, Service B calls Service A — a common pattern in service meshes where services coordinate on shared state. A strict dependency-ordered deploy can't sequence a cycle without splitting the change across multiple deployments.
The right approach for cyclic dependencies is the same as for database schema migrations: expand-and-contract. Deploy version N+1 of Service A that handles both the old and new protocol. Deploy version N+1 of Service B that also handles both. Now both services can communicate in either mode. Then deploy version N+2 of both services that drops the old protocol fallback. The cyclic dependency is resolved by making each intermediate version backward-compatible.
This is not a Kubestead-specific pattern — it applies to any deployment system. Kubestead will detect a cycle in the dependsOn graph and surface it as a validation error before the rollout starts, requiring you to restructure the deployment plan. That's the correct behavior: fail at plan time, not at deploy time.
Parallel vs. Serial Ordering
Not all multi-service deploys need strict serialization. If you're deploying 8 independent microservices with no cross-service contract changes in the same release, there's no reason to serialize them. Parallel canary rollouts across independent services reduce total deploy time significantly — 8 services in parallel takes roughly the same time as 1 service.
Kubestead supports mixed ordering: services with no declared dependencies run in parallel; services with declared dependsOn relationships run in the order the graph specifies. A typical large deploy might run 6 services in parallel, then gate 2 services on the completion of specific predecessors, then run 4 more in parallel. The orchestrator handles this natively — you don't have to manage the scheduling manually.
When the Dependency Graph Is Wrong
The limitation worth naming directly: Kubestead enforces the dependency ordering you declare — it doesn't automatically discover the correct ordering from your service mesh topology. If your declared dependsOn graph is incomplete or wrong, the rollout will proceed in the order you specified, even if that order is incorrect.
Building the correct dependency graph requires investing in service catalog tooling — whether that's a dedicated catalog (Backstage, or a homegrown service registry) or a dynamic analysis of your mesh traffic patterns. The dependency graph should be derived from observed API contracts and call patterns, not written from memory by the engineer doing the deploy.
We're not suggesting Kubestead solves service catalog discovery — it doesn't. It enforces the ordering you provide. The investment in accurate service graph documentation is a prerequisite for dependency-aware deploy sequencing to be meaningful.
Rollback Semantics Across Dependent Services
When a rollback occurs mid-sequence — say, Service B's canary triggers rollback after Service A has already promoted to 100% — the orchestrator needs to make a decision about Service A. Should Service A also roll back?
The answer depends on whether Service A's new version is compatible with Service B's old version. If it is (because the change was designed with the backward-compatibility principle), Service A can stay at the new version and Service B's rollback doesn't cascade. If it isn't, the rollback must propagate upstream.
Kubestead's rollbackPropagation setting on the dependsOn block lets you declare this explicitly: propagate: true means a downstream rollback triggers upstream rollback; propagate: false means rollbacks are isolated. The default is false — isolation — because most changes that follow the backward-compatibility principle don't need cascaded rollbacks.