Concepts Overview

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

Example: “E-commerce Platform” system containing API, Frontend, and Payment deployments. When to create a System: One per product, platform, or team boundary.

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

Examples: Kubernetes cluster, EC2 instance, Lambda function, VM. How created: Via Resource Providers (auto-sync from K8s, AWS, GCP) or API.

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

Key concept: Environments are dynamic. When you add a new resource matching the selector, it automatically joins the environment.

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

Examples: “API Service”, “Frontend App”, “Payment Processor”.

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

Status meanings:

building — Still being built, won’t be deployed
ready — 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

Example:

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

Releases do not carry their own status. The state of a release is inferred from the Release Target State — which tracks the desired release, current release, and latest job for each target.

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

Job lifecycle:

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

Policy types:

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

Policy evaluation: When a release target needs 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"]

Used in:

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

How It Works — Understand the flow
Quickstart — Hands-on tutorial
Selectors — Deep dive into selector syntax
Policies — Configure deployment rules

​System

​Resource

​Environment

​Deployment

​Version

​Release Target

​Release

​Job

​Job Agent

​Policy

​Selector

​Variables

​Quick Reference Table

​Next Steps