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 definitions and details for every entity in Ctrlplane. For a
gentler introduction, see 5-Minute Overview.
Entity Overview
System
├── Environments (group resources via selectors)
├── Deployments (what to deploy)
│ └── Versions (specific builds)
└── Resources (deployment targets)
Release Target = Deployment × Environment × Resource
Release = Version deployed to a Release Target
└── Job (executed by Job Agent)
Policy → Rules that govern releases
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 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 represents a service or application you want to deploy.
| 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.
| Agent Type | What It Does |
|---|
| GitHub Actions | Triggers workflow dispatch |
| ArgoCD | Creates/syncs ArgoCD Applications |
| Terraform Cloud | Creates workspaces, triggers runs |
| Kubernetes | Applies manifests directly |
| ArgoWorkflows | Applies an inline workflow or template |
Policy
A Policy defines rules governing when and how deployments happen.
| 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) |
| Environment | Logical stage grouping resources via selectors |
| Deployment | Service/app to deploy |
| 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 | Rules controlling deployments |
| Selector | Query expression matching entities |
Next Steps
