Gradual Rollouts

Gradual rollouts allow you to control the pace of deployments across multiple release targets. Instead of deploying to all targets simultaneously, you can stagger deployments over time to reduce risk and catch issues early.

Overview

When deploying to multiple targets (e.g., multiple Kubernetes clusters in production), gradual rollouts let you:

Reduce blast radius - If something goes wrong, only a subset of targets are affected
Catch issues early - Problems surface in early batches before full rollout
Control timing - Space out deployments to manage load and monitoring

Configuration

Terraform
API

resource "ctrlplane_policy" "production_rollout" {
  name     = "Production Rollout"
  selector = "environment.name == 'production'"

  gradual_rollout {
    rollout_type        = "linear"
    time_scale_interval = 300
  }
}

curl -X POST https://api.ctrlplane.com/v1/workspaces/{workspaceId}/policies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Rollout",
    "selector": "environment.name == '\''production'\''",
    "rules": [
      {
        "gradualRollout": {
          "rolloutType": "linear",
          "timeScaleInterval": 300
        }
      }
    ]
  }'

Properties

gradualRollout.rolloutType

string

required

The rollout strategy to use:

linear — Deploy to each target at a fixed interval
linear-normalized — Space deployments evenly within the time window

gradualRollout.timeScaleInterval

integer

required

For linear: seconds between each target deployment. For linear-normalized: total seconds to complete the rollout.

Rollout Types

Linear Rollout

Deploy to each target at a fixed interval:

Terraform
API

gradual_rollout {
  rollout_type        = "linear"
  time_scale_interval = 300
}

{
  "gradualRollout": {
    "rolloutType": "linear",
    "timeScaleInterval": 300
  }
}

Example with 5 targets:

t+0m:   Target 1 deployed
t+5m:   Target 2 deployed
t+10m:  Target 3 deployed
t+15m:  Target 4 deployed
t+20m:  Target 5 deployed

Linear Normalized Rollout

Deployments are spaced evenly so that the last target is scheduled at or before the timeScaleInterval:

Terraform
API

gradual_rollout {
  rollout_type        = "linear-normalized"
  time_scale_interval = 600
}

{
  "gradualRollout": {
    "rolloutType": "linear-normalized",
    "timeScaleInterval": 600
  }
}

Example with 5 targets and 10 minute window:

t+0m:   Target 1 deployed
t+2m:   Target 2 deployed
t+4m:   Target 3 deployed
t+6m:   Target 4 deployed
t+8m:   Target 5 deployed

How Rollout Start Time Is Determined

The gradual rollout evaluator determines its start time by looking at other policy rules that must be satisfied first:

Approval rules - Uses the satisfiedAt time when approvals were met
Environment progression rules - Uses the satisfiedAt time when progression criteria were met
Policy skip overrides - Uses the skip creation time
Deployment windows - Allow windows push the start to the window opening; deny windows push the start past the window closing

If no approval or progression rules exist, the rollout starts from the version creation time. The rollout start is the latest time at which all prerequisites were met. Target ordering within a rollout is determined by a consistent hash of the release target key and version ID, ensuring deterministic but varied ordering across different versions.

Common Patterns

Conservative Production Rollout

Long intervals with approval:

resource "ctrlplane_policy" "conservative_rollout" {
  name     = "Conservative Rollout"
  selector = "environment.name == 'production'"

  any_approval {
    min_approvals = 1
  }

  gradual_rollout {
    rollout_type        = "linear"
    time_scale_interval = 900
  }
}

Fast Staging Rollout

Quick rollout for non-production environments:

resource "ctrlplane_policy" "staging_rollout" {
  name     = "Staging Rollout"
  selector = "environment.name == 'staging'"

  gradual_rollout {
    rollout_type        = "linear-normalized"
    time_scale_interval = 120
  }
}

Critical Service Rollout

Extra cautious rollout for critical services:

Terraform
API

resource "ctrlplane_policy" "critical_service_rollout" {
  name     = "Critical Service Rollout"
  selector = "deployment.metadata['tier'] == 'critical' && environment.name == 'production'"

  any_approval {
    min_approvals = 2
  }

  gradual_rollout {
    rollout_type        = "linear"
    time_scale_interval = 1800
  }
}

{
  "name": "Critical Service Rollout",
  "selector": "deployment.metadata['tier'] == 'critical' && environment.name == 'production'",
  "rules": [
    { "anyApproval": { "minApprovals": 2 } },
    {
      "gradualRollout": {
        "rolloutType": "linear",
        "timeScaleInterval": 1800
      }
    }
  ]
}

Best Practices

Timing Guidelines

Environment	Rollout Type	Interval	Notes
QA	linear-normalized	60-120s	Fast feedback
Staging	linear-normalized	120-300s	Reasonable pace
Production	linear	300-900s	Conservative, time to monitor
Critical	linear	900-1800s	Extra time for verification

Recommendations

✅ Use longer intervals for production environments
✅ Combine with verification to catch issues between batches
✅ Use linear-normalized when you have a time constraint
✅ Use linear when you want consistent spacing regardless of target count
✅ Monitor each batch before the next one deploys

Next Steps

Policies Overview - Learn about policy structure
Deployment Window - Time-based deployment control
Version Cooldown - Batch frequent releases

Deployment

Job Agents

Policies

Verification

Gradual Rollouts

Overview

Configuration

Properties

Rollout Types

Linear Rollout

Linear Normalized Rollout

How Rollout Start Time Is Determined

Common Patterns

Conservative Production Rollout

Fast Staging Rollout

Critical Service Rollout

Best Practices

Timing Guidelines

Recommendations

Next Steps

Deployment

Job Agents

Policies

Verification

Documentation Index

​Overview

​Configuration

​Properties

​Rollout Types

​Linear Rollout

​Linear Normalized Rollout

​How Rollout Start Time Is Determined

​Common Patterns

​Conservative Production Rollout

​Fast Staging Rollout

​Critical Service Rollout

​Best Practices

​Timing Guidelines

​Recommendations

​Next Steps

Overview

Configuration

Properties

Rollout Types

Linear Rollout

Linear Normalized Rollout

How Rollout Start Time Is Determined

Common Patterns

Conservative Production Rollout

Fast Staging Rollout

Critical Service Rollout

Best Practices

Timing Guidelines

Recommendations

Next Steps