Safe Rollout

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

Safe rollout gives operators progressive control over how a new release reaches traffic. Rather than activating a release across all traffic at once, operators can target specific service lanes — canary first, then broader groups — and roll back quickly if execution health degrades.

What Is Safe Rollout?

Orqestra enforces a one-active-release invariant per (app, environment, lane) tuple. Safe rollout builds on this by letting you activate a release on one lane at a time, moving through a progression from restricted to broader exposure:

1. Activate on a restricted lane to serve a small slice of traffic (canary).
2. Advance to guided once you are satisfied the release is healthy.
3. Advance to standard to reach full traffic.

At any point you can roll back, which re-activates the previous release on the same lane and records an evidence artifact capturing the reason.

The system also surfaces rollback recommendations based on observed execution error rates. The recommendation is advisory — the operator always makes the final decision.

Service Lanes

Orqestra defines three built-in lanes:

Each lane can carry a different active release simultaneously. For example, restricted might run release v3 while guided and standard still run release v2.

Lane assignment for incoming requests is controlled by the workload’s runtime configuration. See the Workloads guide for lane binding details.

Lane Progression

Activating on a Lane

To start a progressive rollout, activate the release on a specific lane by passing the lane parameter to the transition endpoint:

curl -X POST http://localhost:8000/v1/releases/{release_id}/transition \
  -H "Content-Type: application/json" \
  -d '{
    "to_state": "active",
    "lane": "restricted"
  }'

Response (200 OK):

{
  "release_id": "r1a2b3c4-0000-0000-0000-000000000001",
  "state": "active",
  "previous_state": "approved",
  "lane": "restricted",
  "transitioned_by": "user:alice",
  "transitioned_at": "2026-04-11T09:00:00Z"
}

When lane is omitted, the release activates on all lanes simultaneously (default behavior, equivalent to a full promotion).

Rollout Plans

An optional rollout_plan on activation structures lane progression for operator or automation callers:

curl -X POST http://localhost:8000/v1/releases/{release_id}/transition \
  -H "Content-Type: application/json" \
  -d '{
    "to_state": "active",
    "lane": "restricted",
    "rollout_plan": {
      "lane_sequence": ["restricted", "guided", "standard"],
      "soak_duration_minutes": 30,
      "auto_advance": false
    }
  }'

Rollout Plan Fields

Rollout Modes

The system tracks progression via the rollout_state field on the release. This field records the current lane, soak start time, and overall rollout status (in_progress, completed, or rolled_back).

Advancing the Rollout

When operating in planned mode, call the advance endpoint to move to the next lane in the sequence. In manual mode, activate each lane explicitly with another transition request.

curl -X POST http://localhost:8000/v1/releases/{release_id}/rollout/advance \
  -H "Content-Type: application/json" \
  -d '{}'

Response (200 OK):

{
  "rollout_state": {
    "status": "in_progress",
    "lane_sequence": ["restricted", "guided", "standard"],
    "current_lane_index": 1,
    "soak_started_at": "2026-04-11T09:35:00Z"
  },
  "advanced_to_lane": "guided"
}

advanced_to_lane is null when all lanes have been traversed and rollout_state.status becomes "completed". The endpoint returns an error if the release has no in-progress rollout state.

Rollback

To revert a lane to its previous release:

curl -X POST http://localhost:8000/v1/releases/{release_id}/rollback \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "elevated error rate on payment flow"
  }'

Response (200 OK):

{
  "release_id": "r1a2b3c4-0000-0000-0000-000000000001",
  "rolled_back_to": "r0a1b2c3-0000-0000-0000-000000000001",
  "lane": "restricted"
}

What happens on rollback:

1. The previous active release on that lane is re-activated.
2. The rolled-back release transitions to superseded on that lane.
3. An evidence artifact is recorded with the rollback reason.
4. If a rollout plan was in progress, the rollout_status transitions to rolled_back.

Because asset versions are immutable, rollback restores the exact same configuration that was previously live.

Rollback Recommendation

Before advancing or deploying to wider traffic, you can query the system for a recommendation:

curl "http://localhost:8000/v1/releases/{release_id}/rollback-recommendation"

Response (200 OK):

{
  "recommended": false,
  "error_rate": 0.018,
  "sample_size": 200,
  "threshold": 0.05
}

When recommended is true, the execution error rate has exceeded the configured threshold over the sample window.

The recommendation is advisory. The system does not automatically roll back even when recommended — the operator decides when and whether to act.

Portal

The portal provides a rollout progress indicator on the release detail page:

• Lane badges show the current state of each lane (restricted, guided, standard) alongside the active release for that lane.
• “Advance to Next Lane” button is available when a rollout plan is active and the soak period has elapsed.
• “Rollback” button is available on any lane where this release is active.
• Rollback recommendation warning banner appears when the recommendation endpoint returns recommended: true for the current lane, prompting the operator to review before advancing.

Configuration

Rollback recommendation defaults can be pre-configured in the workload’s interface_config under the rollout_config key:

{
  "interface_config": {
    "rollout_config": {
      "sample_size": 200,
      "error_threshold": 0.03
    }
  }
}

rollout_config Fields

Values set here are used by rollback recommendation queries. They do not create rollout_state; tracked progression is created only when an activation request includes an explicit rollout_plan.

SDK Reference

The Python SDK exposes rollout operations on the releases client:

from orqestra_sdk import OrqestraClient
 
async with OrqestraClient("http://localhost:8000") as client:
    # Activate on a specific lane with an optional rollout plan
    await client.releases.transition(
        release_id="r1a2b3c4-...",
        to_state="active",
        lane="restricted",
        rollout_plan={
            "lane_sequence": ["restricted", "guided", "standard"],
            "soak_duration_minutes": 30,
            "auto_advance": False,
        },
    )
 
    # Check rollback recommendation
    recommendation = await client.releases.get_rollback_recommendation(
        release_id="r1a2b3c4-...",
    )
 
    # Check rollout status
    status = await client.releases.get_rollout_status(release_id="r1a2b3c4-...")
 
    # Advance to the next lane
    await client.releases.advance_rollout(release_id="r1a2b3c4-...")
 
    # Roll back to the previous release on the same lane
    await client.releases.rollback(
        release_id="r1a2b3c4-...",
        reason="elevated error rate",
    )

CLI Reference

# Activate on a specific lane
orqestractl release transition <release_id> --to active --lane restricted
 
# Check rollout status
orqestractl release rollout-status <release_id>
 
# Check rollback recommendation
orqestractl release rollback-recommendation <release_id>
 
# Advance to the next lane
orqestractl release advance <release_id>
 
# Roll back to the previous release on the same lane
orqestractl release rollback <release_id>

Best Practices

Start on restricted. Even if you intend to promote quickly, beginning on the most limited lane gives you a clean canary signal before broader exposure.

Set a meaningful soak duration. Thirty minutes is a reasonable minimum for flows with moderate traffic. For low-traffic workloads, increase the sample size or soak duration to gather a statistically useful signal.

Watch the recommendation before advancing. Query the rollback recommendation endpoint — or check the portal banner — before each manual advance step.

Use rollout_config for recommendation consistency. Setting workload-level defaults ensures rollback recommendations use the same sampling window and error threshold for every release of that workload.