Configuring progressive rollout

General constraints

Review the general constraints that apply to all progressive rollout configurations. These constraints ensure proper operation and prevent conflicts with other features.

• Enterprise tier required: Progressive rollout is available only for Enterprise tier users.
• One rollout per flag: Only one progressive rollout is allowed per feature flag. You can configure it at the flag level or at the rule level, but not both at the same time.
• One active delivery strategy at a time: If an experiment is running on a flag, you can't create a progressive rollout. Similarly, if a progressive rollout is running, you can't start an experiment on that flag.
• Percentage range: Rollout percentage must be between 1% and 100%.

API requirements by scope

The API you use depends on the scope of your progressive rollout configuration. Select the appropriate API based on where you're configuring the rollout.

• Flag-level progressive rollout: Use the feature flag API to create and update the rollout.
• Rule-level progressive rollout: Use the Rules API to create and update the rollout.
• Stopping a rollout: Use the stop rollout APIs to stop an active progressive rollout.

Configuration requirements by scope

Before configuring a progressive rollout, ensure that your flag or rule uses explicit rollout values rather than inherited values. This requirement prevents conflicts and ensures the progressive rollout has full control.

• For flag-level progressive rollout: None of the targeting rules can have a rolloutPercentage value inherited from the flag. All targeting rules must use overridden rollout values.
• For rule-level progressive rollout: The targeting rule where you add the rollout can't use a value inherited from the flag. The rule must have its own explicit value.

Blocked operations during progressive rollout

When a progressive rollout is in the running state, certain operations are blocked to maintain rollout integrity and prevent conflicts.

• Creating another progressive rollout: Only one progressive rollout is allowed per flag.
• Starting an experiment: Experiments can't run on flags that already have a running progressive rollout.
• Deleting a collection: Collection deletion is blocked if any associated feature flag has a progressive rollout in the running state.
• Updating or deleting a segment: Segment updates and deletes are blocked if any associated feature flag has a progressive rollout in the running state.
• Modifying the flag or rule configuration: Updates to the flag or to the targeting rule that uses the rollout are allowed only when the progressive rollout isn't running.

Lifecycle behavior

Understanding the lifecycle behavior helps you to manage the interaction between progressive rollouts and other features. App Configuration maintains strict separation between delivery strategies.

• If an experiment is running, you can't create a progressive rollout.
• If a progressive rollout is running, you can't start an experiment on the same flag.
• To stop a rollout, you must use the dedicated stop rollout APIs.

Configuring flag-level progressive rollout

To configure progressive rollout at the flag level:

1. In the App Configuration console, navigate to Feature flags.
2. Select the environment containing your feature flag.
3. Click the feature flag you want to configure.
4. In the Feature rollout section, select Progressive as the rollout type.
5. Configure the rollout settings:
   • Duration preset: Choose from predefined templates (1hr, 12hr, 24hr, 48hr) or select Custom
   • Phases: Define each phase with a percentage and duration
   • Schedule later (optional): Toggle this option to specify a start time in UTC for the rollout. If not enabled, the rollout starts immediately.
6. Click Save.

The progressive rollout will start automatically at the configured start time.

Configuring rule-level progressive rollout

To configure progressive rollout at the targeting rule level:

1. In the App Configuration console, navigate to Feature flags.
2. Select the environment containing your feature flag.
3. Click the feature flag you want to configure.
4. In the Targeting section, select the rule you want to configure.
5. Ensure the rule has an overridden value.
6. In the rule's Rollout section, select Progressive as the rollout type.
7. Configure the rollout settings:
   • Duration preset: Choose from predefined templates (1hr, 12hr, 24hr, 48hr) or select Custom
   • Phases: Define each phase with a percentage and duration
   • Schedule later (optional): Toggle this option to specify a start time in UTC for the rollout. If not enabled, the rollout starts immediately.
8. Click Save.

Phase configuration

Define the percentage and duration for each phase of your progressive rollout. Each phase consists of two key components that control the rollout progression.

Each phase includes:

• Percentage: The percentage of users who will receive the enabled value (1-100%)
• Duration: How long this phase should last (e.g., "8h", "30m", "2d")

The final phase does not require a duration, as it represents the completion state.

Phase examples

Review these examples of progressive rollout phase configurations for different scenarios.

Example 1: Gradual 24-hour rollout

{
  "phases": [
    { "percentage": 5, "duration": "6h" },
    { "percentage": 25, "duration": "6h" },
    { "percentage": 50, "duration": "6h" },
    { "percentage": 100, "duration": "6h" }
  ]
}

Example 2: Rapid 1-hour rollout

{
  "phases": [
    { "percentage": 10, "duration": "15m" },
    { "percentage": 50, "duration": "15m" },
    { "percentage": 100, "duration": "30m" }
  ]
}

Example 3: Conservative 48-hour rollout

{
  "phases": [
    { "percentage": 5, "duration": "12h" },
    { "percentage": 10, "duration": "12h" },
    { "percentage": 25, "duration": "12h" },
    { "percentage": 100, "duration": "12h" }
  ]
}

Within a rollout

During a single progressive rollout, App Configuration maintains consistent assignments for each user to ensure a stable experience throughout all phases.

• Randomization is deterministic per entity_id.
• The same entity_id always receives the same assignment.
• Users who receive the enabled value in phase 1 continue to receive it in subsequent phases.
• New users are added as the percentage increases.

Across rollouts

When you start a new progressive rollout on the same flag, App Configuration generates a fresh distribution to allow different user exposure patterns.

• A fresh random distribution is generated.
• The same entity_id may receive a different assignment.
• This allows for different user groups to be exposed in different rollout cycles.