Release Targets

A Release Target is the combination of a Deployment, Environment, and Resource. It represents a specific place where a deployment version can be released.

Understanding Release Targets

The core formula:

Deployment × Environment × Resource = Release Target

Example

Given:

Deployment: API Service
Environment: Production (matches 2 resources)
- Resource 1: prod-cluster-us-east
- Resource 2: prod-cluster-us-west

Release Targets Created:

API Service → Production → prod-cluster-us-east
API Service → Production → prod-cluster-us-west

Each release target can independently receive deployment versions.

How Release Targets are Created

Release targets are created automatically based on selectors:

1. Environment Selector Matches Resources

Environment defines a resource selector:

type: Environment
name: Production
resourceSelector: resource.metadata["environment"] == "production"

This matches all resources with metadata.environment = "production".

2. Deployment Selector Further Filters (Optional)

Deployment can have an additional resource selector:

type: Deployment
name: API Service
resourceSelector: resource.kind == "KubernetesCluster"

This limits the deployment to only Kubernetes clusters.

3. Intersection Creates Release Targets

The final set of resources is the intersection of:

Resources matched by environment selector
Resources matched by deployment selector (if present)

Example Calculation:

Environment "Production" matches:
  - prod-k8s-cluster-1 (kind: kubernetes-cluster, env: production)
  - prod-k8s-cluster-2 (kind: kubernetes-cluster, env: production)
  - prod-vm-server-1 (kind: vm, env: production)

Deployment "API Service" selector (kind: kubernetes-cluster):
  - prod-k8s-cluster-1 ✓
  - prod-k8s-cluster-2 ✓
  - prod-vm-server-1 ✗ (not a kubernetes-cluster)

Release Targets Created:
  1. API Service → Production → prod-k8s-cluster-1
  2. API Service → Production → prod-k8s-cluster-2

Release Target Properties

id: rt_abc123
deploymentId: dep_api
environmentId: env_prod
resourceId: res_cluster1
key: dep_api:env_prod:res_cluster1
createdAt: "2024-01-15T10:00:00Z"

key

Unique identifier combining deployment, environment, and resource IDs. Format: {deploymentId}:{environmentId}:{resourceId} This key is used to track which version is currently deployed to each target.

Release Target Lifecycle

Creation

Release targets are created when:

A new deployment is created (targets created for all matching environments and resources)
A new environment is created (targets created for all deployments and matching resources)
A new resource is created that matches existing environment selectors (targets created for all deployments)

Deletion

Release targets are deleted when:

The deployment is deleted
The environment is deleted
The resource is deleted or no longer matches the selectors

Dynamic Updates

As resources are added, updated, or removed:

Resource metadata changes → Release targets re-evaluated
Resource matches environment selector → New release targets created
Resource stops matching → Release targets removed

Viewing Release Targets

Via Web UI

Navigate to your deployment
Click “Release Targets” tab
See all targets with current deployed versions

Via CLI

# List release targets for a deployment
ctrlc api get release-targets --deployment {deploymentId}

Response:

releaseTargets:
  - id: rt_abc123
    deployment:
      id: dep_api
      name: API Service
    environment:
      id: env_prod
      name: Production
    resource:
      id: res_cluster1
      name: Production US East Cluster
      identifier: k8s-prod-use1
    currentRelease:
      versionTag: v1.2.3
      status: completed

Release Target Matrix

Think of release targets as a 3D matrix:

                    Resources
                 ┌─────┬─────┬─────┐
                 │ R1  │ R2  │ R3  │
    ┌────────────┼─────┼─────┼─────┤
    │ Dev        │ RT  │ RT  │ RT  │ Environments
    │ Staging    │ RT  │ RT  │ RT  │
    │ Production │ RT  │ RT  │ RT  │
    └────────────┴─────┴─────┴─────┘
                    ↑
               Deployment

Each cell “RT” is a release target. For multiple deployments, this becomes a 3D cube:

          Deployments (layers)
               ↓
        [API] [Frontend] [Worker]
         ↓       ↓          ↓
    Environment × Resource matrices

Release Target States

While release targets don’t have an explicit “status” field, their state is determined by their current release:

No Release

Target exists but no version has been deployed yet.

Active Release

A version is currently being deployed (job in progress).

Completed Release

A version is successfully deployed (job completed).

Failed Release

Latest deployment attempt failed.

Pending Release

A release exists but is waiting for approval/policies.

Deployment Targeting Strategies

Strategy 1: Broad Matching

Environment matches many resources, deployment doesn’t filter:

# Environment matches all production resources
type: Environment
name: Production
resourceSelector: resource.metadata["environment"] == "production"

# Deployment (no selector)
# → Deploys to ALL production resources
type: Deployment
name: Monitoring Agent
# resourceSelector: not specified

Result: Deployment goes to every production resource. Use Case: Services that should run everywhere (monitoring agents, logging).

Strategy 2: Deployment-Level Filtering

Deployment limits which resources it can target:

# Environment
type: Environment
name: Production
resourceSelector: resource.metadata["environment"] == "production"

# Deployment filters to Kubernetes only
type: Deployment
name: API Service
resourceSelector: resource.kind == "KubernetesCluster"

Result: Deployment only goes to production Kubernetes clusters. Use Case: Platform-specific deployments (containers vs. VMs).

Strategy 3: Fine-Grained Environments

Create specific environments for precise targeting:

# Environment: Production Kubernetes US East
type: Environment
name: Production Kubernetes US East
resourceSelector: >-
  resource.metadata["environment"] == "production" &&
  resource.metadata["region"] == "us-east-1" &&
  resource.kind == "KubernetesCluster"

Result: Very specific set of release targets. Use Case: Region-specific deployments, gradual rollouts.

Release Target Locking

Release targets can be locked to prevent new deployments:

ctrlc api lock release-target {releaseTargetId} --reason "Maintenance window"

To unlock:

ctrlc api unlock release-target {releaseTargetId}

Use Cases:

Maintenance windows
Incident response (freeze deployments)
Testing/debugging (keep specific version)

Locked targets won’t receive new deployments until unlocked.

Querying Release Targets

By Deployment

ctrlc api get release-targets --deployment {deploymentId}

Shows all targets for a specific deployment.

By Environment

ctrlc api get release-targets --environment {environmentId}

Shows all targets in a specific environment.

By Resource

ctrlc api get release-targets --resource {resourceId}

Shows all targets for a specific resource (all deployments).

With Filters

ctrlc api get release-targets \
  --deployment dep_api \
  --environment env_prod \
  --status completed

Release Target Count Estimates

Before creating a deployment, estimate how many release targets will be created:

ctrlc api estimate-targets \
  --system sys_abc \
  --selector 'resource.kind == "KubernetesCluster"'

Response:

environments:
  - name: Development
    matchingResources: 1
    releaseTargets: 1
  - name: Production
    matchingResources: 3
    releaseTargets: 3
totalReleaseTargets: 4

Common Patterns

Pattern 1: Environment-Per-Region

# regional-setup.yaml
---
type: Deployment
name: API Service
slug: api-service
jobAgent:
  ref: kubernetes-agent
---
type: Environment
name: Production US East
resourceSelector: >-
  resource.metadata["environment"] == "production" &&
  resource.metadata["region"] == "us-east-1"
---
type: Environment
name: Production US West
resourceSelector: >-
  resource.metadata["environment"] == "production" &&
  resource.metadata["region"] == "us-west-2"

ctrlc apply -f regional-setup.yaml

Release Targets: API Service gets separate targets per region. Benefit: Independent regional deployments, gradual rollout by region.

Pattern 2: Tiered Resources

# tiered-setup.yaml
---
type: Deployment
name: Critical Service
slug: critical-service
resourceSelector: resource.metadata["tier"] == "critical"
jobAgent:
  ref: kubernetes-agent
---
type: Deployment
name: Standard Service
slug: standard-service
resourceSelector: resource.metadata["tier"] == "standard"
jobAgent:
  ref: kubernetes-agent
---
type: Environment
name: Production
resourceSelector: resource.metadata["environment"] == "production"

ctrlc apply -f tiered-setup.yaml

Release Targets: Services only deploy to appropriate tier resources. Benefit: Resource isolation, cost optimization.

Pattern 3: Canary Deployments

# canary-setup.yaml
---
type: Deployment
name: API Service
slug: api-service
jobAgent:
  ref: kubernetes-agent
---
type: Environment
name: Production Canary
resourceSelector: >-
  resource.metadata["environment"] == "production" &&
  resource.metadata["canary"] == "true"
---
type: Environment
name: Production Stable
resourceSelector: >-
  resource.metadata["environment"] == "production" &&
  resource.metadata["canary"] != "true"

ctrlc apply -f canary-setup.yaml

Release Targets: Separate targets for canary vs. stable. Benefit: Test new versions on canary before rolling out to stable.

Best Practices

Resource Metadata Design

Design resource metadata with targeting in mind:

# Good resource metadata
metadata:
  environment: production
  region: us-east-1
  zone: us-east-1a
  tier: critical
  team: platform
  canary: "false"

This allows flexible targeting across multiple dimensions.

Selector Simplicity

Prefer Simple Selectors:

resourceSelector: resource.metadata["environment"] == "production"

Over Complex Ones:

resourceSelector: >-
  (resource.metadata["environment"] == "production" ||
   resource.metadata["environment"] == "prod") &&
  resource.metadata["tier"] != "deprecated" && ...

Complex selectors are harder to understand and maintain.

Validate Target Count

Before deploying:

Check estimated release target count
Verify targets match expectations
Test in lower environment first

Monitor Release Targets

Track release target creation/deletion events
Alert on unexpected target count changes
Review targets when resources are added/updated

Troubleshooting

Too many release targets created

Review environment resource selectors
Check if deployment needs a resource selector to filter
Verify resource metadata is correct

Expected targets not created

Check environment selector matches resources
Verify deployment selector (if present) isn’t too restrictive
Ensure deployment and environment are in same system
Check resources exist and aren’t deleted

Targets created for wrong resources

Review selector logic (AND vs. OR)
Check resource metadata matches expectations
Test selectors with query API before applying

Release target disappeared

Check if resource was deleted
Verify resource still matches environment selector
Check if resource metadata changed

Next Steps

Releases and Jobs - How versions deploy to targets
Selectors - Master the selector syntax
Environments - Create and configure environments
Policies - Control which targets receive deployments

​Understanding Release Targets

​Example

​How Release Targets are Created

​1. Environment Selector Matches Resources

​2. Deployment Selector Further Filters (Optional)

​3. Intersection Creates Release Targets

​Release Target Properties

​key

​Release Target Lifecycle

​Creation

​Deletion

​Dynamic Updates

​Viewing Release Targets

​Via Web UI

​Via CLI

​Release Target Matrix

​Release Target States

​No Release

​Active Release

​Completed Release

​Failed Release

​Pending Release

​Deployment Targeting Strategies

​Strategy 1: Broad Matching

​Strategy 2: Deployment-Level Filtering

​Strategy 3: Fine-Grained Environments

​Release Target Locking

​Querying Release Targets

​By Deployment

​By Environment

​By Resource

​With Filters

​Release Target Count Estimates

​Common Patterns

​Pattern 1: Environment-Per-Region

​Pattern 2: Tiered Resources

​Pattern 3: Canary Deployments

​Best Practices

​Resource Metadata Design

​Selector Simplicity

​Validate Target Count

​Monitor Release Targets

​Troubleshooting

​Too many release targets created

​Expected targets not created

​Targets created for wrong resources

​Release target disappeared

​Next Steps