document container rollout config

Author: emily-shen

src/content/docs/containers/faq.mdx

@@ -67,16 +67,17 @@ An Example:
 ## How do container updates and rollouts work?
 
 When you run `wrangler deploy`, the Worker code is updated immediately and Container
-instances are updated using a rolling deploy strategy. Container instances are updated
-in batches, with 25% of instances being updated at a time by default.
+instances are updated using a rolling deploy strategy. The default rollout configuration is two steps,
+where the first step updates 10% of the instances, and the second step updates the remaining 90%.
+This can be configured in your Wrangler config file using the [`rollout_step_percentage`](/workers/wrangler/configuration#containers) property.
 
-When a Container instance is ready to be stopped, it is sent a `SIGTERM` signal, which
-allows it to gracefully shut down. If the instance does not stop within 15 minutes,
-it is forcefully stopped with a `SIGKILL` signal. If you have cleanup that must occur
-before a Container instance is stopped, you should do it during this period.
+When deploying a change, you can also configure a `rollout_active_grace_period`, which is the minimum
+number of seconds to wait before an active container instance becomes eligible for updating during a rollout.
+At that point, the container will be sent at `SIGTERM` and still has 15 minutes to shut down gracefully.
+If the instance does not stop within 15 minutes, it is forcefully stopped with a `SIGKILL` signal.
+If you have cleanup that must occur before a Container instance is stopped, you should do it during this 15 minute period.
 
-Once stopped, the instance is replaced with a new instance running the updated code. When the
-new instance starts, requests will hang during container startup.
+Once stopped, the instance is replaced with a new instance running the updated code. Requests may hang while the container is starting up again.
 
 ## How does scaling work?
 

src/content/docs/workers/wrangler/commands.mdx

@@ -324,6 +324,9 @@ None of the options for this command are required. Also, many can be set in your
   - Specify the [Workers for Platforms dispatch namespace](/cloudflare-for-platforms/workers-for-platforms/get-started/configuration/#2-create-a-dispatch-namespace) to upload this Worker to.
 - `--metafile` <Type text="string" /> <MetaInfo text="optional" />
   - Specify a file to write the build metadata from esbuild to. If flag is used without a path string, this defaults to `bundle-meta.json` inside the directory specified by `--outdir`. This can be useful for understanding the bundle size.
+- `--containers-rollout` <Type text="immediate | gradual" /> <MetaInfo text="optional" />
+  - Specify the [rollout strategy](/containers/faq#how-do-container-updates-and-rollouts-work) for [Containers](/containers) associated with the Worker. If set to `immediate`, 100% of container instances will be updated in one rollout step, overriding any configuration in `rollout_step_percentage`. Note that `rollout_active_grace_period`, if configured still applies.
+  - Defaults to `gradual`, where the default rollout is 10% then 100% of instances.
 
 <Render file="wrangler-commands/global-flags" product="workers" />
 

src/content/docs/workers/wrangler/configuration.mdx

@@ -1008,6 +1008,17 @@ The following options are available:
 - `image_vars` <Type text="Record<string, string>" /> <MetaInfo text="optional" />
   - Build-time variables, equivalent to using `--build-arg` with `docker build`. If you want to provide environment variables to your container at _runtime_, you should [use secret bindings or `envVars` on the Container class](/containers/examples/env-vars-and-secrets/).
 
+- `rollout_active_grace_period` <Type text="number" /> <MetaInfo text="optional" />
+  - The minimum number of seconds to wait before an active container instance becomes eligible for updating during a [rollout](/containers/faq#how-do-container-updates-and-rollouts-work). At that point, the container will be sent at `SIGTERM` and still has 15 minutes to shut down before it is forcibly killed and updated.
+  - Defaults to `0`.
+
+- `rollout_step_percentage` <Type text="number | number[]" /> <MetaInfo text="optional" />
+  - Configures what percentage of instances should be updated at each step of a [rollout](/containers/faq#how-do-container-updates-and-rollouts-work).
+  - If this is set to a single number, each step will rollout to that percentage of instances. The options are `5`, `10`, `20`, `25`, `50` or `100`.
+  - If this is an array of numbers, each step specifies the cumulative rollout progress, so the final step must be `100`.
+  - Defaults to `[10, 100]`.
+  - This can be overridden ad hoc by deploying with the `--containers-rollout=immediate` flag, which will roll out to 100% of instances in one step. Note that flag will not override `rollout_active_grace_period`, if configured.
+
 <WranglerConfig>
 
 ```toml title="wrangler.toml"