skip to content

In Cloudflare Containers, how do instance_type and max_instances size a service, and what happens when a start would exceed max_instances?

level: middleimportance: should knowfreq 25%

answer

  1. fixed slices, not autoscaling
  2. lite is the default
  3. only running instances count
  4. 20 unless you say otherwise
  5. provisioned memory is billed

basics

~10 s

instance_type fixes each instance's vCPU, memory and disk, from lite (the default) up to standard-4 or a custom type. max_instances, default 20, caps concurrently running instances; a start beyond it errors instead of queueing.

solid answer

~50 s

Under the default scheduling policy, `instance_type` gives every instance the same slice: `lite` (1/16 vCPU, 256 MiB, 2 GB, the default), `basic`, `standard-1` (1/2 vCPU, 4 GiB) through `standard-4` (4 vCPU, 12 GiB, 20 GB), or a custom `vcpu`/`memory_mib`/`disk_mb` with at least 1 vCPU and 3 GiB per vCPU. Containers have no swap, so a process past its memory is killed and the instance restarts. `max_instances`, default 20, counts only running instances; a start that would exceed it errors, and the cap is not enforced in `wrangler dev`. There is no built-in autoscaling: instances exist because code started a name, or `getRandom()` spread requests over a fixed pool. Billing is per 10 ms, on provisioned memory and disk and on active CPU. Under the `durable_object` policy, sizing moves to `start({ instance })` and `max_instances` is not supported.

code

json · 10 lines
json
{
  "containers": [
    {
      "class_name": "Converter",
      "image": "./container/Dockerfile",
      "instance_type": "standard-1",
      "max_instances": 10
    }
  ]
}

go deeper

for a junior

Recall the instance types from lite to standard-4, that lite is the default, and that max_instances defaults to 20.

for a middle

Explain how memory, disk and image size drive the instance type, why there is no swap, and how max_instances counts and rejects starts.

for a senior

Diagnose out-of-memory restarts and start failures at the cap, and design the Worker's response and naming scheme around no built-in autoscaling.

for a principal

Size for cost: provisioned memory and disk are billed while instances run, so choose types, caps and idle timeouts from measured peaks, not guesses.

## Instance types Every container instance gets a fixed slice of vCPU, memory and disk, chosen by its instance type: | `instance_type` | vCPU | Memory | Disk | | --- | --- | --- | --- | | `lite` (default) | 1/16 | 256 MiB | 2 GB | | `basic` | 1/4 | 1 GiB | 4 GB | | `standard-1` | 1/2 | 4 GiB | 8 GB | | `standard-2` | 1 | 6 GiB | 12 GB | | `standard-3` | 2 | 8 GiB | 16 GB | | `standard-4` | 4 | 12 GiB | 20 GB | The older names `dev` and `standard` still work as aliases for `lite` and `standard-1`. A **custom instance type** sets `vcpu`, `memory_mib` and `disk_mb` within these bounds: - at least 1 vCPU and at most 4; - at most 12 GiB of memory and 20 GB of disk; - at least 3 GiB of memory per vCPU. Two consequences matter for sizing. The image may be no larger than the instance's disk, so a large image forces a larger type. And containers do not use swap: a process that runs out of memory is killed with an out-of-memory error and the instance restarts. A document converter that peaks near 3 GiB fits `standard-1`; on `basic` it would be killed on the first large file. ## `max_instances` `max_instances` caps how many instances of the application run at once: - it defaults to 20 when omitted; - only running instances count, so the application can have many more named instances overall; - a request that would start an instance beyond the cap errors; it does not wait in a queue; - the cap is enforced only on Cloudflare's network, and `wrangler dev` ignores it. Treat it as a ceiling on cost and blast radius, not as a capacity plan. Containers have **no built-in autoscaling** today: an instance exists because code addressed a name and started it. For a pool of interchangeable instances, `getRandom(env.BACKEND, 3)` from `@cloudflare/containers` picks one of a fixed number of instance names at random for each request, regardless of location; for per-document or per-tenant work, use one name per entity. When a start fails at the cap, return a clear retryable response from the Worker instead of a bare 500. ## Sizing under the `durable_object` scheduling policy The table and the cap above belong to the `default` scheduling policy, where sizing lives in the Wrangler file and applies to every instance. Under `scheduling_policy: "durable_object"`, in public beta, sizing moves into code: ```js this.ctx.container.start({ image: this.ctx.container.images.base, instance: "standard-2", enableInternet: false, }); ``` `instance` accepts `lite` and `standard-1` through `standard-4`, or a custom object in camel case (`vcpu`, `memoryMib`, `diskMb`). It defaults to `lite` and rejects `basic`, `dev` and `standard`. This policy has no `max_instances`: running instances count only toward the account limits of 6 TiB of memory, 1,500 vCPU and 30 TB of disk at once, so any per-tenant cap has to be enforced in your own code. The policy is fixed when the application is created. ## How sizing becomes a bill Containers need the Workers Paid plan, and an instance is billed for every 10 ms it runs: | Resource | Billed on | Included each month | | --- | --- | --- | | Memory | The instance type's provisioned size | 25 GiB-hours | | CPU | Active usage only | 375 vCPU-minutes | | Disk | The instance type's provisioned size | 200 GB-hours | The Worker and the Durable Object in front of each container are billed as usual, and egress is priced per GB by region. Because memory and disk are charged on what the type provisions, an idle `standard-4` costs far more per hour than an idle `lite`: oversizing "to be safe" is a direct, continuous cost while instances run. Charges stop when an instance goes to sleep. ## Sizing a conversion service in practice 1. Measure the converter's peak memory and scratch disk on the largest realistic input, and pick the smallest type with headroom. 2. Set `max_instances` to the peak concurrency you are willing to pay for, and decide what the Worker returns when a start fails at the cap. 3. Keep idle timeouts short enough that the provisioned size is not billed for hours of silence. 4. Re-measure after converter upgrades, since a new native library can change the memory profile.

  • Your converter is killed on large files and the instance restarts. What do you check first?
    Memory: containers have no swap, so a process that exceeds its instance type's memory is killed out of memory and restarted. Measure peak usage on the failing input and move to a larger type, such as `standard-1` (4 GiB) or `standard-2` (6 GiB), or reduce the converter's working set.
  • How do you spread stateless requests over several instances without autoscaling?
    Use `getRandom(env.BACKEND, n)` from `@cloudflare/containers`, which picks one of n fixed instance names at random per request, or build names yourself, such as `pool-${i}`. Either way n is fixed in code and selection ignores location, so size n and `max_instances` together.

  • Expects Cloudflare to autoscale container instances with load.
  • Thinks max_instances counts stopped instances too.
  • Believes requests over max_instances queue until an instance frees up.
  • Assumes memory is billed only on what the process actually uses.
  • Relies on swap to absorb a memory spike in a container.

Assumes Cloudflare's platform as of 2026-10-10: instance types lite to standard-4 (dev and standard are aliases), max_instances default 20, and the durable_object policy in public beta without max_instances.