Deployment Dependency

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

Terraform
API

resource "ctrlplane_policy" "api_requires_database" {
  name     = "API Requires Database"
  selector = "deployment.name == 'api-service'"

  deployment_dependency {
    depends_on_selector = "deployment.name == 'database-migration'"
  }
}

curl -X POST https://api.ctrlplane.com/v1/workspaces/{workspaceId}/policies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Requires Database",
    "selector": "deployment.name == '\''api-service'\''",
    "rules": [
      {
        "deploymentDependency": {
          "dependsOn": "deployment.name == '\''database-migration'\''"
        }
      }
    ]
  }'

Properties

deploymentDependency.dependsOn

string

required

CEL expression to match upstream release targets that must exist before this deployment can proceed. The expression can reference both deployment and version properties of the currently deployed upstream release.

Available CEL Variables

The dependsOn expression is evaluated against each release target on the same resource that has a successful release. Both deployment.* and version.* fields are available:

Variable	Type	Description
`deployment.id`	string	Deployment ID
`deployment.name`	string	Deployment name
`deployment.slug`	string	Deployment slug
`deployment.metadata`	map	Deployment metadata key-value pairs
`version.id`	string	Deployed version ID
`version.tag`	string	Version tag (e.g. `v2.1.0`)
`version.name`	string	Version name
`version.status`	string	Version status
`version.metadata`	map	Version metadata key-value pairs
`version.createdAt`	timestamp	When the version was created

How It Works

Release created - A new version is released for a deployment with dependency rules.
Same-resource resolution - Ctrlplane finds all release targets on the same resource as the current target.
Version resolution - For each release target, Ctrlplane resolves the deployment and its currently deployed version (from the latest successful job).
CEL evaluation - The dependsOn expression is evaluated against each {deployment, version} pair.
Deployment allowed - If at least one upstream release target matches the selector, the deployment can proceed.

Common Patterns

Database Before API

Ensure database migrations complete before API deploys:

Terraform
API

resource "ctrlplane_policy" "api_requires_db" {
  name     = "API Requires DB Migration"
  selector = "deployment.name == 'api-service'"

  deployment_dependency {
    depends_on_selector = "deployment.name == 'database-migration'"
  }
}

{
  "name": "API Requires DB Migration",
  "selector": "deployment.name == 'api-service'",
  "rules": [
    {
      "deploymentDependency": {
        "dependsOn": "deployment.name == 'database-migration'"
      }
    }
  ]
}

Service Dependency Chain

Create a chain of dependencies:

Terraform
API

resource "ctrlplane_policy" "api_depends_on_db" {
  name     = "API Depends on DB"
  selector = "deployment.name == 'api-service'"

  deployment_dependency {
    depends_on_selector = "deployment.name == 'database-migration'"
  }
}

resource "ctrlplane_policy" "frontend_depends_on_api" {
  name     = "Frontend Depends on API"
  selector = "deployment.name == 'frontend'"

  deployment_dependency {
    depends_on_selector = "deployment.name == 'api-service'"
  }
}

[
  {
    "name": "API Depends on DB",
    "selector": "deployment.name == 'api-service'",
    "rules": [
      {
        "deploymentDependency": {
          "dependsOn": "deployment.name == 'database-migration'"
        }
      }
    ]
  },
  {
    "name": "Frontend Depends on API",
    "selector": "deployment.name == 'frontend'",
    "rules": [
      {
        "deploymentDependency": {
          "dependsOn": "deployment.name == 'api-service'"
        }
      }
    ]
  }
]

Shared Library Dependencies

Ensure shared libraries are deployed before dependent services:

resource "ctrlplane_policy" "services_require_shared_lib" {
  name     = "Services Require Shared Lib"
  selector = "deployment.metadata['usesSharedLib'] == 'true'"

  deployment_dependency {
    depends_on_selector = "deployment.metadata['type'] == 'shared-library'"
  }
}

Version-Scoped Dependencies

Require a specific version range of an upstream deployment:

Terraform
API

resource "ctrlplane_policy" "api_requires_db_v2" {
  name     = "API Requires DB Migration v2"
  selector = "deployment.name == 'api-service'"

  deployment_dependency {
    depends_on_selector = "deployment.name == 'database-migration' && version.tag.startsWith('v2.')"
  }
}

{
  "name": "API Requires DB Migration v2",
  "selector": "deployment.name == 'api-service'",
  "rules": [
    {
      "deploymentDependency": {
        "dependsOn": "deployment.name == 'database-migration' && version.tag.startsWith('v2.')"
      }
    }
  ]
}

Version Metadata Filtering

Depend on an upstream deployment running a version with specific metadata:

resource "ctrlplane_policy" "frontend_requires_stable_api" {
  name     = "Frontend Requires Stable API"
  selector = "deployment.name == 'frontend'"

  deployment_dependency {
    depends_on_selector = "deployment.name == 'api-service' && version.metadata.channel == 'stable'"
  }
}

Infrastructure First

Deploy infrastructure changes before application updates:

resource "ctrlplane_policy" "app_requires_infrastructure" {
  name     = "App Requires Infrastructure"
  selector = "deployment.metadata['type'] == 'application'"

  deployment_dependency {
    depends_on_selector = "deployment.metadata['type'] == 'infrastructure'"
  }
}

Multi-Service Dependency

Depend on multiple services using CEL in operator:

resource "ctrlplane_policy" "gateway_requires_services" {
  name     = "Gateway Requires Backend Services"
  selector = "deployment.name == 'api-gateway'"

  deployment_dependency {
    depends_on_selector = "deployment.name in ['auth-service', 'user-service', 'billing-service']"
  }
}

Combining with Other Rules

With Environment Progression

Terraform
API

resource "ctrlplane_policy" "api_full_gates" {
  name     = "API Full Gates"
  selector = "deployment.name == 'api-service' && environment.name == 'production'"

  deployment_dependency {
    depends_on_selector = "deployment.name == 'database-migration'"
  }

  environment_progression {
    depends_on_environment_selector = "environment.name == 'staging'"
  }

  any_approval {
    min_approvals = 1
  }
}

{
  "name": "API Full Gates",
  "selector": "deployment.name == 'api-service' && environment.name == 'production'",
  "rules": [
    {
      "deploymentDependency": {
        "dependsOn": "deployment.name == 'database-migration'"
      }
    },
    {
      "environmentProgression": {
        "dependsOnEnvironmentSelector": "environment.name == 'staging'"
      }
    },
    {
      "anyApproval": { "minApprovals": 1 }
    }
  ]
}

With Gradual Rollout

resource "ctrlplane_policy" "frontend_controlled_release" {
  name     = "Frontend Controlled Release"
  selector = "deployment.name == 'frontend'"

  deployment_dependency {
    depends_on_selector = "deployment.name == 'api-service'"
  }

  gradual_rollout {
    rollout_type        = "linear"
    time_scale_interval = 300
  }
}

Best Practices

Dependency Design

Pattern	Use Case
Database → API	Schema changes before code
API → Frontend	API contracts before consumers
Infrastructure → App	Platform changes before workloads
Shared lib → Services	Common code before dependents
Config → Application	Configuration 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:

Check the dependency deployment’s status
Verify the CEL expression matches the expected deployment
Remember that dependencies are resolved per-resource — the upstream deployment must have a successful release on the same resource
Review the dependency deployment’s success status

Circular Dependencies

If you encounter circular dependency errors:

Review the dependency graph
Break the cycle by removing one dependency
Consider using environment progression instead

Next Steps

Policies Overview - Learn about policy structure
Environment Progression - Cross-environment gates
Gradual Rollouts - Control deployment pace

Deployment

Job Agents

Policies

Verification

Deployment Dependency

Overview

Why Use Deployment Dependencies?

Configuration

Properties

Available CEL Variables

How It Works

Common Patterns

Database Before API

Service Dependency Chain

Shared Library Dependencies

Version-Scoped Dependencies

Version Metadata Filtering

Infrastructure First

Multi-Service Dependency

Combining with Other Rules

With Environment Progression

With Gradual Rollout

Best Practices

Dependency Design

Recommendations

Anti-Patterns

Troubleshooting

Deployment Blocked

Circular Dependencies

Next Steps

Deployment

Job Agents

Policies

Verification

Documentation Index

​Overview

​Why Use Deployment Dependencies?

​Configuration

​Properties

​Available CEL Variables

​How It Works

​Common Patterns

​Database Before API

​Service Dependency Chain

​Shared Library Dependencies

​Version-Scoped Dependencies

​Version Metadata Filtering

​Infrastructure First

​Multi-Service Dependency

​Combining with Other Rules

​With Environment Progression

​With Gradual Rollout

​Best Practices

​Dependency Design

​Recommendations

​Anti-Patterns

​Troubleshooting

​Deployment Blocked

​Circular Dependencies

​Next Steps

Overview

Why Use Deployment Dependencies?

Configuration

Properties

Available CEL Variables

How It Works

Common Patterns

Database Before API

Service Dependency Chain

Shared Library Dependencies

Version-Scoped Dependencies

Version Metadata Filtering

Infrastructure First

Multi-Service Dependency

Combining with Other Rules

With Environment Progression

With Gradual Rollout

Best Practices

Dependency Design

Recommendations

Anti-Patterns

Troubleshooting

Deployment Blocked

Circular Dependencies

Next Steps