Skip to main content
Deployment dependency rules ensure that one deployment succeeds before another can proceed. Use them to coordinate related services, enforce deployment order across microservices, or manage infrastructure dependencies.

​
Overview

​
Why Use Deployment Dependencies?

Deployment dependency rules help you:
  • Coordinate services - Deploy database before API, API before frontend
  • Manage infrastructure - Infrastructure changes before application updates
  • Enforce order - Shared libraries before dependent services
  • Reduce failures - Prevent cascading failures from out-of-order deploys

​
Configuration

Add a deployment dependency rule to your policy: 
policies:
  - name: api-requires-database
    selectors:
      - deployment: deployment.name == "api-service"
    rules:
      - deploymentDependency:
          dependsOnDeploymentSelector:
            matchLabels:
              name: database-migration

​
Properties

PropertyTypeRequiredDescription
dependsOnDeploymentSelectorSelectorYesSelector for the prerequisite deployment(s)
referencestringNoReference to the dependency entity

​
Common Patterns

​
Database Before API

Ensure database migrations complete before API deploys: 
policies:
  - name: api-requires-db-migration
    selectors:
      - deployment: deployment.name == "api-service"
    rules:
      - deploymentDependency:
          dependsOnDeploymentSelector:
            matchLabels:
              name: database-migration

​
Service Dependency Chain

Create a chain of dependencies: 
policies:
  # API depends on database
  - name: api-depends-on-db
    selectors:
      - deployment: deployment.name == "api-service"
    rules:
      - deploymentDependency:
          dependsOnDeploymentSelector:
            matchLabels:
              name: database-migration

  # Frontend depends on API
  - name: frontend-depends-on-api
    selectors:
      - deployment: deployment.name == "frontend"
    rules:
      - deploymentDependency:
          dependsOnDeploymentSelector:
            matchLabels:
              name: api-service

​
Shared Library Dependencies

Ensure shared libraries are deployed before dependent services: 
policies:
  - name: services-require-shared-lib
    selectors:
      - deployment: deployment.metadata.usesSharedLib == "true"
    rules:
      - deploymentDependency:
          dependsOnDeploymentSelector:
            matchLabels:
              type: shared-library

​
Infrastructure First

Deploy infrastructure changes before application updates: 
policies:
  - name: app-requires-infrastructure
    selectors:
      - deployment: deployment.metadata.type == "application"
    rules:
      - deploymentDependency:
          dependsOnDeploymentSelector:
            matchLabels:
              type: infrastructure

​
Multi-Service Dependency

Depend on multiple services: 
policies:
  - name: gateway-requires-services
    selectors:
      - deployment: deployment.name == "api-gateway"
    rules:
      - deploymentDependency:
          dependsOnDeploymentSelector:
            matchExpression:
              - key: name
                operator: In
                values:
                  - auth-service
                  - user-service
                  - billing-service

​
By Team or Domain

Dependencies based on metadata: 
policies:
  - name: frontend-requires-backend
    selectors:
      - deployment: deployment.metadata.layer == "frontend"
    rules:
      - deploymentDependency:
          dependsOnDeploymentSelector:
            matchLabels:
              layer: backend

​
Dependency Resolution

​
1. Release Created

A new version is released for a deployment with dependency rules.

​
2. Dependency Check

Ctrlplane identifies all deployments matching dependsOnDeploymentSelector.

​
3. Status Evaluation

For each dependency, Ctrlplane checks if the same version (or compatible version) has been successfully deployed.

​
4. Deployment Allowed

Once all dependencies are satisfied, the deployment can proceed.

​
Combining with Other Rules

​
With Environment Progression

policies:
  - name: api-full-gates
    selectors:
      - deployment: deployment.name == "api-service"
      - environment: environment.name == "production"
    rules:
      - deploymentDependency:
          dependsOnDeploymentSelector:
            matchLabels:
              name: database-migration
      - environmentProgression:
          dependsOnEnvironmentSelector:
            matchLabels:
              name: staging
      - approval:
          required: 1

​
With Gradual Rollout

policies:
  - name: frontend-controlled-release
    selectors:
      - deployment: deployment.name == "frontend"
    rules:
      - deploymentDependency:
          dependsOnDeploymentSelector:
            matchLabels:
              name: api-service
      - gradualRollout:
          rolloutType: linear
          timeScaleInterval: 300

​
Best Practices

​
Dependency Design

PatternUse Case
Database → APISchema changes before code
API → FrontendAPI contracts before consumers
Infrastructure → AppPlatform changes before workloads
Shared lib → ServicesCommon code before dependents
Config → ApplicationConfiguration before apps

​
Recommendations

  • ✅ Keep dependency chains short (2-3 levels max)
  • ✅ Use metadata to group related deployments
  • ✅ Document why dependencies exist
  • ✅ Test dependency resolution in staging
  • ✅ Monitor for circular dependency issues

​
Anti-Patterns

  • ❌ Deep dependency chains (> 3 levels)
  • ❌ Circular dependencies (A → B → A)
  • ❌ Over-coupling unrelated services
  • ❌ Using dependencies when environment progression would suffice

​
Troubleshooting

​
Deployment Blocked

If a deployment is blocked waiting for dependencies:
  1. Check the dependency deployment’s status
  2. Verify the selector matches the expected deployment
  3. Ensure the dependency version is compatible
  4. Review the dependency deployment’s success status

​
Circular Dependencies

If you encounter circular dependency errors:
  1. Review the dependency graph
  2. Break the cycle by removing one dependency
  3. Consider using environment progression instead

​
Next Steps