How It Works

This page explains the mental model behind Ctrlplane—how the pieces fit together and what happens when you deploy.

The Big Picture

Ctrlplane sits between your CI/CD pipelines and your infrastructure, acting as the orchestration layer that decides when, where, and how deployments happen.

The Flow: What Happens When You Deploy

Step 1: CI Creates a Version

After your CI pipeline builds and tests your code, it creates a Version in Ctrlplane:

curl -X POST ".../deployments/{id}/versions" \
  -d '{"tag": "v1.2.3", "status": "ready"}'

A Version is a specific build of your service—think of it like a Docker image tag or a Git SHA.

Step 2: Ctrlplane Calculates Release Targets

Ctrlplane automatically figures out where this version needs to go by calculating Release Targets:

Release Target = Deployment × Environment × Resource

Example: If your “API Service” deployment targets the “Production” environment, and Production contains 3 Kubernetes clusters, Ctrlplane creates 3 release targets:

API Service → Production → us-east-1 cluster
API Service → Production → us-west-2 cluster
API Service → Production → eu-west-1 cluster

Step 3: Policies Are Evaluated

Before any deployment happens, Ctrlplane evaluates Policies for each release target:

Policy Type	What It Does
Approval	Requires manual sign-off before deploying
Environment Progression	Waits for staging to succeed before prod
Gradual Rollout	Deploys to targets one at a time with delays
Deployment Window	Only allows deployments during certain hours
Verification	Checks metrics after deployment before proceeding

If all policies pass, a Release is created and a Job is dispatched.

Step 4: Job Agent Executes

A Job Agent receives the job and performs the actual deployment. Job agents are the bridge to your infrastructure:

Agent Type	What It Does
GitHub Actions	Triggers a workflow dispatch
ArgoCD	Creates or syncs an ArgoCD Application
Terraform Cloud	Creates a workspace and triggers a run
Kubernetes	Applies manifests directly

Step 5: Verification Runs

After the deployment completes, Verification checks that everything is healthy:

verification:
  metrics:
    - name: error-rate
      provider:
        type: datadog
        query: "sum:errors{service:api}.as_rate()"
      successCondition: result.value < 0.01

If verification passes → the release is marked successful. If verification fails → automatic rollback is triggered.

Key Concepts at a Glance

Concept	What It Is
System	A workspace grouping related deployments (e.g., “E-commerce”)
Resource	A deployment target (K8s cluster, VM, Lambda function)
Environment	A logical stage (dev, staging, prod) that groups resources
Deployment	A service or app you want to deploy
Version	A specific build of a deployment (created by CI)
Release Target	Deployment × Environment × Resource
Release	A version being deployed to a release target
Job	The execution task sent to a job agent
Job Agent	The executor (ArgoCD, GitHub Actions, etc.)
Policy	Rules controlling when/how deployments happen

How Resources and Environments Work Together

Resources are your actual infrastructure—clusters, VMs, functions. Environments are logical groupings that use selectors to dynamically include resources.

# Environment definition
name: Production
resourceSelector: resource.metadata["env"] == "production"

When you add a new cluster with env: production metadata, it automatically becomes part of the Production environment. No config changes needed.

The Inventory: Your Source of Truth

Ctrlplane maintains a real-time Inventory of all your resources:

Synced from providers: Kubernetes, AWS, GCP, or custom scripts
Rich metadata: Region, team, tier, version—whatever you need
Version tracking: See what’s deployed where at any moment
Custom relationships: Model dependencies between resources

This inventory powers the dynamic environment selectors and gives you visibility across your entire infrastructure.

Putting It All Together

Here’s a complete example flow:

You push code to your main branch
CI builds and creates Version v2.0.0 in Ctrlplane
Ctrlplane plans: “v2.0.0 needs to go to Staging (2 clusters) and Production (3 clusters)”
Staging deploys first (environment progression policy)
Verification runs on staging—checks error rates in Datadog
Staging passes → Production is unblocked
Production requires approval → Team lead approves
Gradual rollout → Deploy to 1 cluster, wait 10 min, next cluster…
Verification runs after each cluster
Done → All 5 clusters running v2.0.0

Next Steps

Quickstart

Set up your first deployment pipeline

Core Concepts

Deep dive into each entity

Inventory

Manage your infrastructure resources

Policies

Configure deployment rules

​The Big Picture

​The Flow: What Happens When You Deploy

​Step 1: CI Creates a Version

​Step 2: Ctrlplane Calculates Release Targets

​Step 3: Policies Are Evaluated

​Step 4: Job Agent Executes

​Step 5: Verification Runs

​Key Concepts at a Glance

​How Resources and Environments Work Together

​The Inventory: Your Source of Truth

​Putting It All Together

​Next Steps