Skip to content

Commit 3954f36

Browse files
mikenomitchmikenomitch
committed
Adds Containers docs
1 parent aa7c5e0 commit 3954f36

24 files changed

+2138
-0
lines changed

‎src/content/docs/containers/architecture.mdx

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
pcx_content_type: reference
3+
title: Architecture
4+
sidebar:
5+
order: 9
6+
---
7+
8+
### How and where containers run
9+
10+
After you deploy a Worker that uses a Container, your image is uploaded to
11+
[Cloudflare's Registry](/containers/image-management) and distributed globally to Cloudflare's Network.
12+
Cloudflare will pre-schedule instances and pre-fetch images across the globe to ensure quick start
13+
times when scaling up the number of concurrent container instances. This allows you to call
14+
`env.YOUR_CONTAINER.get(id)` and get a new instance quickly without worrying
15+
about the underlying scaling.
16+
17+
When a request is made to start a new container instance, the nearest location
18+
with a pre-fetched image is selected. Subsequent requests to the same instance,
19+
regardless of where they originate, will be routed to this location as long as
20+
the instance stays alive.
21+
22+
Starting additional container instances will use other locations with pre-fetched images,
23+
and Cloudflare will automatically begin prepping additional machines behind the scenes
24+
for additional scaling and quick cold starts. Because there are a finite number pre-warmed
25+
locations, some container instances may be started in locations that are farther away from
26+
the end-user. This is done to ensure that the container instance starts quickly. You are
27+
only charged for actively running instances and not for any unused pre-warmed images.
28+
29+
Each container instance runs inside its own VM, which provides strong
30+
isolation from other workloads running on Cloudflare's network. Containers
31+
should be built for the `linux/amd64` architecture, and should stay within
32+
[size limits](/containers/platform-details/#limits). Logging, metrics collection, and
33+
networking are automatically set up on each container.
34+
35+
### Life of a Container Request
36+
37+
When a request is made to any Worker, including one with an associated Container, it is generally handled
38+
by a datacenter in a location with the best latency between itself and the requesting user.
39+
A different datacenter may be selected to optimize overall latency, if [Smart Placement](/workers/configuration/smart-placement/)
40+
is on, or if the nearest location is under heavy load.
41+
42+
When a request is made to a Container instance, it is sent through a Durable Object, which
43+
can be defined by either using a `DurableObject` or the [`Container` class](/containers/container-package), which
44+
extends Durable Objects with Container-specific APIs and helpers. We recommend using `Container`, see
45+
the [`Container` class documentation](/containers/container-package) for more details.
46+
47+
Each Durable Object is a globally routable isolate that can execute code and store state. This allows
48+
developers to easily address and route to specific container instances (no matter where they are placed)
49+
define and run hooks on container status changes, execute recurring checks on the instance, and store persistent
50+
state associated with each instance.
51+
52+
As mentioned above, when a container instance starts, it is launched in the nearest pre-warmed location. This means that
53+
code in a container is usually executed in a different location than the one handling the Workers request.
54+
55+
:::note
56+
Currently, Durable Objects may be co-located with their associated Container instance, but often are not.
57+
58+
Cloudflare is currently working on expanding the number of locations in which a Durable Object can run,
59+
which will allow container instances to always run in the same location as their Durable Object.
60+
:::
61+
62+
Because all Container requests are passed through a Worker, end-users cannot make TCP or
63+
UDP requests to a Container instance. Workers themselves cal make TCO and UDP requests to
64+
the Container using the [`connect()` API](/workers/runtime-apis/tcp-sockets/#connect). If you have a use
65+
case that requires inbound TCP or UDP from an end-user, please [let us know](https://forms.gle/AGSq54VvUje6kmKu8).

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

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
pcx_content_type: reference
3+
title: Beta Info & Roadmap
4+
sidebar:
5+
order: 2
6+
---
7+
8+
Currently, Containers are in beta. There are several changes we plan to make prior to GA:
9+
10+
## Upcoming Changes and Known Gaps
11+
12+
### Limits
13+
14+
Container limits will be raised in the future. We plan to increase
15+
both maximum instance size and maximum number of instances in an account.
16+
17+
See the [Limits documentation](/containers/limits) for more information.
18+
19+
### Autoscaling and load balancing
20+
21+
Currently, Containers are not autoscaled or load balanced. Containers can be scaled manually
22+
by calling `get()` on their binding with a unique ID.
23+
24+
We plan to add official support for utilization-based autoscaling and latency-aware load balancing
25+
in the future.
26+
27+
See the [Autoscaling documentation](/containers/scaling-and-routing) for more information.
28+
29+
### Reduction of log noise
30+
31+
Currently, the `Container` class uses Durable Object alarms to help manage Container shutdown. This
32+
results in unnecessary log noise in the Worker logs. You can filter these logs out in the dashboard
33+
by adding a Query, but this is not ideal.
34+
35+
We plan to automatically reduce log noise in the future.
36+
37+
### Dashboard Updates
38+
39+
The dashboard will be updated to show:
40+
41+
- the status of Container rollouts.
42+
- links from Workers to their associated Containers
43+
44+
### Co-locating Durable Objects and Containers
45+
46+
Currently, Durable Objects are not co-located with their associated Container. When requesting a container,
47+
the Durable Object will find one close to it, but not on the same machine.
48+
49+
We plan to co-locate Durable Objects with their Container in the future.
50+
51+
### More advanced Container placement
52+
53+
We currently prewarm servers across our global network with container images to ensure quick start times.
54+
There are times in which you may request a new container and it will be started in a location that
55+
farther from the end user than is desired. We are optimizing this process to ensure that this happens
56+
as little as possible, but it may still occur.
57+
58+
### Atomic code updates across Workers and Containers
59+
60+
When deploying a Container with `wrangler deploy`, the Worker code will be immediately
61+
updated while the Container code will slowly be updated using a rolling deploy.
62+
63+
This means that you must ensure Worker code is backwards compatible with the old Container code.
64+
65+
In the future, Worker code in the Durable Object will only update when associated Container code updates.
66+
67+
## Feedback wanted
68+
69+
There are several areas where we wish to gather feedback from users:
70+
71+
- Do you want to integrate Containers with any other Cloudflare services? If so, which ones and how?
72+
- Do you want more ways to interact with a Container via Workers? If so, how?
73+
- Do you need different mechanisms for routing requests to containers?
74+
- Do you need different mechanisms for scaling containers? (see scaling documentation for information on autoscaling plans)
75+
76+
At any point during the Beta, feel free to [give feedback using this form](https://forms.gle/CscdaEGuw5Hb6H2s7).

‎src/content/docs/containers/container-package.mdx

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
pcx_content_type: navigation
3+
title: Container Package
4+
sidebar:
5+
order: 8
6+
---
7+
8+
When writing code that interacts with a container instance, you can either use a
9+
Durable Object directly or use the [`Container` module](https://github.com/cloudflare/containers)
10+
importable from [`@cloudflare/containers`](https://www.npmjs.com/package/@cloudflare/containers).
11+
12+
```javascript
13+
import { Container } from "@cloudflare/containers";
14+
15+
class MyContainer extends Container {
16+
defaultPort = 8080;
17+
sleepAfter = "5m";
18+
}
19+
```
20+
21+
We recommend using the `Container` class for most use cases.
22+
23+
Install it with `npm install @cloudflare/containers`.
24+
25+
The `Container` class extends `DurableObject` so all Durable Object functionality is available.
26+
It also provides additional functionality and a nice interface for common container behaviors,
27+
such as:
28+
29+
- sleeping instances after an inactivity timeout
30+
- making requests to specific ports
31+
- running status hooks on startup, stop, or error
32+
- awaiting specific ports before making requests
33+
- setting environment variables and secrets
34+
35+
See the [Containers GitHub repo](https://github.com/cloudflare/containers) for more details
36+
and the complete API.

‎src/content/docs/containers/durable-object-methods.mdx

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
pcx_content_type: navigation
3+
title: Durable Object Interface
4+
external_link: /durable-objects/api/container/
5+
sidebar:
6+
order: 81
7+
---

0 commit comments

Comments
 (0)