> ## 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.
# 5-Minute Overview
> Understand Ctrlplane's mental model in 5 minutes
## The Core Flow
Every deployment in Ctrlplane follows this flow:
```mermaid theme={null}
flowchart LR
CI --"1\. create version"--> Ctrlplane
Ctrlplane --"2\. evaluate policies"--> Policies
Policies --"3\. dispatch job"--> JobAgent
JobAgent --"4\. deploy"--> Resource
Resource --"5\. verify"--> Ctrlplane
Ctrlplane --"6\. promote or rollback"--> Next
```
1. **CI creates a version** — After building, your CI tells Ctrlplane about the new version
2. **Policies are evaluated** — Ctrlplane checks if approvals, dependencies, and gates are satisfied
3. **Job is dispatched** — Ctrlplane tells your job agent (ArgoCD, GitHub Actions, etc.) to deploy
4. **Deployment executes** — The job agent performs the actual deployment
5. **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)
6. **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" |
In short: **Deployments** define *what and how*, **Environments** define *where*, and **Policies** define *when*.
### How They Connect
```
Deployment × Environment × Resource = Release Target
```
When you deploy "API Gateway" to "Production" (which has 3 clusters), Ctrlplane creates 3 **release targets**:
* 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:
```yaml theme={null}
type: Environment
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.
```mermaid theme={null}
flowchart TB
subgraph Resources["All Resources"]
R1["us-east-1 cluster
env: production"]
R2["us-west-2 cluster
env: production"]
R3["dev cluster
env: development"]
end
subgraph Envs["Environments"]
Prod["Production"]
Dev["Development"]
end
R1 -.->|"matches"| Prod
R2 -.->|"matches"| Prod
R3 -.->|"matches"| Dev
```
## 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 |
Policies use selectors to target specific releases:
```yaml theme={null}
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 |
This means Ctrlplane works with your existing deployment tooling.
## A Complete Example
```mermaid theme={null}
flowchart TB
subgraph Build["1\. Build"]
CI["GitHub Actions"]
end
subgraph Orchestrate["2\. Orchestrate (Ctrlplane)"]
Version["Version v1.2.3"]
Staging["Staging Release"]
Verify1["Verify"]
Prod["Production Release"]
Approve["Approval Gate"]
Verify2["Verify"]
end
subgraph Execute["3\. Execute"]
ArgoStaging["ArgoCD Staging"]
ArgoProd["ArgoCD Prod"]
end
CI -->|"create version"| Version
Version --> Staging
Staging -->|"dispatch"| ArgoStaging
ArgoStaging -->|"complete"| Verify1
Verify1 -->|"pass"| Prod
Prod --> Approve
Approve -->|"approved"| ArgoProd
ArgoProd -->|"complete"| Verify2
```
1. GitHub Actions builds `v1.2.3` and creates a version in Ctrlplane
2. Ctrlplane creates a release for staging
3. ArgoCD deploys to staging
4. Verification checks Datadog metrics
5. Staging passes → production release is unblocked
6. Production requires approval → team lead approves
7. ArgoCD deploys to production
8. Verification confirms production is healthy
## What's Next?
Build this pipeline yourself in 15 minutes
See specific deployment scenarios