Skip to main content
Deployment versions are how Ctrlplane tracks what to deploy. Your CI/CD pipeline builds and packages your software, then creates a deployment version in Ctrlplane to trigger deployments across your infrastructure.

​
Key Characteristics of Deployment Versions

  1. Version Identification: Each deployment version has:
    • Tag: A unique identifier within the deployment (e.g., v1.2.3, main-abc123, pr-456)
    • Name: A human-readable name for the version
    • Created timestamp: When the version was registered
  2. Deployment Association: Deployment versions belong to a specific deployment. Each deployment can have many versions over time.
  3. External Build Process: Ctrlplane does not build your software - that’s handled by your existing CI/CD pipelines. Ctrlplane takes over after the build is complete, orchestrating how and where it gets deployed.
  4. Creation Methods: Deployment versions are typically created via:
    • The Ctrlplane REST API (from your CI/CD pipeline)
    • Ctrlplane integrations (e.g., GitHub Actions, GitLab CI)
    • The Ctrlplane UI (for manual deployments)
  5. Configuration Data: Each version can include custom configuration:
    • Docker image tags
    • Git commit SHAs
    • Build artifacts locations
    • Any deployment-specific configuration
  6. Status Tracking: Deployment versions have a status:
    • building: Version is still being prepared
    • ready: Version is ready to be deployed
    • failed: Version build failed
    • rejected: Version was rejected and should not be deployed

​
Version Dependencies

Deployment versions can declare dependencies on specific versions of other deployments. This ensures that services are only deployed when their dependencies are satisfied. Common use cases for version dependencies:
  1. Microservice Dependencies: A frontend service requires a minimum version of a backend API to ensure required endpoints are available.
  2. Infrastructure Requirements: An application requires a specific database version or Kubernetes version range.
  3. Feature Flags: A service version depends on another service having a specific feature enabled.
  4. Breaking Changes: Prevent deployment of incompatible versions across services.

​
How Version Dependencies Work

When creating a deployment version, you can specify dependencies: 
{
  "deploymentId": "frontend-app-id",
  "tag": "v2.0.0",
  "dependencies": [
    {
      "deploymentId": "backend-api-id",
      "versionSelector": {
        "type": "comparison",
        "operator": "greaterThanOrEqual",
        "key": "version",
        "value": "v1.5.0"
      }
    }
  ]
}
Ctrlplane will only deploy frontend-app v2.0.0 to resources where the backend-api deployment is at version v1.5.0 or higher.

​
Dependency Evaluation

Dependencies are evaluated at the release target level. For a version to be deployed to a specific resource in a specific environment, all its dependencies must be satisfied on that same resource. For cross-resource dependencies (e.g., checking if a database is deployed in the same cluster), you can use resource metadata and selectors to define the dependency scope.

​
Dependency Selectors

Version selectors support various comparison operators:
  • Equals: Exact version match
  • Not Equals: Any version except the specified one
  • Greater Than: Semantic version comparison
  • Less Than: Semantic version comparison
  • Regex: Pattern matching on version tags
  • Filters: Complex metadata-based filtering

​
Best Practices

  1. Semantic Versioning: Use semantic versioning for clearer dependency specifications.
  2. Minimum Versions: Prefer specifying minimum versions rather than exact matches for flexibility.
  3. Test Dependencies: Verify dependency chains in non-production environments first.
  4. Document Dependencies: Keep documentation of why specific version dependencies exist.
  5. Circular Dependencies: Avoid circular dependency chains that prevent deployments.