Some minor tweaks by mikenomitch · Pull Request #23150 · cloudflare/cloudflare-docs

mikenomitch · 2025-06-21T18:20:44Z

Summary

Adds documentation for an upcoming feature 🤫 🤐 🙈

Documentation checklist

The documentation style guide has been adhered to.
If a larger change - such as adding a new page- an issue has been opened in relation to any incorrect or out of date information that this PR fixes.
Files which have changed name or location have been allocated redirects.

github-actions · 2025-06-21T18:21:38Z

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

Pattern	Owners
`*`	`@cloudflare/pcx-technical-writing`
`/src/content/docs/durable-objects/`	`@elithrar`, `@vy-ton`, `@joshthoward`, `@oxyjun`, `@harshil1712`, `@mikenomitch`, `@cloudflare/pcx-technical-writing`, `@cloudflare/workers-runtime-1`
`/src/content/docs/workers/wrangler/`	`@cloudflare/wrangler`, `@irvinebroque`, `@kodster28`, `@cloudflare/pcx-technical-writing`, `@cloudflare/workers-runtime-1`
`/src/content/partials/workers/`	`@cloudflare/workers-docs`, `@GregBrimble`, `@irvinebroque`, `@mikenomitch`, `@WalshyDev`, `@cloudflare/deploy-config`, `@cloudflare/pcx-technical-writing`, `@kodster28`, `@cloudflare/wrangler`, `@cloudflare/workers-runtime-1`, `@cloudflare/wrangler`

src/content/docs/containers/architecture.mdx

src/content/docs/containers/beta-info.mdx

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

src/content/docs/containers/index.mdx

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

src/content/docs/containers/scaling-and-routing.mdx

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

Various small fixes Co-authored-by: Nikita Sharma <54369599+nikitassharma@users.noreply.github.com>

irvinebroque

^ copy suggestions for homepage, can take or leave

src/content/docs/containers/index.mdx

Co-authored-by: Brendan Irvine-Broque <birvine-broque@cloudflare.com>

src/content/docs/containers/index.mdx

irvinebroque

^ Notes on getting started docs

src/content/docs/containers/get-started.mdx

irvinebroque · 2025-06-24T06:04:04Z

src/content/docs/containers/get-started.mdx

+  ```
+
+- Making requests to `/lb` will load balance requests across several containers.
+  This uses a simple `getRandom` helper method currently, which picks an ID at random


Suggested change

This uses a simple `getRandom` helper method currently, which picks an ID at random

This uses a simple `getRandom` helper method, which picks an ID at random

irvinebroque · 2025-06-24T06:04:47Z

src/content/docs/containers/get-started.mdx

+
+- Making requests to `/lb` will load balance requests across several containers.
+  This uses a simple `getRandom` helper method currently, which picks an ID at random
+  from a set number (in this case 3), then routes to that Container instance.


Suggested change

from a set number (in this case 3), then routes to that Container instance.

from a set number (in this case 3), then routes to that Container instance. You can replace this with any routing or load balancing logic you choose to implement:

(or maybe there is a good example we want to point towards)

irvinebroque · 2025-06-24T06:06:29Z

src/content/docs/containers/get-started.mdx

+Currently, routing requests to one of many interchangeable Container instances is accomplished
+with the `getRandom` helper.
+
+This is a temporary solution until first-party support for utilization-aware autoscaling


Suggested change

This is a temporary solution until first-party support for utilization-aware autoscaling

This is temporary — we plan to add native support for latency-aware autoscaling and load balancing in the coming months.

irvinebroque · 2025-06-24T06:06:58Z

src/content/docs/containers/get-started.mdx

+with the `getRandom` helper.
+
+This is a temporary solution until first-party support for utilization-aware autoscaling
+and latency-aware load balancing is added to Cloudflare Containers. We plan to add this


Suggested change

and latency-aware load balancing is added to Cloudflare Containers. We plan to add this

irvinebroque · 2025-06-24T06:07:05Z

src/content/docs/containers/get-started.mdx

+
+This is a temporary solution until first-party support for utilization-aware autoscaling
+and latency-aware load balancing is added to Cloudflare Containers. We plan to add this
+in the coming months.


Suggested change

in the coming months.

irvinebroque

^ re: Platform section

irvinebroque · 2025-06-24T06:09:15Z

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

@@ -0,0 +1,71 @@
+---
+pcx_content_type: navigation
+title: Platform Details


Suggested change

title: Platform Details

title: Platform

consistent with rest of docs

irvinebroque · 2025-06-24T06:09:25Z

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

+
+import { WranglerConfig } from "~/components";
+
+This page containers general details about the Containers platform.


Suggested change

This page containers general details about the Containers platform.

irvinebroque · 2025-06-24T06:09:45Z

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

+## Instance Types
+
+The memory, vCPU, and disk space for Containers are set through predefined instance types.
+There are currently three instance types available for Containers users by default:


Suggested change

There are currently three instance types available for Containers users by default:

Three instance types are currently available:

irvinebroque · 2025-06-24T06:12:17Z

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

+| basic         | 1 GiB   | 1/4  | 4 GB |
+| standard      | 4 GiB   | 1/2  | 4 GB |
+
+These are specified using the `instance_type` property in wrangler config.


Suggested change

These are specified using the `instance_type` property in wrangler config.

These are specified using the [`instance_type` property](/workers/wrangler/configuration/#containers) in your Worker's Wrangler configuration file. Looking for larger instances? [Give us feedback here](/containers/beta-info/#feedback-wanted) and tell us what size instances you need, and what you want to use them for.

irvinebroque · 2025-06-24T06:12:47Z

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

+
+## Limits
+
+Containers limits are currently set per account. You may have higher


Suggested change

Containers limits are currently set per account. You may have higher

irvinebroque · 2025-06-24T06:14:56Z

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

+
+| Feature                                           | Workers Paid |
+| ------------------------------------------------- | ------------ |
+| GB Memory for concurrent live Container instances | 40GB [^1]    |


irvinebroque · 2025-06-24T06:15:13Z

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

+| Feature                                           | Workers Paid |
+| ------------------------------------------------- | ------------ |
+| GB Memory for concurrent live Container instances | 40GB [^1]    |
+| vCPU for concurrent live Container instances      | 20 [^1]      |


irvinebroque · 2025-06-24T06:15:22Z

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

+| ------------------------------------------------- | ------------ |
+| GB Memory for concurrent live Container instances | 40GB [^1]    |
+| vCPU for concurrent live Container instances      | 20 [^1]      |
+| GB Disk for concurrent live Container instances   | 100GB [^1]   |


irvinebroque · 2025-06-24T06:15:32Z

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

+| vCPU for concurrent live Container instances      | 20 [^1]      |
+| GB Disk for concurrent live Container instances   | 100GB [^1]   |
+| Image size                                        | 2 GB         |
+| Total image storage for account                   | 50 GB [^2]   |


irvinebroque · 2025-06-24T06:18:36Z

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

+
+[^1]: This limit will be raised as we continue the beta.
+
+[^2]: Delete images with `wrangler containers delete` to free up space. Note that reverted Workers may then break.


Suggested change

[^2]: Delete images with `wrangler containers delete` to free up space. Note that reverted Workers may then break.

[^2]: Delete container images with `wrangler containers delete` to free up space. Note that if you delete a container image and then [roll back](/workers/configuration/versions-and-deployments/rollbacks/) your Worker to a previous version, this version may no longer work.

I'm actually not sure I could fully explain this given how we say this?

irvinebroque

^ local dev

irvinebroque · 2025-06-24T06:19:53Z

src/content/docs/containers/local-dev.mdx

@@ -0,0 +1,47 @@
+---
+pcx_content_type: reference
+title: Local Dev


Suggested change

title: Local Dev

title: Local Development

irvinebroque · 2025-06-24T06:20:01Z

src/content/docs/containers/local-dev.mdx

+  order: 3
+---
+
+## Local Development


Feels like something in getting started should reference?

irvinebroque · 2025-06-24T06:20:48Z

src/content/docs/containers/local-dev.mdx

+  order: 3
+---
+
+## Local Development


Suggested change

## Local Development

Already has title above?

src/content/docs/containers/local-dev.mdx

irvinebroque · 2025-06-24T06:24:31Z

src/content/docs/containers/local-dev.mdx

+`wrangler dev` or `wrangler deploy`.
+
+:::note
+If your Worker app creates many container instances, you may hit local limits


Suggested change

If your Worker app creates many container instances, you may hit local limits

If your Worker app creates many container instances, your local machine may not be able to run as many containers concurrently as is possible when you deploy to Cloudflare.

Suggest being clear that this isn't a limitation of the product but a limit of the end developer's machine that we are talking about here?

irvinebroque · 2025-06-24T06:24:37Z

src/content/docs/containers/local-dev.mdx

+
+:::note
+If your Worker app creates many container instances, you may hit local limits
+on concurrent containers.


Suggested change

on concurrent containers.

irvinebroque · 2025-06-24T06:25:54Z

src/content/docs/containers/local-dev.mdx

+
+## Iterating on Container code
+
+When using `wrangler dev`, standard Worker code is automatically reloaded by wrangler you save a change,


Suggested change

When using `wrangler dev`, standard Worker code is automatically reloaded by wrangler you save a change,

When you use `wrangler dev`, your Worker's code is automatically reloaded by Wrangler each time you save a change,

irvinebroque · 2025-06-24T06:26:14Z

src/content/docs/containers/local-dev.mdx

+When using `wrangler dev`, standard Worker code is automatically reloaded by wrangler you save a change,
+but code running within the container is not.
+
+If you wish to rebuild your container with new code changes, you can hit the `[r]` key on your keyboard, and a


Suggested change

If you wish to rebuild your container with new code changes, you can hit the `[r]` key on your keyboard, and a

To rebuild your container with new code changes, you can hit the `[r]` key on your keyboard, which

irvinebroque · 2025-06-24T06:26:52Z

src/content/docs/containers/local-dev.mdx

+but code running within the container is not.
+
+If you wish to rebuild your container with new code changes, you can hit the `[r]` key on your keyboard, and a
+rebuild will be triggered. Instances will be restarted with the new images.


Suggested change

rebuild will be triggered. Instances will be restarted with the new images.

triggers a rebuild. Container instances will then be restarted with the newly built images.

irvinebroque · 2025-06-24T06:27:43Z

src/content/docs/containers/local-dev.mdx

+If you wish to rebuild your container with new code changes, you can hit the `[r]` key on your keyboard, and a
+rebuild will be triggered. Instances will be restarted with the new images.
+
+You may prefer to set up your code watchers and reloading mechanisms, or mount a local directory


Suggested change

You may prefer to set up your code watchers and reloading mechanisms, or mount a local directory

You may prefer to set up your own code watchers and reloading mechanisms, or mount a local directory

irvinebroque · 2025-06-24T06:43:35Z

src/content/docs/containers/get-started.mdx

+
+  ```js
+  if (pathname.startsWith("/container")) {
+  	let id = env.MY_CONTAINER.idFromName("container");


Realizing that nothing in this page or elsewhere in docs links to or explains bindings

src/content/docs/containers/pricing.mdx

src/content/docs/containers/examples/index.mdx

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

irvinebroque · 2025-06-24T08:26:50Z

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

+
+## Using existing images
+
+If you wish to use a pre-built image, first, push it to the Cloudflare Registry:


Should we be louder here about public/private nature of the registry?

…d plan

emily-shen · 2025-06-24T09:31:59Z

src/content/docs/containers/local-dev.mdx

+You can run both your container and your Worker locally, without additional configuration, by running [`npx wrangler dev`](/workers/wrangler/commands/#dev) in your project's directory.
+
+To develop Container-enabled Workers locally, you will need to first ensure that a
+Docker compatible CLI tool is installed. For instance, you can use [Docker Desktop](https://docs.docker.com/desktop/)


Suggested change

Docker compatible CLI tool is installed. For instance, you can use [Docker Desktop](https://docs.docker.com/desktop/)

Docker compatible CLI tool and engine is installed. For instance, you can use [Docker Desktop](https://docs.docker.com/desktop/)

users will also have to configure the docker host if its not docker desktop.
hopefully by this afternoon, they can do WRANGLER_DOCKER_HOST="unix:///Users/myUser/.colima/default/docker.sock" etc, or set that field in their wrangler config under dev.container_engine.
if we haven't got the release out yet, users can symlink the default docker socket e.g. sudo ln -sf $HOME/.colima/default/docker.sock /var/run/docker.sock

probably mention the symlink thing and i can put up an update PR to the docs when the wrangler release is out?

emily-shen · 2025-06-24T09:34:06Z

src/content/docs/containers/local-dev.mdx

do we also want to mention you have to expose any ports you call in your dockerfile?

gabivlj

(some minor comments)

gabivlj · 2025-06-24T14:36:10Z

src/content/docs/containers/beta-info.mdx

+
+### Reduction of log noise
+
+Currently, the `Container` class uses Durable Object alarms to help manage Container shutdown. This


As an alternative for the user, if they need bigger control over their alarms, they can choose to use the ctx.container directly on a DurableObject?

gabivlj · 2025-06-24T14:38:12Z

src/content/docs/durable-objects/api/container.mdx

+When using a [Container-enabled Durable Object](/containers), you can access the Durable Object's associated container via
+the `container` object which is on the `ctx` property. This allows you to start, stop, and interact with the container.
+
+:::note


It'd be nice to tell the user when is it preferable to use one or the other.

* Adds Containers docs * A variety of tweaks to containers docs * Fixes bad links * replace icon * remove extra file * Apply suggestions from code review Various small fixes Co-authored-by: Nikita Sharma <54369599+nikitassharma@users.noreply.github.com> * Removes unnecessary pre-req and wrong TCP statement * Apply suggestions from code review Co-authored-by: Brendan Irvine-Broque <birvine-broque@cloudflare.com> * Apply suggestions from code review * Update pricing docs, make sure to clarify what is part of Workers Paid plan * Various tweaks --------- Co-authored-by: kodster28 <kody@cloudflare.com> Co-authored-by: Nikita Sharma <54369599+nikitassharma@users.noreply.github.com> Co-authored-by: Brendan Irvine-Broque <birvine-broque@cloudflare.com>

mikenomitch requested review from a team, GregBrimble, Oxyjun, WalshyDev, elithrar, harshil1712, irvinebroque, joshthoward, kodster28 and vy-ton as code owners June 21, 2025 18:20

github-actions bot assigned dcpena and haleycode Jun 21, 2025

github-actions bot added size/xl product:containers labels Jun 21, 2025

github-actions bot assigned patriciasantaana Jun 21, 2025

github-actions bot added product:durable-objects Durable Objects: https://developers.cloudflare.com/workers/learning/using-durable-objects/ product:workers Related to Workers product labels Jun 21, 2025

github-actions bot assigned pedrosousa, elithrar, harshil1712, joshthoward, Oxyjun, vy-ton and irvinebroque Jun 21, 2025

mikenomitch force-pushed the mikenomitch/add-containers-docs branch from 7df8b01 to 3954f36 Compare June 21, 2025 18:22

Adds Containers docs

8f0f7c1

Fixes bad links

78247ec

ichernetsky-cf reviewed Jun 23, 2025

View reviewed changes

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

kodster28 added 2 commits June 23, 2025 10:10

replace icon

8a0e3b3

remove extra file

fd6d4d3

kodster28 approved these changes Jun 23, 2025

View reviewed changes

nikitassharma reviewed Jun 23, 2025

View reviewed changes

mikenomitch and others added 2 commits June 24, 2025 04:53

Apply suggestions from code review

53addbe

Various small fixes Co-authored-by: Nikita Sharma <54369599+nikitassharma@users.noreply.github.com>

Removes unnecessary pre-req and wrong TCP statement

9d673ac

irvinebroque reviewed Jun 24, 2025

View reviewed changes

Apply suggestions from code review

55e4850

Co-authored-by: Brendan Irvine-Broque <birvine-broque@cloudflare.com>

nikitassharma reviewed Jun 24, 2025

View reviewed changes

src/content/docs/containers/index.mdx Outdated Show resolved Hide resolved

skepticfx approved these changes Jun 24, 2025

View reviewed changes

irvinebroque reviewed Jun 24, 2025

View reviewed changes

src/content/docs/containers/pricing.mdx Outdated Show resolved Hide resolved

irvinebroque reviewed Jun 24, 2025

View reviewed changes

src/content/docs/containers/examples/index.mdx Outdated Show resolved Hide resolved

Apply suggestions from code review

8f96822

irvinebroque reviewed Jun 24, 2025

View reviewed changes

Update pricing docs, make sure to clarify what is part of Workers Pai…

11092b7

…d plan

emily-shen reviewed Jun 24, 2025

View reviewed changes

emily-shen mentioned this pull request Jun 24, 2025

Update containers config types cloudflare/workers-sdk#9722

Merged

12 tasks

This was referenced Jun 24, 2025

Fix container engine config cloudflare/workers-sdk#9689

Merged

Add default value for container apps if no name is present cloudflare/workers-sdk#9666

Merged

Various tweaks

724267a

gabivlj approved these changes Jun 24, 2025

View reviewed changes

mikenomitch merged commit cc5260a into production Jun 24, 2025
10 checks passed

mikenomitch deleted the mikenomitch/add-containers-docs branch June 24, 2025 15:02

	This uses a simple `getRandom` helper method currently, which picks an ID at random
	This uses a simple `getRandom` helper method, which picks an ID at random

	from a set number (in this case 3), then routes to that Container instance.
	from a set number (in this case 3), then routes to that Container instance. You can replace this with any routing or load balancing logic you choose to implement:

	This is a temporary solution until first-party support for utilization-aware autoscaling
	This is temporary — we plan to add native support for latency-aware autoscaling and load balancing in the coming months.


		import { WranglerConfig } from "~/components";

		This page containers general details about the Containers platform.

	There are currently three instance types available for Containers users by default:
	Three instance types are currently available:

	These are specified using the `instance_type` property in wrangler config.
	These are specified using the [`instance_type` property](/workers/wrangler/configuration/#containers) in your Worker's Wrangler configuration file. Looking for larger instances? [Give us feedback here](/containers/beta-info/#feedback-wanted) and tell us what size instances you need, and what you want to use them for.


		## Limits

		Containers limits are currently set per account. You may have higher

	\| GB Memory for concurrent live Container instances \| 40GB [^1] \|
	\| GB Memory for all concurrent live Container instances \| 40GB [^1] \|

	\| vCPU for concurrent live Container instances \| 20 [^1] \|
	\| vCPU for all concurrent live Container instances \| 20 [^1] \|

	\| GB Disk for concurrent live Container instances \| 100GB [^1] \|
	\| GB Disk for all concurrent live Container instances \| 100GB [^1] \|

	\| Total image storage for account \| 50 GB [^2] \|
	\| Total image storage per account \| 50 GB [^2] \|


		[^1]: This limit will be raised as we continue the beta.

		[^2]: Delete images with `wrangler containers delete` to free up space. Note that reverted Workers may then break.

	[^2]: Delete images with `wrangler containers delete` to free up space. Note that reverted Workers may then break.
	[^2]: Delete container images with `wrangler containers delete` to free up space. Note that if you delete a container image and then [roll back](/workers/configuration/versions-and-deployments/rollbacks/) your Worker to a previous version, this version may no longer work.

	If your Worker app creates many container instances, you may hit local limits
	If your Worker app creates many container instances, your local machine may not be able to run as many containers concurrently as is possible when you deploy to Cloudflare.


		## Iterating on Container code

		When using `wrangler dev`, standard Worker code is automatically reloaded by wrangler you save a change,

	When using `wrangler dev`, standard Worker code is automatically reloaded by wrangler you save a change,
	When you use `wrangler dev`, your Worker's code is automatically reloaded by Wrangler each time you save a change,

	If you wish to rebuild your container with new code changes, you can hit the `[r]` key on your keyboard, and a
	To rebuild your container with new code changes, you can hit the `[r]` key on your keyboard, which

	rebuild will be triggered. Instances will be restarted with the new images.
	triggers a rebuild. Container instances will then be restarted with the newly built images.

	You may prefer to set up your code watchers and reloading mechanisms, or mount a local directory
	You may prefer to set up your own code watchers and reloading mechanisms, or mount a local directory


		## Using existing images

		If you wish to use a pre-built image, first, push it to the Cloudflare Registry:

Conversation

mikenomitch commented Jun 21, 2025

Summary

Documentation checklist

Uh oh!

github-actions bot commented Jun 21, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

irvinebroque left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

irvinebroque left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

irvinebroque left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

irvinebroque left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

	Docker compatible CLI tool is installed. For instance, you can use [Docker Desktop](https://docs.docker.com/desktop/)
	Docker compatible CLI tool and engine is installed. For instance, you can use [Docker Desktop](https://docs.docker.com/desktop/)


		### Reduction of log noise

		Currently, the `Container` class uses Durable Object alarms to help manage Container shutdown. This