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 provides an overview of the core concepts in Ctrlplane.
The three pillars of Ctrlplane answer the fundamental questions of deployment:
- Deployments define what to deploy and how — the service, its versions, and the job agent that executes the deployment.
- Environments define where to deploy — logical stages that dynamically group resources via selectors.
- Policies define when to deploy — rules like approvals, verification, progression gates, and deployment windows that control timing.
System
├── Deployments (what & how)
│ └── Versions (specific builds)
├── Environments (where)
│ └── Resources (deployment targets)
└── Policies (when)
Release Target = Deployment × Environment × Resource
Release = Version deployed to a Release Target
└── Job (executed by Job Agent)
System
A System is a logical grouping of related deployments, environments, and
resources. Think of it as a workspace for a product or team.
| Property | Description |
|---|
name | Display name |
slug | URL-friendly identifier |
description | What this system encompasses |
Resource
A Resource is a deployment target—the actual infrastructure where your code
runs.
| Property | Description |
|---|
name | Human-readable name |
kind | Type (e.g., KubernetesCluster, AWS/Lambda) |
identifier | Unique identifier |
metadata | Key-value pairs for classification |
config | Resource-specific configuration |
version | Current version/state |
name: prod-us-east-1
kind: KubernetesCluster
identifier: k8s-prod-use1
metadata:
region: us-east-1
environment: production
tier: critical
config:
server: https://k8s.example.com
Environment
An Environment defines where to deploy. It represents a logical
deployment stage (dev, staging, prod) that groups resources using selectors.
| Property | Description |
|---|
name | Environment name |
systemId | Parent system |
resourceSelector | Selector determining which resources belong |
directory | Optional path for hierarchical organization |
name: Production
resourceSelector: resource.metadata["environment"] == "production"
Deployment
A Deployment defines what to deploy and how. It represents a service
or application you want to deploy, along with the job agent configuration that
determines how the deployment is executed.
| Property | Description |
|---|
name | Deployment name |
slug | URL-friendly identifier |
description | What this deployment does |
systemId | Parent system |
resourceSelector | Optional filter for which resources can run this |
jobAgentId | Which job agent executes deployments |
jobAgentConfig | Configuration passed to the job agent |
Version
A Version is a specific build or release of a deployment, typically created
by your CI pipeline.
| Property | Description |
|---|
deploymentId | Parent deployment |
tag | Version identifier (e.g., v1.2.3, sha-abc123) |
name | Optional human-readable name |
status | building, ready, or failed |
metadata | Arbitrary metadata (git commit, build number) |
config | Version-specific configuration |
jobAgentConfig | Overrides deployment’s job agent config |
building — Still being built, won’t be deployedready — Ready for deployment (default for policies)failed — Build failed, won’t be deployed
# CI creates a version after building
curl -X POST ".../deployments/{id}/versions" \
-d '{
"tag": "v1.2.3",
"status": "ready",
"metadata": {"commit": "abc123"}
}'
Release Target
A Release Target is the combination of a Deployment, Environment, and
Resource. It represents a specific place where a deployment can be released.
Release Target = Deployment × Environment × Resource
- Deployment: “API Service”
- Environment: “Production”
- Resource: “us-east-1 cluster”
- Release Target: “API Service on Production/us-east-1”
Automatic creation: Release targets are computed from the intersection of:
- Environment’s resource selector → which resources
- Deployment’s resource selector (if any) → further filtering
Release
A Release is an instance of deploying a specific Version to a Release
Target.
| Property | Description |
|---|
versionId | Which version to deploy |
deploymentId | Which deployment |
environmentId | Which environment |
resourceId | Which resource |
createdAt | When the release was created |
Job
A Job is the actual deployment task executed by a Job Agent.
| Property | Description |
|---|
releaseId | The release this job deploys |
jobAgentId | Which agent executes this job |
status | pending, in_progress, completed, failed |
externalId | External identifier (e.g., GitHub run ID) |
message | Status message or error details |
- Ctrlplane creates job for approved release
- Job agent polls and receives the job
- Agent acknowledges and executes
- Agent updates status as it progresses
- Agent marks completed or failed
Job Agent
A Job Agent is the executor that performs deployments. It bridges Ctrlplane
to your infrastructure.
Policy
A Policy defines when a version is allowed to deploy. Policies are the
rules governing deployment timing—approvals, gates, windows, and verification
that control when releases progress.
| Component | Description |
|---|
name | Policy name |
selectors | Which release targets this policy applies to |
rules | The specific rules to enforce |
| Type | Description |
|---|
| Approval | Requires manual sign-off |
| Environment Progression | Wait for another environment to succeed first |
| Gradual Rollout | Deploy to targets sequentially with delays |
| Deployment Window | Only deploy during certain hours |
| Version Selector | Filter which versions can deploy |
| Version Cooldown | Minimum time between deployments |
| Deployment Dependency | Wait for another deployment to complete |
| Verification | Check metrics after deployment |
- Find all policies matching the target
- Evaluate each rule
- All pass → create job
- Any requires action → release is pending
- Any denies → release is blocked
Selector
Selectors are query expressions used to match resources, environments, or
deployments.
# Match resources in production
resource.metadata["environment"] == "production"
# Match critical deployments in any region
deployment.metadata["tier"] == "critical" &&
resource.metadata["region"] in ["us-east-1", "eu-west-1"]
- Environment resource selectors
- Deployment resource selectors
- Policy target selectors
See Selectors for full syntax.
Variables
Variables provide dynamic configuration for deployments.
| Type | Description |
|---|
| Deployment Variables | Defined per deployment, vary by environment |
| Resource Variables | Defined on resources |
{
"deploymentVariable": "replicas",
"values": [
{ "environmentId": "dev", "value": "1" },
{ "environmentId": "prod", "value": "3" }
]
}
Quick Reference Table
| Entity | What It Is |
|---|
| System | Workspace grouping deployments and environments |
| Resource | Deployment target (cluster, VM, function) |
| Deployment | What & how — service/app to deploy and its agent config |
| Environment | Where — logical stage grouping resources via selectors |
| Version | Specific build of a deployment |
| Release Target | Deployment × Environment × Resource |
| Release | Version being deployed to a release target |
| Job | Execution task sent to a job agent |
| Job Agent | Executor (ArgoCD, GitHub Actions, etc.) |
| Policy | When — rules controlling deployment timing |
| Selector | Query expression matching entities |
Next Steps
