GeezerVison is showing docs.ctrlplane.dev — 5-Minute Overview - docs
The Core Flow
Every deployment in Ctrlplane follows this flow:
- CI creates a version — After building, your CI tells Ctrlplane about the new version
- Policies are evaluated — Ctrlplane checks if approvals, dependencies, and gates are satisfied
- Job is dispatched — Ctrlplane tells your job agent (ArgoCD, GitHub Actions, etc.) to deploy
- Deployment executes — The job agent performs the actual deployment
- Verification runs — Ctrlplane checks metrics (Datadog, Prometheus, HTTP) to confirm health and can also validate resource presence/status (e.g., newly discovered clusters are visible and ready)
- Promote or rollback — If verification passes, continue; if it fails, roll back
The Key Entities
You only need to understand 5 things:
| Entity | Question It Answers | Example |
|---|
| Resource | What infrastructure exists? | prod-us-east-1 K8s cluster |
| Deployment | What to deploy and how | ”API Gateway” deployed via ArgoCD |
| Environment | Where to deploy | ”Production” = all clusters with env: prod |
| Version | Which build to deploy? | v1.2.3 or sha-abc123 |
| Policy | When to deploy | ”After staging succeeds and SRE approves” |
How They Connect
Deployment × Environment × Resource = Release Target
- API Gateway → Production → us-east-1
- API Gateway → Production → us-west-2
- API Gateway → Production → eu-west-1
Each release target can have its own policies, verification, and rollout timing.
Advanced example: Version v1.2.3 of the “API Gateway” deployment targets the “Production” environment,
which expands to multiple clusters including us-west-2. Ctrlplane creates one release target per cluster,
so each target can be governed independently. A deployment window policy can be scoped to the us-west-2
release target so it only deploys on weekdays before 9 a.m., while other production targets follow their
own timing. When a new version arrives, Ctrlplane waits for that window before dispatching the job for
us-west-2, even if other targets can deploy sooner.
Dynamic Environments
Environments use selectors to automatically include resources:
type: Environment
name: Production
resourceSelector: resource.metadata["env"] == "production"
env: production metadata, it automatically becomes part of the Production environment. No config changes needed.
Policies Define When to Deploy
Policies are the rules that govern when a version is allowed to deploy:
| Policy | What It Does |
|---|
| Approval | Require sign-off before deploying |
| Environment Progression | Wait for staging before prod |
| Gradual Rollout | Deploy to targets one at a time |
| Verification | Check Datadog/Prometheus metrics |
| Deployment Window | Only deploy during certain hours |
type: Policy
name: production-approval-policy
description: Production Approval Policy
selectors:
- environments: environment.metadata['requires-approval'] == 'true'
rules:
- approval:
required: 1
Job Agents Execute Deployments
Ctrlplane doesn’t deploy directly—it tells job agents what to do:
| Agent | What It Does |
|---|
| GitHub Actions | Triggers workflow dispatch |
| ArgoCD | Creates/syncs ArgoCD Applications |
| Terraform Cloud | Triggers Terraform runs |
| Kubernetes | Applies manifests directly |
A Complete Example
- GitHub Actions builds
v1.2.3 and creates a version in Ctrlplane
- Ctrlplane creates a release for staging
- ArgoCD deploys to staging
- Verification checks Datadog metrics
- Staging passes → production release is unblocked
- Production requires approval → team lead approves
- ArgoCD deploys to production
- Verification confirms production is healthy
What’s Next?
Quickstart
Build this pipeline yourself in 15 minutes
Use Cases
See specific deployment scenarios