Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ctrlplane.dev/llms.txt

Use this file to discover all available pages before exploring further.

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 TypeWhat It Does
ApprovalRequires manual sign-off before deploying
Environment ProgressionWaits for staging to succeed before prod
Gradual RolloutDeploys to targets one at a time with delays
Deployment WindowOnly allows deployments during certain hours
VerificationChecks 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 TypeWhat It Does
GitHub ActionsTriggers a workflow dispatch
ArgoCDCreates or syncs an ArgoCD Application
Terraform CloudCreates a workspace and triggers a run
KubernetesApplies 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

ConceptWhat It Is
SystemA workspace grouping related deployments (e.g., “E-commerce”)
ResourceA deployment target (K8s cluster, VM, Lambda function)
EnvironmentA logical stage (dev, staging, prod) that groups resources
DeploymentA service or app you want to deploy
VersionA specific build of a deployment (created by CI)
Release TargetDeployment × Environment × Resource
ReleaseA version being deployed to a release target
JobThe execution task sent to a job agent
Job AgentThe executor (ArgoCD, GitHub Actions, etc.)
PolicyRules 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:
  1. You push code to your main branch
  2. CI builds and creates Version v2.0.0 in Ctrlplane
  3. Ctrlplane plans: “v2.0.0 needs to go to Staging (2 clusters) and Production (3 clusters)”
  4. Staging deploys first (environment progression policy)
  5. Verification runs on staging—checks error rates in Datadog
  6. Staging passes → Production is unblocked
  7. Production requires approval → Team lead approves
  8. Gradual rollout → Deploy to 1 cluster, wait 10 min, next cluster…
  9. Verification runs after each cluster
  10. 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