Restructure containers docs #24633

emily-shen · 2025-08-22T16:27:32Z

Changes in this PR:

move more pages things under 'platform reference' so the sidebar is less overwhelming.
create a new rollouts page under platform reference
rename 'architecture' to 'container lifecycle' and add lots more details, mostly copied over from the FAQ page which has lots of useful information but under a non-obvious location.

Before:

After:

I think this is better?

github-actions · 2025-08-22T16:27:50Z

This PR requires additional review attention because it affects the following areas:

Redirects

This PR changes current filenames or deletes current files. Make sure you have redirects set up to cover the following paths:

/containers/architecture/
/containers/durable-object-methods/
/containers/image-management/
/containers/platform-details/
/containers/scaling-and-routing/

Partials

This PR updates partial files, which are pieces of content used across multiple files in our Render component.

fundamentals/account-permissions-table - view affected files

github-actions · 2025-08-22T16:28:27Z

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
`/public/__redirects`	`@GregBrimble`, `@KianNH`, `@pedrosousa`, `@WalshyDev`, `@cloudflare/pcx-technical-writing`
`/src/content/docs/containers/`	`@mikenomitch`, `@th0m`, `@cloudflare/pcx-technical-writing`, `@cloudflare/cloudchamber`
`/src/content/docs/workers/wrangler/`	`@cloudflare/wrangler`, `@irvinebroque`, `@kodster28`, `@cloudflare/pcx-technical-writing`, `@cloudflare/workers-runtime-1`
`*`	`@cloudflare/pcx-technical-writing`

github-actions · 2025-08-22T16:37:22Z

Preview URL: https://25af132f.preview.developers.cloudflare.com
Preview Branch URL: https://emily-containers-restructure.preview.developers.cloudflare.com

Files with changes (up to 15)

gabivlj · 2025-09-10T15:44:16Z

src/content/docs/containers/platform-details/architecture.mdx

+isolation from other workloads running on Cloudflare's network. Containers
+should be built for the `linux/amd64` architecture, and should stay within
+[size limits](/containers/platform-details/limits). [Logging](/containers/faq/#how-do-container-logs-work), metrics collection, and
+networking are automatically set up on each container, if configured by the developer.


would be nice linking to enableInternet here (for networking).

src/content/docs/containers/platform-details/architecture.mdx

src/content/docs/containers/examples/container-backend.mdx

src/content/docs/containers/platform-details/architecture.mdx

gpanders · 2025-09-10T15:58:49Z

src/content/docs/containers/platform-details/architecture.mdx

+cleanup to ensure a graceful shutdown in this time. The container instance
+will be rebooted elsewhere shortly after this.


I think we should say "restarted elsewhere" instead of "rebooted elsewhere". But even then this is not always the case, right? Sometimes a container shuts down, but doesn't get restarted somewhere else (e.g. when downscaling).

i've done a lot of shuffling around, that probably made more sense in its original context. will remove here.

actually, if say, max_instances was 2 and i only had 1 instance running (ie not downscalling), and the container had to shutdown for some reason, would it restart even if there was no new DO activity?

src/content/docs/containers/platform-details/architecture.mdx

src/content/docs/containers/platform-details/environment-variables.mdx

src/content/docs/containers/image-management.mdx

github-actions bot assigned GregBrimble, KianNH, pedrosousa, WalshyDev, mikenomitch and th0m Aug 22, 2025

github-actions bot added size/m product:containers labels Aug 22, 2025

emily-shen force-pushed the emily/containers-restructure branch 4 times, most recently from 58eb81c to 3ff3d87 Compare September 3, 2025 14:03

gabivlj reviewed Sep 10, 2025

View reviewed changes

src/content/docs/containers/platform-details/architecture.mdx Outdated Show resolved Hide resolved