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

# Glossary & Reference

> Complete reference for all Ctrlplane entities and concepts

This page provides definitions and details for every entity in Ctrlplane. For a
gentler introduction, see [5-Minute Overview](/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.

```yaml theme={null}
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.

```yaml theme={null}
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

```bash theme={null}
# 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:

1. Environment's resource selector → which resources
2. 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**:

1. Ctrlplane creates job for approved release
2. Job agent polls and receives the job
3. Agent acknowledges and executes
4. Agent updates status as it progresses
5. 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:

1. Find all policies matching the target
2. Evaluate each rule
3. All pass → create job
4. Any requires action → release is pending
5. Any denies → release is blocked

## Selector

**Selectors** are query expressions used to match resources, environments, or
deployments.

```yaml theme={null}
# 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](/concepts/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                        |

```json theme={null}
{
  "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](/overview) — Understand the flow
* [Quickstart](/quickstart) — Hands-on tutorial
* [Selectors](/concepts/selectors) — Deep dive into selector syntax
* [Policies](/policies/overview) — Configure deployment rules