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

# Gradual Rollouts

> Learn how to use gradual rollouts to control the pace of deployments across multiple release targets.

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

<Tabs>
  <Tab title="Terraform">
    ```hcl theme={null}
    resource "ctrlplane_policy" "production_rollout" {
      name     = "Production Rollout"
      selector = "environment.name == 'production'"

      gradual_rollout {
        rollout_type        = "linear"
        time_scale_interval = 300
      }
    }
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    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
            }
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

## Properties

<ParamField path="gradualRollout.rolloutType" type="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
</ParamField>

<ParamField path="gradualRollout.timeScaleInterval" type="integer" required>
  For `linear`: seconds between each target deployment. For
  `linear-normalized`: total seconds to complete the rollout.
</ParamField>

## Rollout Types

### Linear Rollout

Deploy to each target at a fixed interval:

<Tabs>
  <Tab title="Terraform">
    ```hcl theme={null}
    gradual_rollout {
      rollout_type        = "linear"
      time_scale_interval = 300
    }
    ```
  </Tab>

  <Tab title="API">
    ```json theme={null}
    {
      "gradualRollout": {
        "rolloutType": "linear",
        "timeScaleInterval": 300
      }
    }
    ```
  </Tab>
</Tabs>

**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`:

<Tabs>
  <Tab title="Terraform">
    ```hcl theme={null}
    gradual_rollout {
      rollout_type        = "linear-normalized"
      time_scale_interval = 600
    }
    ```
  </Tab>

  <Tab title="API">
    ```json theme={null}
    {
      "gradualRollout": {
        "rolloutType": "linear-normalized",
        "timeScaleInterval": 600
      }
    }
    ```
  </Tab>
</Tabs>

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

1. **Approval rules** - Uses the `satisfiedAt` time when approvals were met
2. **Environment progression rules** - Uses the `satisfiedAt` time when
   progression criteria were met
3. **Policy skip overrides** - Uses the skip creation time
4. **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:

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

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

<Tabs>
  <Tab title="Terraform">
    ```hcl theme={null}
    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
      }
    }
    ```
  </Tab>

  <Tab title="API">
    ```json theme={null}
    {
      "name": "Critical Service Rollout",
      "selector": "deployment.metadata['tier'] == 'critical' && environment.name == 'production'",
      "rules": [
        { "anyApproval": { "minApprovals": 2 } },
        {
          "gradualRollout": {
            "rolloutType": "linear",
            "timeScaleInterval": 1800
          }
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## 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](./overview) - Learn about policy structure
* [Deployment Window](./deployment-window) - Time-based deployment control
* [Version Cooldown](./version-cooldown) - Batch frequent releases