Skip to main content
Rolling deployments replace replicas incrementally when promoting a deployment to an environment. Instead of swapping all traffic at once, rolling deployments scale up the candidate deployment, shift traffic proportionally, and scale down the previous deployment in controlled steps. Use rolling deployments when you need zero-downtime updates with the ability to pause, cancel, or force-complete the deployment at any point.
Autoscaling is disabled for the entire duration of a rolling deployment. Replica counts don’t adjust automatically until the deployment reaches a terminal status (SUCCEEDED, FAILED, or CANCELED). Use the replica_overhead_percent setting to pre-provision additional capacity before the deployment starts.

​
How rolling deployments work

A rolling deployment follows a repeating three-step cycle:
  1. Scale up candidate deployment replicas by the configured percentage.
  2. Shift traffic proportionally to match the new replica ratio.
  3. Scale down the previous deployment replicas by the same percentage.
This cycle repeats until all traffic and replicas run on the candidate deployment, at which point it becomes the active deployment in the environment.

​
Provisioning modes

Rolling deployments support two mutually exclusive provisioning modes. You must configure exactly one:
  • max_surge_percent: Scales up candidate replicas before scaling down previous replicas.
  • max_unavailable_percent: Scales down previous replicas before scaling up candidate replicas.
Both can’t be non-zero at the same time, and both can’t be zero at the same time.

​
Enabling rolling deployments

Enable rolling deployments on any environment by updating the environment’s promotion settings. Rolling deployments are disabled by default. 
curl -X PATCH \
  https://api.baseten.co/v1/models/{model_id}/environments/production \
  -H "Authorization: Api-Key $BASETEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "promotion_settings": {
      "rolling_deploy": true,
      "rolling_deploy_config": {
        "max_surge_percent": 10,
        "max_unavailable_percent": 0,
        "stabilization_time_seconds": 60,
        "replica_overhead_percent": 0
      }
    }
  }'
Once rolling deployments are enabled, any subsequent promotion to the environment uses the rolling deployment workflow.

​
Configuration reference

Configure rolling deployments through the rolling_deploy_config object in the environment’s promotion_settings.
​
max_surge_percent
integer
default:"10"
Percentage of additional replicas to provision during each step. Set to 0 to use max unavailable mode instead.Range: 0–50
​
max_unavailable_percent
integer
default:"0"
Percentage of replicas that can be unavailable during each step. Set to 0 to use max surge mode instead.Range: 0–50
​
stabilization_time_seconds
integer
default:"0"
Seconds to wait after each traffic shift before proceeding to the next step. Use this to monitor metrics between steps.Range: 0–3600
​
replica_overhead_percent
integer
default:"0"
Percentage of additional replicas to pre-provision on the current deployment before the rolling deployment starts. Compensates for autoscaling being disabled.Range: 0–500
Additional promotion settings configured at the promotion_settings level:
​
rolling_deploy
boolean
default:"false"
Enables rolling deployments for the environment.

​
Deployment statuses

The in_progress_promotion field on the environment detail endpoint tracks the current state of a rolling deployment.
StatusDescription
RELEASINGCandidate deployment is building and initializing replicas.
RAMPING_UPScaling up candidate replicas and shifting traffic.
PAUSEDRolling deployment is paused at its current traffic split. Replicas stay at their current count.
RAMPING_DOWNGraceful cancel in progress. Traffic is shifting back to the previous deployment.
SUCCEEDEDRolling deployment completed. The candidate is now the active deployment. Autoscaling resumes.
FAILEDRolling deployment failed. Traffic remains on the previous deployment. Autoscaling resumes.
CANCELEDRolling deployment was canceled. Traffic returned to the previous deployment. Autoscaling resumes.
The in_progress_promotion object also includes percent_traffic_to_new_version, which reports the current percentage of traffic routed to the candidate deployment.

​
Deployment control actions

​
Pause

Pauses the rolling deployment after the current step completes. Use this to inspect metrics or logs before proceeding. 
curl -X POST \
  https://api.baseten.co/v1/models/{model_id}/environments/production/pause_promotion \
  -H "Authorization: Api-Key $BASETEN_API_KEY"

​
Resume

Resumes a paused rolling deployment from where it left off. 
curl -X POST \
  https://api.baseten.co/v1/models/{model_id}/environments/production/resume_promotion \
  -H "Authorization: Api-Key $BASETEN_API_KEY"

​
Cancel

Gracefully cancels the rolling deployment. Traffic ramps back to the previous deployment and candidate replicas scale down. 
curl -X POST \
  https://api.baseten.co/v1/models/{model_id}/environments/production/cancel_promotion \
  -H "Authorization: Api-Key $BASETEN_API_KEY"
Returns a status of CANCELED (instant cancel for non-rolling deployments) or RAMPING_DOWN (graceful rollback for rolling deployments).

​
Force cancel

Immediately cancels the rolling deployment and returns all traffic to the previous deployment. Use this when you need to roll back without waiting for the graceful ramp-down.
Force canceling may cause brief service disruption if the previous deployment is under-provisioned.
curl -X POST \
  https://api.baseten.co/v1/models/{model_id}/environments/production/force_cancel_promotion \
  -H "Authorization: Api-Key $BASETEN_API_KEY"

​
Force roll forward

Immediately completes the rolling deployment, shifting all traffic to the candidate deployment. This works even if the deployment is in the process of rolling back.
Force rolling forward may promote an under-provisioned deployment if the candidate has not finished scaling up.
curl -X POST \
  https://api.baseten.co/v1/models/{model_id}/environments/production/force_roll_forward_promotion \
  -H "Authorization: Api-Key $BASETEN_API_KEY"

​
Autoscaling during rolling deployments

To compensate for autoscaling being disabled during rolling deployments:
  • Set replica_overhead_percent to pre-provision the current deployment before the rolling deployment starts. For example, a value of 50 adds 50% more replicas to the current deployment before any traffic shifts.
  • Set stabilization_time_seconds to add a wait period between steps, giving you time to monitor metrics before the next traffic shift.
  • Factor in expected traffic when setting your environment’s min_replica and max_replica before starting the rolling deployment.
Autoscaling resumes automatically when the rolling deployment reaches a terminal status: SUCCEEDED, FAILED, or CANCELED.

​
Deployment cleanup

After a rolling deployment completes, the promotion_cleanup_strategy setting controls what happens to the previous deployment.
  • SCALE_TO_ZERO: Scales the previous deployment to zero replicas. It remains available for reactivation. This is the default.
  • KEEP: Leaves the previous deployment running at its current replica count.
  • DEACTIVATE: Deactivates the previous deployment. It stops serving traffic and releases all resources.
Set it alongside your other promotion settings: 
curl -X PATCH \
  https://api.baseten.co/v1/models/{model_id}/environments/production \
  -H "Authorization: Api-Key $BASETEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "promotion_settings": {
      "promotion_cleanup_strategy": "DEACTIVATE"
    }
  }'