Rollouts

A rollout applies a target container application configuration after you deploy a Worker that uses Containers. The target can change the image, instance type, limits, placement, or other container settings.

A container instance is one running copy of your container image on Cloudflare's network. It runs the process your image starts (ENTRYPOINT/CMD in the Dockerfile, or the base image default). When the target changes the image, the rollout replaces container instances with copies that run the target image. Rollouts do not change Durable Object storage.

When an existing container application's effective configuration changes, wrangler deploy:

1. Uploads and activates the new Worker version, including Durable Object class code.
2. Builds and pushes a Dockerfile image when needed, or uses the configured registry image reference.
3. Starts a rollout to apply the target container configuration.

The Worker is active before the image and rollout steps begin. These steps are not transactional, so the Worker can remain active if a later image or rollout step fails. Deploy success means the rollout started, not that every container instance has finished replacing. The first deploy creates the container application directly, and a deploy with no effective container changes starts no rollout.

When the image changes, new Worker code can still reach container instances on the previous image until the rollout finishes. Prefer Worker and image changes that work together during that window, or choose immediate when you need the shortest mixed window the platform allows.

Field names and allowed values are listed under Containers configuration.

By default, Wrangler starts a rolling rollout using rollout_step_percentage. If max_instances is omitted or less than 2, Wrangler uses one 100 step. Otherwise, Wrangler requests [10, 100]:

1. Request a target of about 10% of container instances with the new configuration. The platform raises this percentage when necessary so the step represents at least one instance at the configured max_instances.
2. Target 100% of container instances with the new configuration.

Configure the steps with rollout_step_percentage in Wrangler. Override the default plan for one deploy with --containers-rollout.

When the rollout selects a container instance to update:

1. Grace period (if configured). If rollout_active_grace_period is greater than 0, container instances that only recently became connected to their Durable Object are skipped until they pass that window. Default 0 means no extra wait. Refer to Rollout active grace period.
2. Signal stop. The platform sends SIGTERM to the main process in the container so it can stop accepting new work and finish in-flight work. Handle SIGTERM in your image if that process needs cleanup before exit.
3. Drain. The process has up to 15 minutes to exit after SIGTERM.
4. Force stop if needed. If the process is still running after 15 minutes, the platform sends SIGKILL.
5. After exit. The Container class onStop hook can run in the Worker once the container process has exited.
6. Start a new container instance with the target image. Disk is ephemeral unless you store data outside the container filesystem.

Each selected container instance follows this sequence on its own schedule. The fleet does not restart in a single moment.

The new container instance must start its process. Startup often takes on the order of seconds, depending on image size and what runs at start. Refer to cold starts.

A request that needs that container instance may wait until the container is ready, or fail if a client or Worker timeout is shorter than startup. Keep startup work fast, use port readiness checks if you configure them, and set timeouts with startup in mind.

rollout_active_grace_period applies only during a rollout, when the platform chooses which container instances to replace.

Containers are backed by Durable Objects. Each running container instance is associated with a Durable Object instance that starts it and sends it traffic. The grace period is how long that connection must already have been up before a rollout may shut the container down. It is not measured from deploy completion.

Use a non-zero value when short sessions should finish before a rollout replaces the container. Container instances that have been connected longer can still be replaced once they pass the window.

rollout_active_grace_period applies in every rollout mode, including immediate.

--containers-rollout applies to wrangler deploy only. It does not apply to wrangler versions upload.

On a full deploy, Wrangler activates the Worker before it processes the container image and rollout. Rollout mode controls how the target container configuration is applied.

Immediate sets the rollout plan to a single step that targets 100% of container instances. There is no intermediate percentage hold.

npx wrangler deploy --containers-rollout=immediate

yarn wrangler deploy --containers-rollout=immediate

pnpm wrangler deploy --containers-rollout=immediate

Use immediate when Worker code and the container image need to stay compatible and you want the mixed window as short as the platform allows (for example a breaking change in how the Worker talks to the process in the image).

Behavior:

• The new Worker version is activated before the container image and rollout are processed.
• The rollout then replaces container instances toward 100% using the same replace sequence as gradual mode, including grace period when configured.
• Replacements complete over wall-clock time. How long depends on how many container instances are running, how long each takes to stop and start, and any grace period.
• When the image changes, immediate minimizes but does not eliminate the period when the new Worker can reach instances on the previous image.
• Deploy success means the rollout started, not that replacements finished.

None leaves images and running container instances unchanged and deploys Worker code only.

Use none when the deploy should not publish a new image or start a container instance rollout. If image is a Dockerfile path and Docker is unavailable, Wrangler may require this flag or a working Docker setup so the deploy can skip container steps.

rollout_active_grace_period of 300 seconds (five minutes) and steps [10, 100]:

{
	"containers": [
		{
			"max_instances": 10,
			"class_name": "MyContainer",
			"image": "./Dockerfile",
			"rollout_active_grace_period": 300,
			"rollout_step_percentage": [10, 100],
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"name": "MY_CONTAINER",
				"class_name": "MyContainer",
			},
		],
	},
	"migrations": [
		{
			"tag": "v1",
			"new_sqlite_classes": ["MyContainer"],
		},
	],
}

[[containers]]
max_instances = 10
class_name = "MyContainer"
image = "./Dockerfile"
rollout_active_grace_period = 300
rollout_step_percentage = [ 10, 100 ]

[[durable_objects.bindings]]
name = "MY_CONTAINER"
class_name = "MyContainer"

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "MyContainer" ]

• Deploy Containers
• Lifecycle of a Container
• Image management
• Containers configuration