diff --git a/public/__redirects b/public/__redirects index 2702c2b0734..2a5f6efe42c 100644 --- a/public/__redirects +++ b/public/__redirects @@ -641,10 +641,14 @@ /constellation/ /workers-ai/ 301 # Containers /containers/beta-info/ /containers/faq/ 301 -/containers/container-package/ /containers/reference/container-class/ 301 -/containers/durable-object-methods/ /durable-objects/api/container/ 301 +# Containers API +/containers/container-package/ /containers/api/container-class/ 301 +/containers/durable-object-methods/ /containers/api/durable-object-container/ 301 +/containers/container-class/ /containers/api/container-class/ 301 +/containers/reference/container-class/ /containers/api/container-class/ 301 +/containers/reference/durable-object-methods/ /containers/api/durable-object-container/ 301 +/durable-objects/api/container/ /containers/api/durable-object-container/ 301 # Containers IA rework: loose pages folded into core sections -/containers/container-class/ /containers/reference/container-class/ 301 /containers/local-dev/ /containers/guides/local-dev/ 301 /containers/deploy/ /containers/guides/deploy/ 301 /containers/execute-commands/ /containers/guides/execute-commands/ 301 @@ -663,7 +667,7 @@ /containers/platform-details/scaling-and-routing/ /containers/configuration/scaling-and-routing/ 301 /containers/platform-details/limits/ /containers/platform/limits/ 301 /containers/platform-details/image-management/ /containers/guides/image-management/ 301 -/containers/platform-details/durable-object-methods/ /durable-objects/api/container/ 301 +/containers/platform-details/durable-object-methods/ /containers/api/durable-object-container/ 301 /containers/platform-details/ /containers/concepts/architecture/ 301 # Containers IA rework: Configuration section + Local Development to Guides + Wrangler pages to Reference /containers/guides/outbound-traffic/ /containers/configuration/outbound-traffic/ 301 diff --git a/src/content/docs/containers/reference/container-class.mdx b/src/content/docs/containers/api/container-class.mdx similarity index 98% rename from src/content/docs/containers/reference/container-class.mdx rename to src/content/docs/containers/api/container-class.mdx index 1c32036aac7..2d1cdfacf7c 100644 --- a/src/content/docs/containers/reference/container-class.mdx +++ b/src/content/docs/containers/api/container-class.mdx @@ -1,16 +1,18 @@ --- pcx_content_type: reference -title: Container Interface +title: Container class sidebar: - order: 1 -description: API reference for the Container interface and utility functions + order: 2 +description: API reference for the Container class and its built-in lifecycle helpers. products: - containers --- import { PackageManagers, TypeScriptExample } from "~/components"; -The [`Container` class](https://github.com/cloudflare/containers) from [`@cloudflare/containers`](https://www.npmjs.com/package/@cloudflare/containers) is the most common way to interact with container instances from a Worker. +The [`Container` class](https://github.com/cloudflare/containers) from [`@cloudflare/containers`](https://www.npmjs.com/package/@cloudflare/containers) provides lifecycle helpers for container instances. For direct lifecycle control, use the [Durable Object Container API](/containers/api/durable-object-container/). + +To move an existing application to direct control, refer to [Migrate to the Durable Object Container API](/containers/guides/migrate-to-durable-object-container-api/). **`Container` extends [`DurableObject`](/durable-objects/api/base/).** The Durable Object manages routing, persistent state, and lifecycle hooks, while the container process runs your image inside a Linux VM. Because your subclass is a Durable Object, you have access to the full Durable Object API — including [`this.ctx.storage`](/durable-objects/api/sqlite-storage-api/) for persistent SQLite-backed storage and [`this.ctx.id`](/durable-objects/api/id/) for the unique instance identifier. Use Durable Object storage to persist state that should survive container restarts, such as configuration, user data, or task results. diff --git a/src/content/docs/containers/api/durable-object-container.mdx b/src/content/docs/containers/api/durable-object-container.mdx new file mode 100644 index 00000000000..5546b1c9a90 --- /dev/null +++ b/src/content/docs/containers/api/durable-object-container.mdx @@ -0,0 +1,376 @@ +--- +title: Durable Object Container API +description: Access and manage containers associated with a Durable Object, including start, stop, and interaction methods. +pcx_content_type: reference +sidebar: + order: 1 +products: + - containers + - durable-objects +--- + +import { TypeScriptExample } from "~/components"; + +Each [container](/containers/) is managed and proxied by a Durable Object. The Durable Object manages routing and persistent state. The container process runs your image inside a Linux VM. + +The API documented on this page is available on `this.ctx.container` inside any Durable Object class that has a container binding. Use it for direct control over the container process. + +:::note +We recommend starting new applications with the Durable Object Container API. It lets you run container workloads alongside the Durable Object's persistent storage, alarms, and request handling. Use `ctx.container` to control when the container starts, receives traffic, and stops, while the Durable Object manages application state and coordination. For existing applications that use the `Container` class, refer to [Migrate to the Durable Object Container API](/containers/guides/migrate-to-durable-object-container-api/). +::: + +Your Durable Object also has access to [SQLite storage](/durable-objects/api/sqlite-storage-api/) through `this.ctx.storage`, [alarms](/durable-objects/api/alarms/), and all other Durable Object APIs. Use storage to preserve configuration and state across container restarts. Use alarms to schedule work without keeping the container running. + + + +```ts +import { DurableObject } from "cloudflare:workers"; + +interface Env {} + +export class MyDurableObject extends DurableObject { + async start(): Promise { + const container = this.ctx.container; + if (!container) { + throw new Error("No container is configured for this Durable Object"); + } + if (!container.running) { + container.start(); + await this.ctx.storage.put("lastStartedAt", Date.now()); + } + } + + async scheduleStart(timestamp: number): Promise { + await this.ctx.storage.setAlarm(timestamp); + } + + async alarm(): Promise { + await this.start(); + } +} +``` + + + +## Attributes + +### `running` + +`running` is `true` when the container is running. It does not confirm that the container is ready to accept requests. + +```js +this.ctx.container.running; +``` + +## Methods + +### `start` + +`start()` boots a container. It returns before the container is ready to accept requests. Confirm readiness before sending traffic. + +```js +this.ctx.container.start(); +``` + +#### Parameters + +- `options` (`object`, optional): Common container startup options: + - `env` (`Record`, optional): Environment variables to pass to the container. + - `entrypoint` (`string[]`, optional): Command and arguments to run in the container. + - `enableInternet` (`boolean`, required): Whether to allow outbound Internet access. Required when you pass `options`. + +#### Return values + +- `void`: No return value. + +### `exec` + +`exec()` starts another process inside an already-running container. It does not start a stopped container. + +```txt +exec( + cmd: string[], + options?: ContainerExecOptions, +): Promise +``` + +`exec()` starts the executable directly with the provided arguments. It does not start a shell or interpret pipes, redirects, expansion, or other shell syntax. Invoke Bash explicitly with `["bash", "-lc", ""]` when Bash exists in the image. Use `["sh", "-c", ""]` for images with only a Portable Operating System Interface (POSIX) shell. + +The following RPC method checks that the container is running before executing a command: + + + +```ts +import { DurableObject } from "cloudflare:workers"; + +interface Env {} + +export class MyDurableObject extends DurableObject { + async runCommand() { + const container = this.ctx.container; + if (!container) { + throw new Error("No container is configured for this Durable Object"); + } + if (!container.running) { + throw new Error("Container is not running"); + } + + const process = await container.exec(["node", "--version"]); + const output = await process.output(); + + return { + pid: process.pid, + exitCode: output.exitCode, + stdout: new TextDecoder().decode(output.stdout), + }; + } +} +``` + + + +#### Parameters + +- `cmd` (`string[]`): Executable followed by its arguments. +- `options` (`ContainerExecOptions`, optional): Process configuration: + - `stdin` (`ReadableStream | "pipe"`, optional): Source for standard input. Use `"pipe"` to write through the returned `stdin` stream. When omitted, standard input closes and sends end-of-file (EOF). + - `stdout` (`"pipe" | "ignore"`, optional, default `"pipe"`): Captures or discards standard output. + - `stderr` (`"pipe" | "ignore" | "combined"`, optional, default `"pipe"`): Captures, discards, or merges standard error into standard output. The `"combined"` value requires `stdout: "pipe"`. Combined output does not guarantee ordering between its source streams. + - `cwd` (`string`, optional): Working directory for the process. + - `env` (`Record`, optional): Environment additions and overrides. The process inherits existing container variables. Matching keys use the per-execution value. + - `user` (`string`, optional): Image user for the process. + +#### Return values + +- `Promise`: Resolves with an `ExecProcess` for the started process. + +An `ExecProcess` has these fields and methods: + +- `stdin` (`WritableStream | null`): Writable standard input when `stdin` is `"pipe"`. +- `stdout` (`ReadableStream | null`): Readable standard output when piped. +- `stderr` (`ReadableStream | null`): Readable standard error when piped separately. +- `pid` (`number`): Process identifier. +- `exitCode` (`Promise`): Resolves when the process exits. Nonzero codes resolve normally instead of rejecting. +- `output()` (`Promise`): Reads buffered output once. `ExecOutput` contains `stdout` (`ArrayBuffer`), `stderr` (`ArrayBuffer`), and `exitCode` (`number`). Ignored streams produce empty buffers. Use `TextDecoder` to decode text. +- `kill(signal?: number)` (`void`): Queues a signal for the process. The default is `SIGTERM`, signal `15`. The signal must be from `1` through `64`. + +With `stderr: "combined"`, `stderr` is `null` on `ExecProcess` and an empty `ArrayBuffer` on `ExecOutput`. Read both output channels from `stdout`. + +`output()` throws a `TypeError` when called more than once or after either readable stream starts being consumed. For large output, consume both readable streams concurrently instead of buffering them with `output()`. + +`exec()` has no built-in timeout. Use `kill()` to request termination, then observe completion through `exitCode`. A process can handle or ignore a signal, so this does not enforce a hard deadline. Do not infer a specific exit code from the signal. + +#### Exceptions + +- `exec()` throws when the container is not running. +- `exec()` throws a `TypeError` when `cmd` is empty, an option mode is invalid, or `stderr: "combined"` is used with `stdout: "ignore"`. +- `exec()` rejects if the runtime cannot create or start the process. +- Environment variable names cannot contain `=` or null characters. Environment values, `cwd`, and `user` cannot contain null characters. +- `kill()` throws a `RangeError` when the signal is outside the supported range. + +For task-oriented examples, refer to [Execute commands](/containers/guides/execute-commands/). + +### `destroy` + +`destroy()` stops the container and can include an optional reason for the operation. + +```js +await this.ctx.container.destroy("Manually Destroyed"); +``` + +#### Parameters + +- `error` (`any`, optional): Optional reason associated with the destroy operation. A string is commonly used for logging or debugging. + +#### Return values + +- `Promise`: Resolves when the container is destroyed. + +### `signal` + +`signal()` sends an inter-process communication (IPC) signal to the container, such as `SIGKILL` or `SIGTERM`. Use it to stop the container gracefully or forcefully. + +```js +const SIGTERM = 15; +this.ctx.container.signal(SIGTERM); +``` + +#### Parameters + +- `signal` (`number`): POSIX signal number to send to the container, such as `SIGTERM` (`15`) or `SIGKILL` (`9`). + +#### Return values + +- `void`: No return value. + +### `setInactivityTimeout` + +`setInactivityTimeout()` sets how long a running container can remain inactive before the runtime stops it. + +```txt +setInactivityTimeout(durationMs: number | bigint): Promise +``` + +```js +await this.ctx.container.setInactivityTimeout(10 * 60 * 1000); +``` + +#### Parameters + +- `durationMs` (`number | bigint`): Inactivity timeout in milliseconds. + +#### Return values + +- `Promise`: Resolves after the timeout is set. + +### `getTcpPort` + +`getTcpPort()` returns a TCP port from the container. Use it to communicate with the container over TCP or HTTP. + +```js +const port = this.ctx.container.getTcpPort(8080); +const res = await port.fetch("http://container/set-state", { + body: initialState, + method: "POST", +}); +``` + +```js +const conn = this.ctx.container.getTcpPort(8080).connect("10.0.0.1:8080"); +await conn.opened; + +try { + if (request.body) { + await request.body.pipeTo(conn.writable); + } + return new Response(conn.readable); +} catch (error) { + console.error("Request body piping failed:", error); + return new Response("Failed to proxy request body", { status: 502 }); +} +``` + +#### Parameters + +- `port` (`number`): TCP port number to use for communication with the container. + +#### Return values + +- `Fetcher`: Object used to send HTTP requests or TCP connections to the container port. + +### `monitor` + +`monitor()` returns a promise that resolves when a container exits and rejects if the container errors. Use it to handle container status changes in your Workers code. + + + +```ts +import { DurableObject } from "cloudflare:workers"; + +interface Env {} + +class MyDurableObject extends DurableObject { + startAndMonitor() { + const container = this.ctx.container; + container.start(); + this.ctx.waitUntil( + container + .monitor() + .then(() => console.log("Container exited")) + .catch((error) => console.error("Container errored", error)), + ); + } +} +``` + + + +#### Parameters + +- None. + +#### Return values + +- `Promise`: Resolves when the container exits. + +### `interceptOutboundHttp` + +`interceptOutboundHttp()` routes outbound HTTP requests matching a hostname, hostname glob, IP address, IP:port, or CIDR range through a `Fetcher`. Call it before or after starting the container. Open connections use the new handler without being dropped. + +```js +const worker = this.ctx.exports.MyWorker({ props: { message: "hello" } }); + +// Match a specific hostname +await this.ctx.container.interceptOutboundHttp("api.example.com", worker); + +// Match a hostname glob pattern +await this.ctx.container.interceptOutboundHttp("*.example.com", worker); + +// Match an IP:port +await this.ctx.container.interceptOutboundHttp("15.0.0.1:80", worker); + +// Match a CIDR range (IPv4 and IPv6) +await this.ctx.container.interceptOutboundHttp("123.123.123.123/23", worker); +``` + +#### Parameters + +- `addr` (`string`): Hostname, hostname glob (for example, `*.example.com`), IP address, IP:port, or CIDR range to match. +- `binding` (`Fetcher`): Worker entrypoint or service binding that handles matching requests. + +#### Return values + +- `Promise`: Resolves when the intercept rule is installed. + +### `interceptAllOutboundHttp` + +`interceptAllOutboundHttp()` routes all outbound HTTP requests from the container through a `Fetcher`, regardless of destination. + +```js +await this.ctx.container.interceptAllOutboundHttp(worker); +``` + +#### Parameters + +- `binding` (`Fetcher`): Worker entrypoint or service binding that handles all outbound HTTP requests. + +#### Return values + +- `Promise`: Resolves when the intercept rule is installed. + +### `interceptOutboundHttps` + +`interceptOutboundHttps()` routes outbound HTTPS requests matching a hostname or hostname glob through a `Fetcher`. It works like `interceptOutboundHttp()` but handles HTTPS traffic. The container must trust the CA certificate at `/etc/cloudflare/certs/cloudflare-containers-ca.crt` for HTTPS interception. + +Hostname globs support `*` to match any sequence of characters. + +```js +const worker = this.ctx.exports.MyWorker({ props: {} }); + +// Match a specific hostname +await this.ctx.container.interceptOutboundHttps("api.example.com", worker); + +// Match a hostname glob pattern +await this.ctx.container.interceptOutboundHttps("*.example.com", worker); + +// Intercept all HTTPS traffic +await this.ctx.container.interceptOutboundHttps("*", worker); +``` + +#### Parameters + +- `addr` (`string`): Hostname or hostname glob pattern to match. Use `*` to intercept all HTTPS traffic. +- `binding` (`Fetcher`): Worker entrypoint or service binding that handles matching requests. + +#### Return values + +- `Promise`: Resolves when the intercept rule is installed. + +## Related resources + +- [Containers APIs](/containers/api/): Compare direct runtime control with the `Container` class. +- [Container class reference](/containers/api/container-class/): Reference for existing `Container` class applications. +- [Containers overview](/containers/): Understand how Cloudflare Containers work. +- [Get started with Containers](/containers/get-started/): Deploy your first container. +- [SQLite storage API](/durable-objects/api/sqlite-storage-api/): Persist state across container restarts. +- [Durable Objects](/durable-objects/): The underlying platform that powers Containers. diff --git a/src/content/docs/containers/api/index.mdx b/src/content/docs/containers/api/index.mdx new file mode 100644 index 00000000000..57cd15d8790 --- /dev/null +++ b/src/content/docs/containers/api/index.mdx @@ -0,0 +1,104 @@ +--- +pcx_content_type: navigation +title: API +description: Use the Durable Object Container API for new applications and compare it with the Container class. +sidebar: + order: 6 +products: + - containers + - durable-objects +--- + +import { CardGrid, LinkTitleCard, TabItem, Tabs } from "~/components"; + +Containers provide two APIs for managing a container from a Durable Object. Both APIs address the same container runtime. + +For new applications, we recommend the Durable Object Container API. It lets you combine container workloads with the Durable Object's persistent storage, alarms, and request handling. Use `ctx.container` to control the container lifecycle while your Durable Object coordinates application state. The `Container` class remains documented for existing applications. + + + + + Start, stop, monitor, and connect to a container through `ctx.container`. + + + + Reference the class and its routing, readiness checks, lifecycle hooks, and + scheduling for existing applications. + + + + +## Choose an API + +Inside a Durable Object, use `ctx.container` to control the container runtime directly. You can manage startup, shutdown, networking, and resource usage while using Durable Object storage and alarms for state and coordination. Add readiness checks, custom request routing, or lifecycle policies when needed. + +The `Container` class extends `DurableObject` and wraps the container runtime API with convenience methods. Existing applications can use these methods for request proxying, readiness checks, lifecycle hooks, and scheduling. Durable Object storage and alarms remain available when needed. + +The following examples compare the starting structure for each API: + + + + +```ts title="src/index.ts" +import { DurableObject } from "cloudflare:workers"; + +interface Env {} + +export class MyContainer extends DurableObject { + fetch(): Response { + const container = this.ctx.container; + if (!container) { + return new Response("No container is configured", { status: 500 }); + } + if (container.running) { + return new Response("Container is running"); + } + container.start(); + return new Response("Container is starting", { status: 202 }); + } +} +``` + + + + + +```ts title="src/index.ts" +import { Container } from "@cloudflare/containers"; + +export class MyContainer extends Container { + defaultPort = 8080; + sleepAfter = "10m"; +} +``` + + + + + +Starting a container through the Durable Object Container API does not mean its ports are ready. For request routing, use [`getTcpPort()`](/containers/api/durable-object-container/#gettcpport) after checking port readiness. For all direct methods, refer to the [Durable Object Container API](/containers/api/durable-object-container/). For convenience methods, refer to the [Container class API](/containers/api/container-class/). + +The following table compares both options: + +| Requirement | Durable Object Container API | `Container` class | +| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Start and stop a container | [`start()`](/containers/api/durable-object-container/#start), [`signal()`](/containers/api/durable-object-container/#signal), and [`destroy()`](/containers/api/durable-object-container/#destroy) | [`start()`](/containers/api/container-class/#start), [`stop()`](/containers/api/container-class/#stop), and [`destroy()`](/containers/api/container-class/#destroy) | +| Send and proxy traffic | [`getTcpPort(port).fetch()`](/containers/api/durable-object-container/#gettcpport) and [`getTcpPort(port).connect()`](/containers/api/durable-object-container/#gettcpport) | [`fetch()`](/containers/api/container-class/#fetch) and [`containerFetch()`](/containers/api/container-class/#containerfetch) | +| Execute another process | [`exec()`](/containers/api/durable-object-container/#exec) | [`ctx.container.exec()`](/containers/api/container-class/#execute-commands) | +| Check port readiness | Use [`getTcpPort()`](/containers/api/durable-object-container/#gettcpport) in application code | [`startAndWaitForPorts()`](/containers/api/container-class/#startandwaitforports) and [`waitForPort()`](/containers/api/container-class/#waitforport) | +| Handle concurrent starts | Coordinate calls to [`start()`](/containers/api/durable-object-container/#start) when needed | Handled by [`start()`](/containers/api/container-class/#start) and [`startAndWaitForPorts()`](/containers/api/container-class/#startandwaitforports) | +| Run lifecycle hooks | [`monitor()`](/containers/api/durable-object-container/#monitor) and application code | [`onStart()`](/containers/api/container-class/#onstart), [`onStop()`](/containers/api/container-class/#onstop), [`onError()`](/containers/api/container-class/#onerror), and [`onActivityExpired()`](/containers/api/container-class/#onactivityexpired) | +| Stop inactive containers | [`setInactivityTimeout()`](/containers/api/durable-object-container/#setinactivitytimeout) | [`sleepAfter`](/containers/api/container-class/#sleepafter) and [`onActivityExpired()`](/containers/api/container-class/#onactivityexpired) | +| Schedule callbacks | [`ctx.storage.setAlarm()`](/durable-objects/api/alarms/#setalarm) (Durable Object API) | [`schedule()`](/containers/api/container-class/#schedule) | + +For new applications, use the Durable Object Container API to combine direct container control with Durable Object storage and coordination. It also supports latency-sensitive workloads and applications that need a smaller storage footprint. + +If your application uses the `Container` class, refer to [Migrate to the Durable Object Container API](/containers/guides/migrate-to-durable-object-container-api/). diff --git a/src/content/docs/containers/concepts/architecture.mdx b/src/content/docs/containers/concepts/architecture.mdx index 4b3c7b4da8a..dbdd81beb46 100644 --- a/src/content/docs/containers/concepts/architecture.mdx +++ b/src/content/docs/containers/concepts/architecture.mdx @@ -17,7 +17,38 @@ times when scaling up the number of concurrent container instances. Worker code goes live on deploy. Container instances update with a [rollout](/containers/configuration/rollouts/). Refer to [Deploy Containers](/containers/guides/deploy/). -## Lifecycle of a Request +## Container instance lifecycle + +```mermaid +flowchart LR + accTitle: Container instance lifecycle + accDescr: A Worker accesses a container through its Durable Object. The container moves from stopped to starting, running but not ready, ready for traffic, stopping, and stopped. + + Worker["Worker"] -->|Durable Object binding| DurableObject["Durable Object"] + DurableObject -->|ctx.container| Container + + subgraph Container["Container instance"] + direction TD + Stopped["Stopped"] + Starting["Starting
start() called"] + Running["Running
Not ready"] + Ready["Ready
Accepting traffic"] + Stopping["Stopping
Stop requested"] + StoppedAgain["Stopped"] + + Stopped --> Starting --> Running --> Ready --> Stopping --> StoppedAgain + end +``` + +A Container can only be accessed through its [Durable Object](/durable-objects/). A Worker sends a request to the Durable Object, which accesses the Container through `ctx.container`. + +An inactivity timeout, `signal()`, `destroy()`, a rollout, or a process exit can stop the instance. If startup fails or the process exits early, the instance returns to the stopped state. + +The `ctx.container.running` property becomes `true` before the process is ready to accept traffic. Check port readiness before you send the first request. + +For new applications, manage this lifecycle through the [Durable Object Container API](/containers/api/durable-object-container/). It lets the Durable Object coordinate container compute with persistent state and alarms. Existing applications may use the [`Container` class](/containers/api/container-class/). To compare both APIs, refer to [Containers APIs](/containers/api/). + +## Lifecycle of a request ### Client to Worker @@ -33,11 +64,9 @@ or UDP from an end-user, please [let us know](https://forms.gle/AGSq54VvUje6kmKu ### Worker to Durable Object -From the Worker, a request passes through a Durable Object instance (the [Container class](/containers/reference/container-class/) extends a Durable Object class). +From the Worker, a request passes through a Durable Object instance. You can extend `DurableObject` and use `ctx.container` directly, or extend the [`Container` class](/containers/api/container-class/). Each Durable Object instance is a globally routable isolate that can execute code and store state. This allows -developers to easily address and route to specific container instances (no matter where they are placed), -define and run hooks on container status changes, execute recurring checks on the instance, and store persistent -state associated with each instance. +developers to address and route to specific container instances, run code when a container exits, and store persistent state associated with each instance. ### Starting a Container @@ -91,9 +120,9 @@ should be built for the `linux/amd64` architecture, and should stay within ### Container shutdown -The Container class sets [`sleepAfter`](/containers/reference/container-class/#sleepafter) to 10 minutes by default. Its default [`onActivityExpired()`](/containers/reference/container-class/#onactivityexpired) implementation signals the container to stop after that period without activity. You can change the duration or override the hook. +With the Durable Object Container API, call [`setInactivityTimeout()`](/containers/api/durable-object-container/#setinactivitytimeout) to let the runtime stop the container after the Durable Object becomes inactive. The Durable Object becomes inactive when it stops receiving requests. The timeout can keep the container available while the Durable Object sleeps. You can also stop a container with [`signal()`](/containers/api/durable-object-container/#signal) or [`destroy()`](/containers/api/durable-object-container/#destroy). -You can stop a container instance yourself with [`stop()`](/containers/reference/container-class/#stop) or [`destroy()`](/containers/reference/container-class/#destroy). +The `Container` class sets [`sleepAfter`](/containers/api/container-class/#sleepafter) to 10 minutes by default. Its [`onActivityExpired()`](/containers/api/container-class/#onactivityexpired) implementation calls [`stop()`](/containers/api/container-class/#stop). You can change the duration or override the hook. When the platform is about to stop a container instance, it: @@ -103,14 +132,16 @@ When the platform is about to stop a container instance, it: Handle `SIGTERM` in your image if you need cleanup before exit. The same sequence runs when a [rollout](/containers/configuration/rollouts/) replaces a container instance with a new image. -### Lifecycle hooks +### Lifecycle events + +The Durable Object Container API provides [`monitor()`](/containers/api/durable-object-container/#monitor). Its promise resolves when the container exits and rejects when the container errors. -The [`Container` class](/containers/reference/container-class/) provides hooks that run Worker code when the container changes state: +The [`Container` class](/containers/api/container-class/) adds hooks that run Worker code when the container changes state: -- [`onStart()`](/containers/reference/container-class/#onstart) — Runs after the container has started. -- [`onStop()`](/containers/reference/container-class/#onstop) — Runs after the container process exits. Receives the exit code and reason for the stop. -- [`onActivityExpired()`](/containers/reference/container-class/#onactivityexpired) — Runs when the [`sleepAfter`](/containers/reference/container-class/#sleepafter) timer expires with no incoming requests. The default implementation calls `stop()` to shut down the container. You can use this to only stop the container on certain conditions. -- [`onError()`](/containers/reference/container-class/#onerror) — Runs when the container exits with an error. +- [`onStart()`](/containers/api/container-class/#onstart) — Runs after the container has started. +- [`onStop()`](/containers/api/container-class/#onstop) — Runs after the container process exits. Receives the exit code and reason for the stop. +- [`onActivityExpired()`](/containers/api/container-class/#onactivityexpired) — Runs when the [`sleepAfter`](/containers/api/container-class/#sleepafter) timer expires with no incoming requests. The default implementation calls `stop()` to shut down the container. You can use this to only stop the container on certain conditions. +- [`onError()`](/containers/api/container-class/#onerror) — Runs when container startup or port checking fails. Refer to the [status hooks example](/containers/examples/status-hooks/) for a full implementation. diff --git a/src/content/docs/containers/configuration/environment-variables.mdx b/src/content/docs/containers/configuration/environment-variables.mdx index 62612167fa4..ac71f31fa1c 100644 --- a/src/content/docs/containers/configuration/environment-variables.mdx +++ b/src/content/docs/containers/configuration/environment-variables.mdx @@ -3,7 +3,7 @@ pcx_content_type: reference title: Environment Variables description: Runtime and user-defined environment variables available inside Container instances. sidebar: - order: 2 + order: 3 products: - containers --- diff --git a/src/content/docs/containers/configuration/index.mdx b/src/content/docs/containers/configuration/index.mdx index a49102d100a..787c7a1766a 100644 --- a/src/content/docs/containers/configuration/index.mdx +++ b/src/content/docs/containers/configuration/index.mdx @@ -1,7 +1,7 @@ --- pcx_content_type: navigation title: Configuration -description: Configure Containers — connect them to Workers and bindings, set environment variables, tune scaling and routing, and manage rollouts. +description: Configure Containers in Wrangler, connect them to Workers and bindings, set environment variables, tune scaling and routing, and manage rollouts. sidebar: order: 5 group: diff --git a/src/content/docs/containers/configuration/outbound-traffic.mdx b/src/content/docs/containers/configuration/outbound-traffic.mdx index fbe1ee0e430..f20ad6875bd 100644 --- a/src/content/docs/containers/configuration/outbound-traffic.mdx +++ b/src/content/docs/containers/configuration/outbound-traffic.mdx @@ -357,7 +357,7 @@ Requests are evaluated in this order: 5. Instance-level handlers set with `setOutboundHandler()` are checked before the class-level `outbound` handler. 6. If no handler matches, the request can still egress to the public internet when it matched `allowedHosts` or `enableInternet = true`. Otherwise, it is denied. -## Low-level API +## Direct API To configure outbound interception directly on `ctx.container`, use `interceptOutboundHttp` for a specific hostname glob, IP, or CIDR range, or `interceptAllOutboundHttp` for all traffic. Both accept a `WorkerEntrypoint`. @@ -414,4 +414,4 @@ The `Container` class calls these methods automatically when you use the functio - [Connect to Workers bindings](/containers/configuration/workers-connections/) — Access KV, R2, Durable Objects, and other bindings from a container - [Control outbound traffic (Sandboxes)](/sandbox/guides/outbound-traffic/) — Sandbox SDK API for outbound handlers - [Environment variables and secrets](/containers/configuration/environment-variables/) — Configure secrets and environment variables -- [Durable Object interface](/durable-objects/api/container/) — Full `ctx.container` API reference +- [Durable Object Container API](/containers/api/durable-object-container/) — Full `ctx.container` API reference diff --git a/src/content/docs/containers/configuration/rollouts.mdx b/src/content/docs/containers/configuration/rollouts.mdx index d658eb17a03..cb9b73c551c 100644 --- a/src/content/docs/containers/configuration/rollouts.mdx +++ b/src/content/docs/containers/configuration/rollouts.mdx @@ -3,7 +3,7 @@ pcx_content_type: reference title: Rollouts description: How container instances update after a deploy, including step percentages, grace periods, and rollout modes. sidebar: - order: 4 + order: 5 products: - containers --- @@ -53,7 +53,7 @@ When the rollout selects a container instance to update: 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`](/containers/reference/container-class/#onstop) hook can run in the Worker once the container process has exited. +5. **After exit.** The Container class [`onStop`](/containers/api/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](/containers/faq/#is-disk-persistent-what-happens-to-my-disk-when-my-container-sleeps) 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. @@ -160,4 +160,4 @@ Use none when the deploy should not publish a new image or start a container ins - [Deploy Containers](/containers/guides/deploy/) - [Lifecycle of a Container](/containers/concepts/architecture/) - [Image management](/containers/guides/image-management/) -- [Containers configuration](/workers/wrangler/configuration/#containers) +- [Wrangler configuration](/containers/configuration/wrangler/) diff --git a/src/content/docs/containers/configuration/scaling-and-routing.mdx b/src/content/docs/containers/configuration/scaling-and-routing.mdx index 7306d9c20c9..c5f85f46f7c 100644 --- a/src/content/docs/containers/configuration/scaling-and-routing.mdx +++ b/src/content/docs/containers/configuration/scaling-and-routing.mdx @@ -3,7 +3,7 @@ pcx_content_type: reference title: Scaling and Routing description: Scale Container instances using explicit IDs or the getRandom helper for stateless load balancing. sidebar: - order: 3 + order: 4 products: - containers --- @@ -11,7 +11,7 @@ products: ## Scale container instances with explicit IDs :::note -This section uses helpers from the [Container class](/containers/reference/container-class/). +This section uses helpers from the [Container class](/containers/api/container-class/). ::: Today, Containers are scaled manually by getting containers with a unique ID, then diff --git a/src/content/docs/containers/configuration/workers-connections.mdx b/src/content/docs/containers/configuration/workers-connections.mdx index 8cf45a36f38..1aa35122871 100644 --- a/src/content/docs/containers/configuration/workers-connections.mdx +++ b/src/content/docs/containers/configuration/workers-connections.mdx @@ -2,7 +2,7 @@ title: Connect to Workers and Bindings pcx_content_type: concept sidebar: - order: 1 + order: 2 description: Access KV, R2, Durable Objects, and other bindings from a container. products: - containers @@ -59,4 +59,4 @@ The `ctx` argument exposes `containerId`, which lets you interact with the conta - [Handle outbound traffic](/containers/configuration/outbound-traffic/) — Block, allow, and intercept all outbound HTTP from a container - [Environment variables and secrets](/containers/configuration/environment-variables/) — Configure secrets and environment variables -- [Durable Object interface](/durable-objects/api/container/) — Full `ctx.container` API reference +- [Durable Object Container API](/containers/api/durable-object-container/) — Full `ctx.container` API reference diff --git a/src/content/docs/containers/configuration/wrangler.mdx b/src/content/docs/containers/configuration/wrangler.mdx new file mode 100644 index 00000000000..06a783c35a8 --- /dev/null +++ b/src/content/docs/containers/configuration/wrangler.mdx @@ -0,0 +1,79 @@ +--- +title: Wrangler configuration +description: Configure a Container, its Durable Object binding, and its class export in Wrangler. +pcx_content_type: configuration +sidebar: + order: 0 +products: + - containers + - durable-objects +--- + +import { WranglerConfig } from "~/components"; + +Define Containers in the Wrangler configuration file for your Worker. Each Container is associated with a Durable Object class, which provides access to the Container at runtime. + +## Minimal configuration + +A new Container application requires a Container definition, a Durable Object binding, and a Durable Object class export: + + + +```jsonc +{ + "$schema": "./node_modules/wrangler/config-schema.json", + "name": "my-container-worker", + "main": "src/index.ts", + "compatibility_date": "$today", + "containers": [ + { + "class_name": "MyContainer", + "image": "./Dockerfile", + "max_instances": 10, + }, + ], + "durable_objects": { + "bindings": [ + { + "name": "MY_CONTAINER", + "class_name": "MyContainer", + }, + ], + }, + "exports": { + "MyContainer": { + "type": "durable-object", + "storage": "sqlite", + }, + }, +} +``` + + + +The configuration uses three sections: + +1. **`containers`** defines the container image and associates it with a Durable Object class through `class_name`. +2. **`durable_objects.bindings`** makes the Durable Object namespace available to Worker code. In this example, access it through `env.MY_CONTAINER`. +3. **`exports`** declares the Durable Object class and provisions it with SQLite storage. + +The `class_name` in `containers` and `durable_objects.bindings`, and the key in `exports`, must match the exported Durable Object class in your Worker. + +:::note[Existing applications] + +Existing applications that use the legacy `migrations` array can continue to use it. Do not configure `exports` and `migrations` together. To switch an existing application to `exports`, refer to [Migrate from the legacy `migrations` flow](/durable-objects/reference/durable-objects-migrations/#migrate-from-the-legacy-migrations-flow). + +::: + +## Container settings + +The `containers` entry can also configure the instance type, maximum number of running instances, image build, placement constraints, rollouts, and SSH access. + +For all available fields and values, refer to the [Containers Wrangler configuration reference](/workers/wrangler/configuration/#containers). + +## Next steps + +- [Deploy Containers](/containers/guides/deploy/) — Build the image and deploy the Worker. +- [Scaling and Routing](/containers/configuration/scaling-and-routing/) — Route requests and scale Container instances. +- [Rollouts](/containers/configuration/rollouts/) — Control how configuration changes reach running instances. +- [Image management](/containers/guides/image-management/) — Use local and remote container images. diff --git a/src/content/docs/containers/examples/env-vars-and-secrets.mdx b/src/content/docs/containers/examples/env-vars-and-secrets.mdx index 00d3117d36b..4dfa0e739bf 100644 --- a/src/content/docs/containers/examples/env-vars-and-secrets.mdx +++ b/src/content/docs/containers/examples/env-vars-and-secrets.mdx @@ -13,7 +13,7 @@ products: import { WranglerConfig, PackageManagers } from "~/components"; Environment variables can be passed into a Container using the `envVars` field -in the [`Container`](/containers/reference/container-class/) class, or by setting manually when the Container starts. +in the [`Container`](/containers/api/container-class/) class, or by setting manually when the Container starts. Secrets can be passed into a Container by using [Worker Secrets](/workers/configuration/secrets/) or the [Secret Store](/secrets-store/integrations/workers/), then passing them into the Container diff --git a/src/content/docs/containers/examples/index.mdx b/src/content/docs/containers/examples/index.mdx index 532425ee67a..337286b2dd3 100644 --- a/src/content/docs/containers/examples/index.mdx +++ b/src/content/docs/containers/examples/index.mdx @@ -3,7 +3,7 @@ pcx_content_type: navigation title: Examples description: Code examples showing how to use Containers with Workers for stateless routing, cron jobs, WebSockets, and more. sidebar: - order: 6 + order: 7 group: hideIndex: true products: diff --git a/src/content/docs/containers/examples/status-hooks.mdx b/src/content/docs/containers/examples/status-hooks.mdx index 1a0e219a1e5..3d38fcd9e2b 100644 --- a/src/content/docs/containers/examples/status-hooks.mdx +++ b/src/content/docs/containers/examples/status-hooks.mdx @@ -12,7 +12,7 @@ products: --- When a Container starts, stops, becomes idle, and errors, it can trigger code execution in a Worker -that has defined status hooks on the `Container` class. Refer to the [Container class lifecycle hooks](/containers/reference/container-class/#lifecycle-hooks) for more details. +that has defined status hooks on the `Container` class. Refer to the [Container class lifecycle hooks](/containers/api/container-class/#lifecycle-hooks) for more details. ```ts import { Container } from "@cloudflare/containers"; diff --git a/src/content/docs/containers/faq.mdx b/src/content/docs/containers/faq.mdx index 982cdc3fe55..94ddc8be3f1 100644 --- a/src/content/docs/containers/faq.mdx +++ b/src/content/docs/containers/faq.mdx @@ -123,7 +123,9 @@ Containers do not use swap memory. ## How long can instances run for? What happens when a host server is shut down? -Cloudflare does not stop a container instance after a fixed maximum runtime. The Container class sets [`sleepAfter`](/containers/reference/container-class/#sleepafter) to 10 minutes by default, and its default [`onActivityExpired()`](/containers/reference/container-class/#onactivityexpired) implementation signals the container to stop after that period without activity. You can change the duration or override the hook. Even if your hook keeps the instance running, another platform event can stop it. One of those cases is a host server restart, which happens on an irregular cadence. Cloudflare does not guarantee that any container instance will run for any set period of time. +Cloudflare does not stop a container instance after a fixed maximum runtime. With the Durable Object Container API, call [`setInactivityTimeout()`](/containers/api/durable-object-container/#setinactivitytimeout) to stop an inactive container. The `Container` class sets [`sleepAfter`](/containers/api/container-class/#sleepafter) to 10 minutes by default. Its [`onActivityExpired()`](/containers/api/container-class/#onactivityexpired) implementation signals the container to stop after that period without activity. You can change the duration or override the hook. + +Another platform event can stop an active container. For example, a host server restart happens on an irregular cadence. Cloudflare does not guarantee that any container instance will run for a set period. When the platform is about to stop a container instance (including before a host moves work off a server), it: diff --git a/src/content/docs/containers/get-started/index.mdx b/src/content/docs/containers/get-started/index.mdx index b8c6fdeeae9..1c9b1dac719 100644 --- a/src/content/docs/containers/get-started/index.mdx +++ b/src/content/docs/containers/get-started/index.mdx @@ -15,6 +15,8 @@ In this example, each container runs a small webserver written in Go. This example Worker should give you a sense for simple Container use, and provide a starting point for more complex use cases. +This guide uses the `Container` class and its built-in lifecycle helpers. You can also manage containers directly through `ctx.container`. To compare both options, refer to [Containers APIs](/containers/api/). + ## Prerequisites ### Ensure Docker is running locally @@ -72,7 +74,7 @@ Now that you've deployed your first container, let's explain what is happening i ### Configuration -Your [Wrangler configuration file](/workers/wrangler/configuration/) defines the configuration for both your Worker and your container: +Your [Wrangler configuration file](/containers/configuration/wrangler/) defines the configuration for both your Worker and your container: @@ -93,12 +95,12 @@ Your [Wrangler configuration file](/workers/wrangler/configuration/) defines the }, ], }, - "migrations": [ - { - "tag": "v1", - "new_sqlite_classes": ["MyContainer"], + "exports": { + "MyContainer": { + "type": "durable-object", + "storage": "sqlite", }, - ], + }, } ``` @@ -110,7 +112,7 @@ Important points about this config: - `class_name` must be a [Durable Object class name](/durable-objects/api/base/). - `max_instances` declares the maximum number of simultaneously running container instances that will run. -- The Durable Object must use [`new_sqlite_classes`](/durable-objects/best-practices/access-durable-objects-storage/#create-sqlite-backed-durable-object-class) not `new_classes`. +- The `exports` entry declares the Durable Object class with SQLite storage. Existing applications that use the legacy `migrations` array can continue to use it, but `exports` and `migrations` cannot be combined. ### The Container Image @@ -171,7 +173,7 @@ This defines basic configuration for the container: The `Container` class itself extends [`DurableObject`](/durable-objects/), so your subclass has access to the full Durable Object API. The Durable Object handles routing, lifecycle, and persistent state, while the container process runs your image inside a Linux VM. This means you can use [`this.ctx.storage`](/durable-objects/api/sqlite-storage-api/) to persist data that survives container restarts and resides close to the container itself. -Refer to the [Container class reference](/containers/reference/container-class/) and the [low-level Durable Object container API](/durable-objects/api/container/) for more details. +For all properties and methods, refer to the [Container class API](/containers/api/container-class/). #### Routing to Containers diff --git a/src/content/docs/containers/guides/execute-commands.mdx b/src/content/docs/containers/guides/execute-commands.mdx index c5160e3cba6..7b05288a936 100644 --- a/src/content/docs/containers/guides/execute-commands.mdx +++ b/src/content/docs/containers/guides/execute-commands.mdx @@ -11,7 +11,7 @@ reviewed: 2026-06-18 import { TypeScriptExample } from "~/components"; -Use `exec()` to start another process inside a running [Container](/containers/reference/container-class/). The examples call `this.ctx.container.exec()` inside a class extending `Container` from `@cloudflare/containers`. +Use `exec()` to start another process inside a running [Container](/containers/api/container-class/). The examples call `this.ctx.container.exec()` inside a class extending `Container` from `@cloudflare/containers`. `exec()` does not start a stopped Container. In remote procedure call (RPC) methods, check `this.ctx.container.running` and call `await this.start()` when needed. You can also use the `onStart()` hook to run any series of commands whenever the Container starts. @@ -490,4 +490,4 @@ export class MyContainer extends Container { ``` -For all fields and return types, refer to the [`exec()` API contract](/durable-objects/api/container/#exec). +For all fields and return types, refer to the [`exec()` API contract](/containers/api/durable-object-container/#exec). diff --git a/src/content/docs/containers/guides/migrate-to-durable-object-container-api.mdx b/src/content/docs/containers/guides/migrate-to-durable-object-container-api.mdx new file mode 100644 index 00000000000..ba0ae66d661 --- /dev/null +++ b/src/content/docs/containers/guides/migrate-to-durable-object-container-api.mdx @@ -0,0 +1,36 @@ +--- +title: Migrate from the Container class to the Durable Object Container API +description: Replace Container class lifecycle and routing helpers with direct container control inside a Durable Object. +pcx_content_type: how-to +sidebar: + order: 7 +products: + - containers + - durable-objects +--- + +import { Steps } from "~/components"; + +The Durable Object Container API lets your Durable Object coordinate container compute with persistent storage, alarms, and request handling. Access it as `this.ctx.container` inside a Durable Object with a container binding. When migrating from the `Container` class, replace its helpers with application code where needed. + +Before changing code, identify which helpers your application uses. Some helpers require application code to preserve their existing behavior. For an API comparison, refer to [Choose an API](/containers/api/#choose-an-api). + +You can migrate the implementation without replacing the Durable Object. Keep the Worker name, exported class name, binding, container image, and existing migration tags unchanged. Changing the TypeScript base class does not require a new Durable Object migration. + +## Replace Container class helpers + +The `Container` class extends `DurableObject`. Replace its inherited lifecycle and routing helpers with application code that uses `ctx.container`. + + + +1. In your Worker, change the class to extend `DurableObject` from `cloudflare:workers`. Keep the exported class name to retain its existing container definition and Durable Object binding. Do not add a new Durable Object migration solely because you changed the base class. Refer to [Wrangler configuration](/containers/configuration/wrangler/). +2. Replace `start()` calls with [`ctx.container.start()`](/containers/api/durable-object-container/#start). Replace `stop()` calls with [`signal()`](/containers/api/durable-object-container/#signal) or [`destroy()`](/containers/api/durable-object-container/#destroy), as appropriate. Do not assume `start()` waits for a port to become ready. +3. Replace `defaultPort`, `containerFetch()`, and automatic `fetch()` routing with [`getTcpPort(port).fetch()`](/containers/api/durable-object-container/#gettcpport) and your own request routing. Check port readiness before forwarding requests. +4. Replace `sleepAfter` with [`setInactivityTimeout()`](/containers/api/durable-object-container/#setinactivitytimeout). Replace lifecycle hooks and `schedule()` with application code, [`monitor()`](/containers/api/durable-object-container/#monitor), and [Durable Object alarms](/durable-objects/api/alarms/) where appropriate. +5. Test startup, concurrent requests, readiness, idle shutdown, alarm delivery, storage continuity, and recovery after a container restart. A container can be temporarily unavailable after `stop()` or `destroy()`. Retry allocation before checking port readiness. Then remove `@cloudflare/containers` only if no other code imports it. + + + +Keep the same image in the `containers` section of your Wrangler configuration unless you intend to change the container application itself. The direct API still runs the image associated with its Durable Object class. + +For process handling and output, refer to [Execute commands](/containers/guides/execute-commands/) and the [`exec()` reference](/containers/api/durable-object-container/#exec). diff --git a/src/content/docs/containers/index.mdx b/src/content/docs/containers/index.mdx index a2cf34aff99..88f9cf20278 100644 --- a/src/content/docs/containers/index.mdx +++ b/src/content/docs/containers/index.mdx @@ -170,11 +170,7 @@ Ship from your machine or Workers Builds, and confirm the deploy. How a container is scheduled, started, routed, and shut down. - + Instance counts, image size, and other platform limits. @@ -186,12 +182,8 @@ Ship from your machine or Workers Builds, and confirm the deploy. CLI commands for images and containers. - - Start, stop, and talk to the container process from a Durable Object. + + Use the Durable Object Container API or reference the Container class. @@ -203,7 +195,8 @@ Ship from your machine or Workers Builds, and confirm the deploy. href="https://discord.cloudflare.com" icon="discord" > - Ask questions, show what you are building, and talk with other Containers developers. + Ask questions, show what you are building, and talk with other Containers + developers. diff --git a/src/content/docs/containers/platform/index.mdx b/src/content/docs/containers/platform/index.mdx index 3a596df5460..581b8f1d3c1 100644 --- a/src/content/docs/containers/platform/index.mdx +++ b/src/content/docs/containers/platform/index.mdx @@ -3,7 +3,7 @@ pcx_content_type: navigation title: Platform description: Product-wide information for Containers, including pricing and limits. sidebar: - order: 8 + order: 9 group: hideIndex: true products: diff --git a/src/content/docs/containers/reference/durable-object-methods.mdx b/src/content/docs/containers/reference/durable-object-methods.mdx deleted file mode 100644 index 8889c8cc6c5..00000000000 --- a/src/content/docs/containers/reference/durable-object-methods.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -pcx_content_type: navigation -title: Durable Object Interface -description: API reference for the low-level Durable Object methods that control Container instances. -external_link: /durable-objects/api/container/ -sidebar: - order: 2 -products: - - containers - - durable-objects ---- diff --git a/src/content/docs/containers/reference/index.mdx b/src/content/docs/containers/reference/index.mdx index 866ffe34560..8df5a63ad4a 100644 --- a/src/content/docs/containers/reference/index.mdx +++ b/src/content/docs/containers/reference/index.mdx @@ -1,9 +1,9 @@ --- pcx_content_type: navigation title: Reference -description: Lookup details for the Containers platform, including the Container class, the Durable Object interface, and Wrangler configuration and commands. +description: Lookup Wrangler configuration and commands for Containers. sidebar: - order: 7 + order: 8 group: hideIndex: true products: diff --git a/src/content/docs/durable-objects/api/container.mdx b/src/content/docs/durable-objects/api/container.mdx index e335a576411..cfc46405ca5 100644 --- a/src/content/docs/durable-objects/api/container.mdx +++ b/src/content/docs/durable-objects/api/container.mdx @@ -1,345 +1,11 @@ --- -title: Durable Object Container -description: Access and manage containers associated with a Durable Object, including start, stop, and interaction methods. -pcx_content_type: concept +pcx_content_type: navigation +title: Durable Object Container API +description: Manage a container directly through its Durable Object. +external_link: /containers/api/durable-object-container/ sidebar: - order: 1 + order: 7.5 products: + - containers - durable-objects --- - -import { - Render, - Tabs, - TabItem, - GlossaryTooltip, - Type, - MetaInfo, - TypeScriptExample, -} from "~/components"; - -## Description - -Each [container](/containers/) is managed by a Durable Object. The [`Container` class](/containers/reference/container-class/) from `@cloudflare/containers` extends `DurableObject` and handles lifecycle management, port readiness, and sleep timeouts for you. The Durable Object manages routing, persistent state, and lifecycle hooks, while the container process runs your image inside a Linux VM. - -The low-level API documented on this page is available on `this.ctx.container` inside any Durable Object class that has a container binding. Use it when you need direct control over the container process or cannot use the `Container` class. - -Because the `Container` class extends `DurableObject`, you also have access to [SQLite storage](/durable-objects/api/sqlite-storage-api/) via `this.ctx.storage`, [alarms](/durable-objects/api/alarms/), and all other Durable Object APIs. - - -```ts -export class MyDurableObject extends DurableObject { - constructor(ctx: DurableObjectState, env: Env) { - super(ctx, env); - - // boot the container when starting the DO - this.ctx.blockConcurrencyWhile(async () => { - this.ctx.container.start(); - }); - } - -} - -```` - - - -## Attributes - -### `running` - -`running` returns `true` if the container is currently running. It does not ensure that the container has fully started and ready to accept requests. - -```js - this.ctx.container.running; -```` - -## Methods - -### `start` - -`start` boots a container. This method does not block until the container is fully started. -You may want to confirm the container is ready to accept requests before using it. - -```js -this.ctx.container.start({ - env: { - FOO: "bar", - }, - enableInternet: false, - entrypoint: ["node", "server.js"], -}); -``` - -#### Parameters - -- `options` (optional): An object with the following properties: - - `env`: An object containing environment variables to pass to the container. This is useful for passing configuration values or secrets to the container. - - `entrypoint`: An array of strings representing the command to run in the container. - - `enableInternet`: A boolean indicating whether to enable internet access for the container. - -#### Return values - -- None. - -### `exec` - -`exec` starts another process inside an already-running Container. It does not start a stopped Container. - -The following example calls `this.ctx.container.exec()` inside a class extending `Container` from `@cloudflare/containers`. In RPC methods, check `this.ctx.container.running` and call `await this.start()` when needed. You can also use the `onStart()` hook to run any series of commands whenever the Container starts. - -```ts -exec( - cmd: string[], - options?: ContainerExecOptions, -): Promise -``` - -The `exec` operation starts the executable directly with the provided arguments. It does not start a shell or interpret pipes, redirects, expansion, or other shell syntax. Invoke Bash explicitly with `["bash", "-lc", ""]` when Bash exists in the image. Use `["sh", "-c", ""]` for images with only a Portable Operating System Interface (POSIX) shell. - -The following RPC method starts the Container before executing a command: - - -```ts -import { Container } from "@cloudflare/containers"; - -export class MyContainer extends Container { - async runCommand() { - if (!this.ctx.container.running) { - await this.start(); - } - - const process = await this.ctx.container.exec(["node", "--version"]); - const output = await process.output(); - - return { - pid: process.pid, - exitCode: output.exitCode, - stdout: new TextDecoder().decode(output.stdout), - }; - } -} -``` - - -#### Parameters - -- `cmd` (`string[]`) — executable followed by its arguments. -- `options` (`ContainerExecOptions`, optional) — process configuration: - - `stdin` (`ReadableStream | "pipe"`) — source for standard input. Use `"pipe"` to write through the returned `stdin` stream. When omitted, standard input closes and sends end-of-file (EOF). - - `stdout` (`"pipe" | "ignore"`, default `"pipe"`) — captures or discards standard output. - - `stderr` (`"pipe" | "ignore" | "combined"`, default `"pipe"`) — captures, discards, or merges standard error into standard output. The `"combined"` value requires `stdout: "pipe"`. Combined output does not guarantee ordering between its source streams. - - `cwd` (`string`) — working directory for the process. - - `env` (`Record`) — environment additions and overrides. The process inherits existing Container variables. Matching keys use the per-execution value. - - `user` (`string`) — image user for the process. - -#### Return values - -Returns `Promise`. - -An `ExecProcess` has these fields and methods: - -- `stdin` (`WritableStream | null`) — writable standard input when `stdin` is `"pipe"`. -- `stdout` (`ReadableStream | null`) — readable standard output when piped. -- `stderr` (`ReadableStream | null`) — readable standard error when piped separately. -- `pid` (`number`) — process identifier. -- `exitCode` (`Promise`) — resolves when the process exits. Nonzero codes resolve normally instead of rejecting. -- `output()` (`Promise`) — reads buffered output once. `ExecOutput` contains `stdout` (`ArrayBuffer`), `stderr` (`ArrayBuffer`), and `exitCode` (`number`). Ignored streams produce empty buffers. Use `TextDecoder` to decode text. -- `kill(signal?: number)` (`void`) — queues a signal for the process. The default is `SIGTERM`, signal `15`. The signal must be from `1` through `64`. - -With `stderr: "combined"`, `stderr` is `null` on `ExecProcess` and an empty `ArrayBuffer` on `ExecOutput`. Read both output channels from `stdout`. - -`output()` throws a `TypeError` when called more than once or after either readable stream starts being consumed. For large output, consume both readable streams concurrently instead of buffering them with `output()`. - -`exec` has no built-in timeout. Use `kill()` to request termination, then observe completion through `exitCode`. A process can handle or ignore a signal, so this does not enforce a hard deadline. Do not infer a specific exit code from the signal. - -#### Exceptions - -- `exec()` throws when the Container is not running. -- `exec()` throws a `TypeError` when `cmd` is empty, an option mode is invalid, or `stderr: "combined"` is used with `stdout: "ignore"`. -- `exec()` rejects if the runtime cannot create or start the process. -- Environment variable names cannot contain `=` or null characters. Environment values, `cwd`, and `user` cannot contain null characters. -- `kill()` throws a `RangeError` when the signal is outside the supported range. - -For task-oriented examples, refer to [Execute commands](/containers/guides/execute-commands/). - -### `destroy` - -`destroy` stops the container and optionally returns a custom error message to the `monitor()` error callback. - -```js -this.ctx.container.destroy("Manually Destroyed"); -``` - -#### Parameters - -- `error` (optional): A string that will be sent to the error handler of the `monitor` method. This is useful for logging or debugging purposes. - -#### Return values - -- A promise that returns once the container is destroyed. - -### `signal` - -`signal` sends an IPC signal to the container, such as SIGKILL or SIGTERM. This is useful for stopping the container gracefully or forcefully. - -```js -const SIGTERM = 15; -this.ctx.container.signal(SIGTERM); -``` - -#### Parameters - -- `signal`: a number representing the signal to send to the container. This is typically a POSIX signal number, such as SIGTERM (15) or SIGKILL (9). - -#### Return values - -- None. - -### `getTcpPort` - -`getTcpPort` returns a TCP port from the container. This can be used to communicate with the container over TCP and HTTP. - -```js -const port = this.ctx.container.getTcpPort(8080); -const res = await port.fetch("http://container/set-state", { - body: initialState, - method: "POST", -}); -``` - -```js -const conn = this.ctx.container.getTcpPort(8080).connect("10.0.0.1:8080"); -await conn.opened; - -try { - if (request.body) { - await request.body.pipeTo(conn.writable); - } - return new Response(conn.readable); -} catch (err) { - console.error("Request body piping failed:", err); - return new Response("Failed to proxy request body", { status: 502 }); -} -``` - -#### Parameters - -- `port` (number): a TCP port number to use for communication with the container. - -#### Return values - -- `TcpPort`: a `TcpPort` object representing the TCP port. This object can be used to send requests to the container over TCP and HTTP. - -### `monitor` - -`monitor` returns a promise that resolves when a container exits and errors if a container errors. This is useful for setting up -callbacks to handle container status changes in your Workers code. - -```js -class MyContainer extends DurableObject { - constructor(ctx, env) { - super(ctx, env); - function onContainerExit() { - console.log("Container exited"); - } - - // the "err" value can be customized by the destroy() method - async function onContainerError(err) { - console.log("Container errored", err); - } - - this.ctx.container.start(); - this.ctx.container.monitor().then(onContainerExit).catch(onContainerError); - } -} -``` - -#### Parameters - -- None - -#### Return values - -- A promise that resolves when the container exits. - -### `interceptOutboundHttp` - -`interceptOutboundHttp` routes outbound HTTP requests matching a hostname, hostname glob, IP address, IP:port, or CIDR range through a `WorkerEntrypoint`. Can be called before or after starting the container. Open connections pick up the new handler without being dropped. - -```js -const worker = this.ctx.exports.MyWorker({ props: { message: "hello" } }); - -// Match a specific hostname -this.ctx.container.interceptOutboundHttp("api.example.com", worker); - -// Match a hostname glob pattern -this.ctx.container.interceptOutboundHttp("*.example.com", worker); - -// Match an IP:port -await this.ctx.container.interceptOutboundHttp("15.0.0.1:80", worker); - -// Match a CIDR range (IPv4 and IPv6) -await this.ctx.container.interceptOutboundHttp("123.123.123.123/23", worker); -``` - -#### Parameters - -- `target` (string): A hostname, hostname glob (for example, `*.example.com`), IP address, IP:port, or CIDR range to match. -- `worker` (WorkerEntrypoint): A `WorkerEntrypoint` instance to handle matching requests. - -#### Return values - -- None. - -### `interceptAllOutboundHttp` - -`interceptAllOutboundHttp` routes all outbound HTTP requests from the container through a `WorkerEntrypoint`, regardless of destination. - -```js -await this.ctx.container.interceptAllOutboundHttp(worker); -``` - -#### Parameters - -- `worker` (WorkerEntrypoint): A `WorkerEntrypoint` instance to handle all outbound HTTP requests. - -#### Return values - -- A promise that resolves once the intercept rule is installed. - -### `interceptOutboundHttps` - -`interceptOutboundHttps` routes outbound HTTPS requests matching a hostname or hostname glob through a `WorkerEntrypoint`. Works the same way as `interceptOutboundHttp` but for HTTPS traffic. The container must trust the CA certificate at `/etc/cloudflare/certs/cloudflare-containers-ca.crt` for HTTPS interception to work. - -Supports glob patterns where `*` matches any sequence of characters. - -```js -const worker = this.ctx.exports.MyWorker({ props: {} }); - -// Match a specific hostname -this.ctx.container.interceptOutboundHttps("api.example.com", worker); - -// Match a hostname glob pattern -this.ctx.container.interceptOutboundHttps("*.example.com", worker); - -// Intercept all HTTPS traffic -this.ctx.container.interceptOutboundHttps("*", worker); -``` - -#### Parameters - -- `target` (string): A hostname or hostname glob pattern to match. Use `*` to intercept all HTTPS traffic. -- `worker` (WorkerEntrypoint): A `WorkerEntrypoint` instance to handle matching requests. - -#### Return values - -- None. - -## Related resources - -- [Container class reference](/containers/reference/container-class/) — the recommended high-level API built on top of this interface -- [Containers overview](/containers/) -- [Get started with Containers](/containers/get-started/) -- [SQLite storage API](/durable-objects/api/sqlite-storage-api/) — persist state across container restarts -- [Durable Objects](/durable-objects/) — the underlying platform that powers Containers diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index 6a444a83343..0a6f3b8b38a 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -1321,7 +1321,7 @@ The following options are available: build and push the image, or it can be an image reference. Supported registries are the Cloudflare Registry, Docker Hub, Amazon ECR, and Google Artifact Registry. For more information, refer to [Image Management](/containers/guides/image-management/). - `class_name` - The corresponding Durable Object class name. This will make this Durable Object a container-enabled Durable Object - and allow each instance to control a container. See [Durable Object Container Methods](/durable-objects/api/container/) for details. + and allow each instance to control a container. Refer to the [Durable Object Container API](/containers/api/durable-object-container/) for details. - `instance_type` - The instance type of the container. This determines the amount of memory, CPU, and disk given to the container instance. The current options are `"lite"`, `"basic"`, `"standard-1"`, `"standard-2"`, `"standard-3"`, and `"standard-4"`. The default is `"lite"`. For more information,