feat(containers): add support for handling images that link to the CF registry (#9596)

CarmenPopoviciu · emily-shen · web-flow · commit 5162c5194604 · 2025-06-20T18:37:45.000+02:00
* add pull

* update fixture for easier manual testing

* changeset

* pr feedback

---------

Co-authored-by: emily-shen &lt;69125074+emily-shen@users.noreply.github.com&gt;
diff --git a/.changeset/thick-icons-visit.md b/.changeset/thick-icons-visit.md
@@ -0,0 +1,7 @@
+---
+"@cloudflare/containers-shared": patch
+"miniflare": patch
+"wrangler": patch
+---
+
+add ability to pull images for containers local dev
diff --git a/fixtures/container-app/src/index.ts b/fixtures/container-app/src/index.ts
@@ -7,33 +7,64 @@ export class Container extends DurableObject<Env> {
 	constructor(ctx: DurableObjectState, env: Env) {
 		super(ctx, env);
 		this.container = ctx.container!;
-		void this.ctx.blockConcurrencyWhile(async () => {
-			if (!this.container.running) this.container.start();
-		});
 	}
 
 	async fetch(req: Request) {
-		try {
-			return await this.container
-				.getTcpPort(8080)
-				.fetch(req.url.replace("https:", "http:"), req);
-		} catch (err) {
-			return new Response(`${this.ctx.id.toString()}: ${err.message}`, {
-				status: 500,
-			});
+		const path = new URL(req.url).pathname;
+		switch (path) {
+			case "/status":
+				return new Response(JSON.stringify(this.container.running));
+
+			case "/destroy":
+				if (!this.container.running) {
+					throw new Error("Container is not running.");
+				}
+				await this.container.destroy();
+				return new Response(JSON.stringify(this.container.running));
+
+			case "/start":
+				this.container.start({
+					entrypoint: ["node", "app.js"],
+					env: { A: "B", C: "D", L: "F" },
+					enableInternet: false,
+				});
+				// this doesn't instantly start, so we will need to poll /fetch
+				return new Response("Container create request sent...");
+
+			case "/fetch":
+				const res = await this.container
+					.getTcpPort(8080)
+					// actual request doesn't matter
+					.fetch("http://foo/bar/baz", { method: "POST", body: "hello" });
+				return new Response(await res.text());
+
+			case "/destroy-with-monitor":
+				// if (!this.container.running) {
+				// 	throw new Error("Container is not running.");
+				// }
+				const monitor = this.container.monitor();
+				await this.container.destroy();
+				await monitor;
+				return new Response("Container destroyed with monitor.");
+
+			default:
+				return new Response("Hi from Container DO");
 		}
 	}
 }
 
 export default {
 	async fetch(request, env): Promise<Response> {
-		try {
-			return await env.CONTAINER.get(env.CONTAINER.idFromName("fetcher")).fetch(
-				request
-			);
-		} catch (err) {
-			console.error("Error fetch:", err.message);
-			return new Response(err.message, { status: 500 });
+		const url = new URL(request.url);
+		if (url.pathname === "/second") {
+			// This is a second Durable Object that can be used to test multiple DOs
+			const id = env.CONTAINER.idFromName("second-container");
+			const stub = env.CONTAINER.get(id);
+			const query = url.searchParams.get("req");
+			return stub.fetch("http://example.com/" + query);
 		}
+		const id = env.CONTAINER.idFromName("container");
+		const stub = env.CONTAINER.get(id);
+		return stub.fetch(request);
 	},
 } satisfies ExportedHandler<Env>;
diff --git a/fixtures/container-app/wrangler.jsonc b/fixtures/container-app/wrangler.jsonc
@@ -23,7 +23,7 @@
 	"migrations": [
 		{
 			"tag": "v1",
-			"new_classes": ["Container"],
+			"new_sqlite_classes": ["Container"],
 		},
 	],
 }
diff --git a/fixtures/container-app/wrangler.registry.jsonc b/fixtures/container-app/wrangler.registry.jsonc
@@ -0,0 +1,29 @@
+{
+	"name": "container-app-from-registry",
+	"main": "src/index.ts",
+	"compatibility_date": "2025-04-03",
+	"containers": [
+		{
+			"configuration": {
+				"image": "registry.cloudflare.com/8d783f274e1f82dc46744c297b015a2f/ci-container-dont-delete:latest",
+			},
+			"class_name": "Container",
+			"name": "http2",
+			"max_instances": 2,
+		},
+	],
+	"durable_objects": {
+		"bindings": [
+			{
+				"class_name": "Container",
+				"name": "CONTAINER",
+			},
+		],
+	},
+	"migrations": [
+		{
+			"tag": "v1",
+			"new_sqlite_classes": ["Container"],
+		},
+	],
+}
diff --git a/packages/containers-shared/src/build.ts b/packages/containers-shared/src/build.ts
@@ -1,10 +1,7 @@
 import { spawn } from "child_process";
 import { readFileSync } from "fs";
 import path from "path";
-import { dockerImageInspect } from "./inspect";
-import { MF_DEV_CONTAINER_PREFIX } from "./registry";
 import { BuildArgs, ContainerDevOptions, Logger } from "./types";
-import { verifyDockerInstalled } from "./utils";
 
 export async function constructBuildCommand(
 	options: BuildArgs,
@@ -70,33 +67,7 @@ export function dockerBuild(
 	});
 }
 
-/**
- *
- * Builds (or pulls - TODO) the container images for local development. This
- * will be called before starting the local development server, and by a rebuild
- * hotkey during development.
- *
- * Because this runs when local dev starts, we also do some validation here,
- * such as checking if the Docker CLI is installed, and if the container images
- * expose any ports.
- */
-export async function prepareContainerImagesForDev(
-	dockerPath: string,
-	containerOptions: ContainerDevOptions[]
-) {
-	if (process.platform === "win32") {
-		throw new Error(
-			"Local development with containers is currently not supported on Windows. You should use WSL instead. You can also set `enable_containers` to false if you do not need to develop the container as part of your application."
-		);
-	}
-	await verifyDockerInstalled(dockerPath);
-	for (const options of containerOptions) {
-		await buildContainer(dockerPath, options);
-		await checkExposedPorts(dockerPath, options.imageTag);
-	}
-}
-
-async function buildContainer(
+export async function buildImage(
 	dockerPath: string,
 	options: ContainerDevOptions
 ) {
@@ -111,16 +82,3 @@ async function buildContainer(
 
 	await dockerBuild(dockerPath, { buildCmd, dockerfile });
 }
-
-async function checkExposedPorts(dockerPath: string, imageTag: string) {
-	const output = await dockerImageInspect(dockerPath, {
-		imageTag,
-		formatString: "{{ len .Config.ExposedPorts }}",
-	});
-	if (output === "0" && process.platform !== "linux") {
-		throw new Error(
-			`The container "${imageTag.replace(MF_DEV_CONTAINER_PREFIX + "/", "")}" does not expose any ports.\n` +
-				"To develop containers locally on non-Linux platforms, you must expose any ports that you call with `getTCPPort()` in your Dockerfile."
-		);
-	}
-}
diff --git a/packages/containers-shared/src/images.ts b/packages/containers-shared/src/images.ts
@@ -1,4 +1,14 @@
 import { execFile } from "child_process";
+import { buildImage } from "./build";
+import { isCloudflareRegistryLink } from "./knobs";
+import { dockerLoginManagedRegistry } from "./login";
+import { ContainerDevOptions } from "./types";
+import {
+	checkExposedPorts,
+	isDockerfile,
+	runDockerCmd,
+	verifyDockerInstalled,
+} from "./utils";
 
 // Returns a list of docker image ids matching the provided repository:[tag]
 export async function getDockerImageDigest(
@@ -22,3 +32,55 @@ export async function getDockerImageDigest(
 		);
 	});
 }
+
+export async function pullImage(
+	dockerPath: string,
+	options: ContainerDevOptions
+) {
+	await dockerLoginManagedRegistry(dockerPath);
+	await runDockerCmd(dockerPath, [
+		"pull",
+		options.image,
+		// All containers running on our platform need to be built for amd64 architecture, but by default docker pull seems to look for an image matching the host system, so we need to specify this here
+		"--platform",
+		"linux/amd64",
+	]);
+	// re-tag image with the expected dev-formatted image tag for consistency
+	await runDockerCmd(dockerPath, ["tag", options.image, options.imageTag]);
+}
+
+/**
+ *
+ * Builds or pulls the container images for local development. This
+ * will be called before starting the local development server, and by a rebuild
+ * hotkey during development.
+ *
+ * Because this runs when local dev starts, we also do some validation here,
+ * such as checking if the Docker CLI is installed, and if the container images
+ * expose any ports.
+ */
+export async function prepareContainerImagesForDev(
+	dockerPath: string,
+	containerOptions: ContainerDevOptions[]
+) {
+	if (process.platform === "win32") {
+		throw new Error(
+			"Local development with containers is currently not supported on Windows. You should use WSL instead. You can also set `enable_containers` to false if you do not need to develop the container part of your application."
+		);
+	}
+	await verifyDockerInstalled(dockerPath);
+	for (const options of containerOptions) {
+		if (isDockerfile(options.image)) {
+			await buildImage(dockerPath, options);
+		} else {
+			if (!isCloudflareRegistryLink(options.image)) {
+				throw new Error(
+					`Image "${options.image}" is a registry link but does not point to the Cloudflare container registry.\n` +
+						`To use an existing image from another repository, see https://developers.cloudflare.com/containers/image-management/#using-existing-images`
+				);
+			}
+			await pullImage(dockerPath, options);
+		}
+		await checkExposedPorts(dockerPath, options);
+	}
+}
diff --git a/packages/containers-shared/src/knobs.ts b/packages/containers-shared/src/knobs.ts
@@ -2,9 +2,20 @@ import { MF_DEV_CONTAINER_PREFIX } from "./registry";
 
 // default cloudflare managed registry, can be overriden with the env var - CLOUDFLARE_CONTAINER_REGISTRY
 export const getCloudflareContainerRegistry = () => {
+	// previously defaulted to registry.cloudchamber.cfdata.org
 	return process.env.CLOUDFLARE_CONTAINER_REGISTRY ?? "registry.cloudflare.com";
 };
 
+/**
+ * Given a container image that is a registry link, this function
+ * returns true if the link points the Cloudflare container registry
+ * (defined as per `getCloudflareContainerRegistry` above)
+ */
+export function isCloudflareRegistryLink(image: string) {
+	const cfRegistry = getCloudflareContainerRegistry();
+	return image.includes(cfRegistry);
+}
+
 /** Prefixes with the cloudflare-dev namespace. The name should be the container's DO classname, and the tag a build uuid. */
 export const getDevContainerImageName = (name: string, tag: string) => {
 	return `${MF_DEV_CONTAINER_PREFIX}/${name.toLowerCase()}:${tag}`;
diff --git a/packages/containers-shared/src/login.ts b/packages/containers-shared/src/login.ts
@@ -3,8 +3,9 @@ import { ImageRegistriesService, ImageRegistryPermissions } from "./client";
 import { getCloudflareContainerRegistry } from "./knobs";
 
 /**
- * Gets push credentials for cloudflare's managed image registry
- * and runs `docker login`, so subsequent image pushes are authenticated
+ * Gets push and pull credentials for Cloudflare's managed image registry
+ * and runs `docker login`, so subsequent image pushes or pulls are
+ * authenticated
  */
 export async function dockerLoginManagedRegistry(pathToDocker: string) {
 	// how long the credentials should be valid for
@@ -15,7 +16,10 @@ export async function dockerLoginManagedRegistry(pathToDocker: string) {
 			getCloudflareContainerRegistry(),
 			{
 				expiration_minutes: expirationMinutes,
-				permissions: ["push", "pull"] as ImageRegistryPermissions[],
+				permissions: [
+					ImageRegistryPermissions.PUSH,
+					ImageRegistryPermissions.PULL,
+				],
 			}
 		);
 
diff --git a/packages/containers-shared/src/types.ts b/packages/containers-shared/src/types.ts
@@ -25,6 +25,8 @@ export type ContainerDevOptions = {
 	image: string;
 	/** formatted as cloudflare-dev/workername-DOclassname:build-id */
 	imageTag: string;
+	/** container's DO class name */
+	class_name: string;
 	imageBuildContext?: string;
 	/** build time args */
 	args?: Record<string, string>;
diff --git a/packages/containers-shared/src/utils.ts b/packages/containers-shared/src/utils.ts
@@ -1,5 +1,7 @@
 import { execFile, spawn, StdioOptions } from "child_process";
 import { existsSync, statSync } from "fs";
+import { dockerImageInspect } from "./inspect";
+import { ContainerDevOptions } from "./types";
 
 /** helper for simple docker command call that don't require any io handling */
 export const runDockerCmd = async (
@@ -153,3 +155,27 @@ const getContainerIdsFromImage = async (
 	]);
 	return output.split("\n").filter((line) => line.trim());
 };
+
+/**
+ * While all ports are exposed in prod, a limitation of local dev with docker is that
+ * non-linux users will have to manually expose ports in their Dockerfile.
+ * We want to fail early and clearly if a user tries to develop with a container
+ * that has no ports exposed and is definitely not accessible.
+ *
+ * (A user could still use `getTCPPort()` on a port that is not exposed, but we leave that error for runtime.)
+ */
+export async function checkExposedPorts(
+	dockerPath: string,
+	options: ContainerDevOptions
+) {
+	const output = await dockerImageInspect(dockerPath, {
+		imageTag: options.imageTag,
+		formatString: "{{ len .Config.ExposedPorts }}",
+	});
+	if (output === "0" && process.platform !== "linux") {
+		throw new Error(
+			`The container "${options.class_name}" does not expose any ports.\n` +
+				"To develop containers locally on non-Linux platforms, you must expose any ports that you call with `getTCPPort()` in your Dockerfile."
+		);
+	}
+}
diff --git a/packages/wrangler/src/api/startDevWorker/ConfigController.ts b/packages/wrangler/src/api/startDevWorker/ConfigController.ts
@@ -1,7 +1,9 @@
 import assert from "node:assert";
 import path from "node:path";
+import { isDockerfile } from "@cloudflare/containers-shared";
 import { watch } from "chokidar";
 import { getAssetsOptions, validateAssetsArgsAndConfig } from "../../assets";
+import { fillOpenAPIConfiguration } from "../../cloudchamber/common";
 import { readConfig } from "../../config";
 import { getEntry } from "../../deployment-bundle/entry";
 import {
@@ -18,6 +20,7 @@ import {
 } from "../../environment-variables/misc-variables";
 import { UserError } from "../../errors";
 import { getFlag } from "../../experimental-flags";
+import { isNonInteractiveOrCI } from "../../is-interactive";
 import { logger, runWithLogLevel } from "../../logger";
 import { checkTypesDiff } from "../../type-generation/helpers";
 import {
@@ -400,6 +403,16 @@ async function resolveConfig(
 		);
 	}
 
+	// for pulling containers, we need to make sure the OpenAPI config for the
+	// container API client is properly set so that we can get the correct permissions
+	// from the cloudchamber API to pull from the repository.
+	const needsPulling = resolved.containers?.some(
+		(c) => !isDockerfile(c.image ?? c.configuration.image)
+	);
+	if (needsPulling && !resolved.dev.remote) {
+		await fillOpenAPIConfiguration(config, isNonInteractiveOrCI());
+	}
+
 	// TODO(queues) support remote wrangler dev
 	const queues = extractBindingsOfType("queue", resolved.bindings);
 	if (
diff --git a/packages/wrangler/src/api/startDevWorker/LocalRuntimeController.ts b/packages/wrangler/src/api/startDevWorker/LocalRuntimeController.ts
@@ -414,6 +414,7 @@ export async function getContainerOptions(
 			),
 			args: container.image_vars,
 			imageBuildContext: container.image_build_context,
+			class_name: container.class_name,
 		});
 	}
 	return containers;

Original file line number	Diff line number	Diff line change
`@@ -23,7 +23,7 @@`
`23`	`23`	`"migrations": [`
`24`	`24`	`{`
`25`	`25`	`"tag": "v1",`
`26`		`- "new_classes": ["Container"],`
	`26`	`+ "new_sqlite_classes": ["Container"],`
`27`	`27`	`},`
`28`	`28`	`],`
`29`	`29`	`}`