Containers

Containers

Use this skill when evaluating or implementing Cloudflare Containers. Containers are an escape hatch for workloads that do not fit the Worker runtime shape.

Use Containers when

• The code requires native binaries or a runtime that cannot reasonably run in Workers.
• The workload needs a process model unavailable in Workers.
• The task is CPU/memory/runtime-shape heavy and cannot be solved by streaming, chunking, R2, Queues, or Workflows.
• You are bringing an existing service to Cloudflare while incrementally refactoring.

Prefer Workers when

• The workload is HTTP request/response logic.
• It mostly orchestrates I/O through bindings.
• It can be implemented with Web APIs and small compute slices.
• The primary need is global low-latency routing, not a persistent process.

Design pattern

Put a Worker at the edge as the public interface and use Containers only for the specialized work.

Client
  -> Worker: auth, validation, routing, rate limiting
  -> Queue/Workflow: durable background orchestration when needed
  -> Container: native/heavy execution
  -> R2/D1: results and metadata

Implementation guidance

• Make the container API narrow and explicit.
• Store inputs/outputs in R2 for large artifacts; pass keys, not blobs.
• Add idempotency keys for long-running work.
• Use Queues or Workflows for durable scheduling and retries.
• Keep authentication and tenant authorization in the Worker boundary.
• Capture logs and correlation IDs across Worker, queue/workflow, and container.

Refactor-before-container checklist

Try these first when feasible:

• Stream files instead of buffering them.
• Move large blobs to R2.
• Split jobs into queue messages or workflow steps.
• Use Workers-native libraries or Web APIs.
• Push relational work to D1/Hyperdrive.
• Use Workers AI or external APIs through AI Gateway for inference.

Anti-patterns

• Running a normal stateless API in a container only because it is familiar.
• Using containers to bypass clear Cloudflare platform mismatches without a cost/ops review.
• Keeping user authorization only inside container code while the Worker blindly proxies requests.
• Passing unbounded request bodies through the Worker and container without streaming or size checks.