Skip to content
Start here

Rollouts

Create a new rollout for an application
POST/accounts/{account_id}/containers/applications/{application_id}/rollouts
ModelsExpand Collapse
RolloutCreateResponse object { id, created_at, current_configuration, 14 more }

Represents the status and metadata of a rollout process for an application. For “rolling” strategy: includes steps and progress with instance counts. For “new_instances” strategy: the response omits steps and progress. Use percentage, version_distribution, and health.summary for status.

id: string

An identifier for a specific rollout within an application.

created_at: string

UTC timestamp string in ISO 8601 format.

current_configuration: object { authorized_keys, command, entrypoint, 4 more }

User-specified container configuration changes.

authorized_keys: optional array of object { public_key, name }
public_key: string

An SSH public key.

name: optional string

Optional human readable name for this key.

command: optional array of string

The command that runs when the container starts, passed to the entrypoint. You can override this at run-time. If you override only the command, it gets passed to the default entrypoint specified in the image.

entrypoint: optional array of string

The entry point for the container, specifying the executable to run when the container starts. You can override this at run-time. If you do, the default command from the image is ignored. Specify both entrypoint and command at run-time to completely replace the image defaults.

environment_variables: optional array of object { name, value }

Container environment variables.

name: string

An environment variable name.

value: string

An environment variable value.

image: optional string

Image url.

instance_type: optional "lite" or "basic" or "standard-1" or 3 more

The instance type configures vCPU, memory, and disk.

  • “lite”: 1/16 vCPU, 256 MiB memory, 2 GB disk
  • “basic”: 1/4 vCPU, 1 GiB memory, 4 GB disk
  • “standard-1”: 1/2 vCPU, 4 GiB memory, 8 GB disk
  • “standard-2”: 1 vCPU, 6 GiB memory, 12 GB disk
  • “standard-3”: 2 vCPU, 8 GiB memory, 16 GB disk
  • “standard-4”: 4 vCPU, 12 GiB memory, 20 GB disk
One of the following:
"lite"
"basic"
"standard-1"
"standard-2"
"standard-3"
"standard-4"
observability: optional object { logs }

Settings for deployment observability such as logging.

logs: optional object { enabled }

Observability logging settings.

enabled: optional boolean
current_version: number

Current application version before the rollout.

description: string
health: object { errors, instances, summary }
errors: array of object { event, instance_id }
event: object { id, details, message, 4 more }

An event within a Placement or a Job.

id: string
details: map[unknown]
message: string
name: "SchedulerPlaced" or "NetworkingIPAssigned" or "VMStarted" or 14 more

Name of the event that describes the kind event that happened.

  • SchedulerPlaced: It’s the first event that creates a container placement. It happens when the Containers runtime was able to retrieve deployment resources and start verifying everything is correct.
  • NetworkingIPAssigned: It’s sent when the Containers runtime maps the IP to the container.
  • VMStarted: It’s sent when the Containers runtime starts the VM. The container might remain unhealthy at this point.
  • ImagePulled: It’s sent when the Containers runtime pulls the image successfully.
  • ImagePullError: It’s sent when the Containers runtime is having issues pulling the image. The message and details have more information on what happened for debugging.
  • VMFailedToStart: It’s sent when the Containers runtime was unable to boot the VM.
  • VMStopping: It’s sent when the scheduler is stopping the VM.
  • VMStopped: It’s sent when the VM finally exits.
  • VMFailed: It’s sent when the scheduling of the VM failed in the current location.
  • RuntimeStartFailed: It’s sent when the runtime hits an internal error.
  • SSHStarted: It’s sent when the container gains network connectivity and opens the SSH port. Containers only send this event when SSH keys exist.
  • CheckUpdate: Sent when the status of a health or readiness check changes. This may also affect the health status of the placement.
  • DurableObjectConnected: Sent when a durable object instance connects and gains control of the deployment. This event is only sent for durable object deployments. It is sent after VMStarted.
  • ContainerStarted: It’s sent when the container starts running.
One of the following:
"SchedulerPlaced"
"NetworkingIPAssigned"
"VMStarted"
"ImagePulled"
"ImagePullError"
"VMFailedToStart"
"NetworkingIPAssignmentFailed"
"VMRunning"
"VMStopping"
"VMStopped"
"VMFailed"
"RuntimeStartFailed"
"SSHStarted"
"ServiceHealthUpdates"
"CheckUpdate"
"DurableObjectConnected"
"ContainerStarted"
statusChange: map[unknown]
time: string

UTC timestamp string in ISO 8601 format.

type: "Info" or "Error" or "Warn" or 2 more
One of the following:
"Info"
"Error"
"Warn"
"UserError"
"SystemError"
instance_id: string

An instance ID represents an identifier of an instance configuration that maintains an underlying placement.

instances: object { active, assigned }

Shows a count of application instance states.

active: number

Number of instances whose runtime reports the container as running (container_status = “running”). This is a subset of the placements that remain up: an instance that is already bound to a Durable Object and serving traffic is counted under “assigned” until its container_status catches up to “running”, so container_status can briefly lag Durable Object attachment under churn. To estimate running, Durable-Object-bound instances, sum “active” + “assigned” rather than reading “active” alone.

assigned: number

Number of instances bound to a Durable Object with a running placement whose container_status remains behind “running”. These count as live, serving instances; “active” + “assigned” approximates the running, Durable-Object-bound count.

summary: optional "healthy" or "degraded" or "unhealthy" or "pending"

High-level health assessment. Only populated for “new_instances” strategy. Based on a sample of target-version instances rather than a full count.

  • “pending”: Zero target-version instances exist yet.
  • “healthy”: Every sampled target-version instance reports running or active.
  • “degraded”: Some sampled instances remain starting or scheduling.
  • “unhealthy”: One or more sampled instances have failed.
One of the following:
"healthy"
"degraded"
"unhealthy"
"pending"
kind: "full_auto" or "full_manual" or "durable_objects_auto"

Kind of the rollout process.

  • “full_auto”: For rolling rollouts, starts progressing steps upon rollout creation. For new_instances rollouts, advances percentage targets automatically after target-version health is observed.
  • “full_manual”: Requires manually progressing each step in the rollout using the UpdateRollout’s action paramater.
  • “durable_objects_auto”: Default when the application is a DO application.
One of the following:
"full_auto"
"full_manual"
"durable_objects_auto"
last_updated_at: string

Timestamp of the most recent update to status, health, or progress.

status: "pending" or "progressing" or "completed" or 2 more

Current status of the rollout.

One of the following:
"pending"
"progressing"
"completed"
"reverted"
"replaced"
strategy: "rolling" or "new_instances"

The rollout strategy.

  • “rolling”: Step-based rollout with health gates. Actively replaces instances to reach each step’s target percentage. Response includes steps and progress.
  • “new_instances”: Percentage control over version distribution. Version sync actively replaces instances to match the configured percentage. “full_auto” ramps through fixed percentage targets after target-version health is observed. Response includes percentage, version_distribution, and health.summary.
One of the following:
"rolling"
"new_instances"
target_configuration: object { authorized_keys, command, entrypoint, 4 more }

User-specified container configuration changes.

authorized_keys: optional array of object { public_key, name }
public_key: string

An SSH public key.

name: optional string

Optional human readable name for this key.

command: optional array of string

The command that runs when the container starts, passed to the entrypoint. You can override this at run-time. If you override only the command, it gets passed to the default entrypoint specified in the image.

entrypoint: optional array of string

The entry point for the container, specifying the executable to run when the container starts. You can override this at run-time. If you do, the default command from the image is ignored. Specify both entrypoint and command at run-time to completely replace the image defaults.

environment_variables: optional array of object { name, value }

Container environment variables.

name: string

An environment variable name.

value: string

An environment variable value.

image: optional string

Image url.

instance_type: optional "lite" or "basic" or "standard-1" or 3 more

The instance type configures vCPU, memory, and disk.

  • “lite”: 1/16 vCPU, 256 MiB memory, 2 GB disk
  • “basic”: 1/4 vCPU, 1 GiB memory, 4 GB disk
  • “standard-1”: 1/2 vCPU, 4 GiB memory, 8 GB disk
  • “standard-2”: 1 vCPU, 6 GiB memory, 12 GB disk
  • “standard-3”: 2 vCPU, 8 GiB memory, 16 GB disk
  • “standard-4”: 4 vCPU, 12 GiB memory, 20 GB disk
One of the following:
"lite"
"basic"
"standard-1"
"standard-2"
"standard-3"
"standard-4"
observability: optional object { logs }

Settings for deployment observability such as logging.

logs: optional object { enabled }

Observability logging settings.

enabled: optional boolean
target_version: number

Target application version after the rollout is complete and applied to all current instances.

percentage: optional number

Current target version percentage (0-100). Only present for “new_instances” strategy.

progress: optional object { current_step, total_instances, total_steps, 2 more }

Progress details of an application rollout.

current_step: number

Current step being executed in the rollout process. Initialized to 0.

total_instances: number

Total number of instances the rollout affects.

total_steps: number

Total number of steps in the rollout.

updated_instances: number

Number of instances updated in the rollout process.

version_distribution: optional object { current_version_instances, current_version_percentage, target_version_instances, target_version_percentage }

Expected distribution of instances per version, based on the current percentage split. Populated during active rollouts. Values derive from the version percentage weights rather than actual running instance counts.

current_version_instances: optional number

Expected number of instances remaining on the current (old) version based on the current percentage split. Only populated for “rolling” strategy.

current_version_percentage: optional number

The percentage of new instances being scheduled on the current version (100 - target_version_percentage). Only populated for “new_instances” strategy.

target_version_instances: optional number

Expected number of instances scheduled for the target (new) version based on the current percentage split. Only populated for “rolling” strategy.

target_version_percentage: optional number

The active percentage of new instances being scheduled on the target version. For “rolling”, this reflects the step_size.percentage of the current active step. For “new_instances”, this reflects the user-set percentage.

started_at: optional string

Timestamp when the rollout started.

formatdate-time
steps: optional array of object { id, description, status, 4 more }
id: number

The sequential order of the rollout step, automatically assigned starting from 1, based on the total number of steps in the rollout process.

description: string

Description of the rollout step.

status: "pending" or "progressing" or "reverting" or 2 more

Status of the rollout step.

One of the following:
"pending"
"progressing"
"reverting"
"completed"
"reverted"
step_size: object { percentage }
percentage: number

Percentage of instances affected in this step. Min 10% and Max 100%.

completed_at: optional string

UTC timestamp string in ISO 8601 format.

reason: optional string

Reason for the step’s current status.

started_at: optional string

UTC timestamp string in ISO 8601 format.

version_distribution: optional object { current_version_percentage, target_version_percentage }

Version percentage distribution. Only present for “new_instances” strategy. For “rolling” strategy, see progress.version_distribution instead.

current_version_percentage: number

Percentage of instances on the current (old) version.

target_version_percentage: number

Percentage of instances on the target (new) version.