Glossary & Reference

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

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 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 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

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.

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

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)
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

5-Minute Overview — Understand the flow
Quickstart — Hands-on tutorial
Selectors — Deep dive into selector syntax
Policies — Configure deployment rules

​Entity Overview

​System

​Resource

​Environment

​Deployment

​Version

​Release Target

​Release

​Job

​Job Agent

​Policy

​Selector

​Variables

​Quick Reference Table

​Next Steps