Skip to main content

​
What is a Deployment?

A deployment in Ctrlplane is:
  1. A Logical Unit: Represents a single service, application, or piece of infrastructure that you want to deploy and manage.
  2. System-Bound: Each deployment belongs to a specific system, which contains multiple environments (e.g., Development, Staging, Production).
  3. Version Manager: Manages multiple deployment versions - each representing a specific iteration of your software (e.g., git commits, docker tags, build numbers).
  4. Job Configuration: Defines how deployment jobs should be executed via job agent configuration.
  5. Resource Selector: Optionally filters which resources within a system can be deployment targets.

​
Key Components of a Deployment

A deployment in Ctrlplane consists of:
  1. Deployment Versions: Individual versions of your software or infrastructure (e.g., v1.2.3, main-abc123). Each version can have:
    • Name and tag for identification
    • Configuration data
    • Job agent specific configuration
    • Status (building, ready, failed, rejected)
    • Dependencies on other deployment versions
  2. Job Agent Configuration: Specifies how jobs should be executed when deploying this deployment, including:
    • Which job agent to use (Kubernetes, GitHub Actions, etc.)
    • Agent-specific configuration (manifests, workflow files, etc.)
  3. Resource Selector: Optional filter to limit which resources can be deployment targets.
  4. Retry and Timeout Settings: Configure automatic retry behavior and job timeouts.

​
How Deployments Work

​
The Release Target Concept

Ctrlplane creates release targets - the junction between a deployment, environment, and resource. A release target represents “what should deployment X be at for resource Y in environment Z?” For example:
  • Deployment: web-app
  • Environment: production
  • Resource: k8s-cluster-us-east
  • Desired Version: v1.2.3
This release target tracks that web-app v1.2.3 should be deployed to k8s-cluster-us-east in the production environment.

​
Deployment Workflow

  1. Create a Deployment: Define a new deployment within a system, specifying its name, job agent configuration, and resource selector.
  2. Push a Deployment Version: When you have a new version to deploy (from your CI/CD pipeline), create a deployment version with a unique tag.
  3. Release Target Generation: Ctrlplane automatically creates release targets for each combination of:
    • The deployment
    • Each environment in the system
    • Each resource matching both the environment’s selector and the deployment’s selector
  4. Policy Evaluation: Policies determine which version should be deployed to each release target based on:
    • Version dependencies
    • Approval requirements
    • Environment progression rules
    • Release channels
  5. Job Creation: When a release target’s desired version changes, Ctrlplane creates a job to deploy that version to the resource.
  6. Job Execution: The job agent executes the deployment job in your CI/CD system.

​
Resource Selection

Deployments can specify a resource selector to control which resources are valid targets. Resources must match both:
  • The environment’s resource selector
  • The deployment’s resource selector (if specified)
This enables use cases like:
  • A frontend deployment that only deploys to web-server resources
  • A database deployment that only targets database resources
  • Region-specific deployments

​
Creating and Managing Deployments

​
Via UI or API

Create deployments through the Ctrlplane UI or REST API, specifying:
  • Name and slug (unique within the system)
  • System ID
  • Job agent and configuration
  • Resource selector (optional)
  • Retry count and timeout settings

​
Example API Request

{
  "name": "Web Application",
  "slug": "web-app",
  "systemId": "550e8400-e29b-41d4-a716-446655440000",
  "jobAgentId": "660e8400-e29b-41d4-a716-446655440000",
  "jobAgentConfig": {
    "manifest": "..."
  },
  "resourceSelector": {
    "type": "comparison",
    "operator": "equals",
    "key": "kind",
    "value": "kubernetes-cluster"
  }
}

​
Creating Deployment Versions

Deployment versions are typically created from your CI/CD pipeline after a successful build: 
curl -X POST https://api.ctrlplane.dev/v1/deployment-versions \
  -H "Content-Type: application/json" \
  -d '{
    "deploymentId": "550e8400-e29b-41d4-a716-446655440000",
    "tag": "v1.2.3",
    "name": "Release 1.2.3",
    "config": {
      "imageTag": "v1.2.3",
      "commitSha": "abc123"
    }
  }'