Set up canary rollouts

Canary rollouts let you release a new version of a service progressively. Traffic shifts gradually between the current version and the new version, letting you observe its behavior under real traffic before it serves all users.

A rollout is controlled by a canary rollout strategy. Strategies are created at the team level and attached to deployment or combined services. When a service with a strategy deploys a new version, the new version starts alongside the current version and receives only the traffic share defined by the strategy. You then progress the rollout manually by adjusting the traffic split until you promote the canary to serve all traffic or roll back to the previous version.

1. Navigate to Cloud in your team dashboard

2. Click Canary rollouts under Other resources

3. Click Create new canary rollout strategy

4. Enter a strategy name

5. Choose the canary rollout type

6. Choose the canary strategy type:

   • Percentage split: Routes a fixed percentage of requests to the canary version. For example, 10% canary and 90% stable routes approximately one in ten requests to the new version.
   • Header split: Routes requests by matching HTTP headers instead of proportion. For example, requests with x-variant: canary go to the new version, and x-variant: stable go to the current one.

7. Set the traffic split or header routing based on the canary strategy type selected

8. (Optional) Configure strategy options:

   • Block deployment on active rollout: Prevents new deployments from being triggered while a canary rollout is in progress. When enabled, you must promote or roll back the current rollout before deploying a new version.
   • Triggers: Select which release sources automatically start a rollout (Template, Release flow, CD, UI, API)

9. Click Create canary rollout strategy

Your strategy is now available to attach to services.

A strategy has no effect until it is attached to a service. You can attach a strategy when creating a service or add one to an existing service.

When creating a service:

1. Under Resources, expand Advanced resource options during service creation

2. Select a rollout strategy under Canary rollout strategy

3. Create the service

In an existing service:

1. Navigate to your service dashboard

2. Under Run, select Resources

3. Expand Advanced resource options

4. Select a rollout strategy under Canary rollout strategy

5. Click Update & restart

The next deployment will start as a rollout using your strategy's traffic split.

Remove a strategy from a service:

1. Navigate to your service dashboard

2. Under Run, select Resources

3. Expand Advanced resource options

4. Under Canary rollout strategy, deselect the strategy

5. Click Update & restart

The service will deploy new versions normally, without canary rollouts.

When a new version is deployed to a service with a strategy attached, the rollout is managed from the service's deployments page. The page shows the stable version, the canary version, and the amount of traffic each version is receiving.

Rollouts do not advance automatically. You decide when to increase traffic to the canary based on what you see in your metrics, logs, and your own application monitoring.

Increase traffic to the canary

Update the traffic percentages on the deployments page to shift more traffic to the canary, then save your changes. Traffic is rebalanced without redeploying either version.

Increase traffic in steps that suit your release plan. For example, you might move from 10% to 25%, then 50%, observing the canary at each stage before continuing.

Promote the canary

When you are satisfied with the canary, promote it to make it the only version running.

All traffic moves to the new version and the previous stable version is removed, ending the rollout.

Roll back

If the canary is not behaving as expected, roll back to move all traffic back to the previous stable version and end the rollout.

The canary version is removed and the service continues serving the previous stable version.

Edit a strategy

1. Navigate to Cloud in your team dashboard

2. Click Canary rollouts under Other resources

3. Select the strategy you want to edit

4. Edit the name, traffic split, or options

5. Click Save changes

Changes apply to new rollouts started after the update and do not affect rollouts that are already in progress.

Delete a strategy

1. Navigate to Cloud in your team dashboard

2. Click Canary rollouts under Other resources

3. Select the strategy you want to delete

4. Click the Delete icon

5. Confirm the deletion

The strategy is removed from all services that were using it. Those services will deploy new versions normally without canary rollouts.

You can also manage canary rollout strategies as code using templates, allowing you to provision the strategy and attach it to services in the same template.

Create a strategy in a template

Use a rollout strategy node to create or update a canary rollout strategy in your team. As a team resource node, it does not require a project context to run.

{
  "kind": "RolloutStrategy",
  "ref": "canary-strategy",
  "spec": {
    "name": "canary-10-percent",
    "type": "canary",
    "details": {
      "canaryStrategy": "percentage",
      "config": {
        "canaryPercentage": 10,
        "stablePercentage": 90
      }
    }
  }
}

Attach a strategy in a template

Set gradualRolloutStrategyId in the deployment object of a deployment service or combined service node to attach a strategy to the service.

You can reference a strategy created earlier in the same template, so the strategy and the services using it are created in a single run.