Configuration (17)·续4

  • scheduling_policy string optional
  • Set to "default", or omit this field.
  • image string required
  • The image to use for the container. This can either be a local path to a Dockerfile, in which case wrangler deploy will 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.
  • class_name string conditional
  • 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. Refer to the Durable Object Container API for details.
  • Omit this field when the Container is linked by name from exports.<Class>.container.
  • name string conditional
  • The name of your container. Used as an identifier. This will default to a combination of your Worker name, the class name, and your environment.
  • Required when class_name is omitted so that exports.<Class>.container can reference the Container.
  • instance_type string | object optional
  • The instance type determines the amount of memory, CPU, and disk given to the container instance. Supported values are "lite", "basic", "standard-1", "standard-2", "standard-3", and "standard-4". The default is "lite". For more information, refer to Limits and Instance Types.
  • To specify a custom instance type, refer to Custom instance types.
  • max_instances number optional
  • The maximum number of concurrent container instances. Stopped containers do not count towards this - you may have more container instances than this number overall, but only this many actively running containers at once. If a request to start a container will exceed this limit, that request will error.
  • Defaults to 20.
  • This value is only enforced when running in production on Cloudflare's network. This limit does not apply during local development, so you may run more instances than specified.
  • image_build_context string optional
  • The build context of the application, by default it is the directory of image.
  • image_vars Record<string, string> optional
  • Build-time variables, equivalent to using --build-arg with docker build. If you want to provide environment variables to your container at runtime, you should use secret bindings or envVars on the Container class.
  • rollout_active_grace_period number optional
  • During a rollout, minimum seconds a container instance must already have been connected to its Durable Object before it may be replaced. Defaults to 0. Still applies with --containers-rollout=immediate.
  • rollout_step_percentage number | number[] optional
  • Percentage of container instances to update at each rollout step. A single number uses that step size ( 5, 10, 20, 25, 50, or 100). An array must contain ascending integer values from 10 through 100, end in 100, contain at most 10 entries, and contain no more entries than max_instances; its values are cumulative. Defaults to 100 if max_instances is omitted or less than 2; otherwise defaults to [10, 100]. Override for one deploy with --containers-rollout=immediate (single 100% step; does not override grace period).
  • observability object optional
  • Overrides the root Worker observability configuration for this Container application.
  • unsafe.configuration.experimental_flags string[] optional
  • Experimental application flags.
  • ssh object optional
  • Configuration for SSH through Wrangler. Refer to SSH.
  • wrangler_ssh object optional; deprecated, use `ssh`
  • Deprecated alias for ssh. Still supported for backward compatibility.
  • authorized_keys object[] optional
  • Public keys that should be added to the Container's authorized_keys file.
  • constraints object optional
  • Placement constraints for the container. Refer to Containers placement for details.
  • constraints.regions string[] optional
  • Limit container placement to specific geographic regions. Valid values: "ENAM", "WNAM", "EEUR", "WEUR", "APAC", "SAM", "ME", "OC", "AFR".
  • constraints.jurisdiction string optional
  • Restrict containers to compliance boundaries. Valid values: "eu", "fedramp".
  • observability object optional
  • Configures observability for this container application when deploying with wrangler deploy.
  • If omitted, Wrangler uses the top-level observability setting as a fallback for that container.
  • If set, it overrides the top-level observability setting for that container.
  • observability.enabled boolean optional
  • Shorthand for observability.logs.enabled.
  • observability.logs.enabled boolean optional
  • Whether logs for this container are persisted to Cloudflare's observability platform.
  • observability.target_instance_percentage number optional
  • Apply application-level observability changes to this percentage of running instances.
  • Must be an integer from 1 to 99.
  • Cannot be used with observability.target_instance_count.
  • Requires observability to be enabled for the container.
  • observability.target_instance_count number optional
  • Apply application-level observability changes to this many running instances.
  • Must be a positive integer.
  • Cannot be used with observability.target_instance_percentage.
  • Requires observability to be enabled for the container.
{
    "containers": [
        {
            "class_name": "MyContainer",
            "scheduling_policy": "default", // Optional, defaults to "default". Cannot be changed after the application is created.
            "image": "./Dockerfile",
            "max_instances": 10,
            "instance_type": "basic", // Optional, defaults to "lite"
            "observability": {
                "enabled": true,
                "target_instance_percentage": 25,
            },
            "image_vars": {
                "FOO": "BAR",
            },
            "constraints": {
                "regions": ["ENAM", "WNAM"],
                "jurisdiction": "fedramp",
            },
        },
    ],
    "durable_objects": {
        "bindings": [
            {
                "name": "MY_CONTAINER",
                "class_name": "MyContainer",
            },
        ],
    },
    "exports": {
        "MyContainer": {
            "type": "durable-object",
            "storage": "sqlite",
        },
    },
}

[[containers]]
class_name = "MyContainer"
scheduling_policy = "default"
image = "./Dockerfile"
max_instances = 10
instance_type = "basic"

[containers.observability]
  enabled = true
  target_instance_percentage = 25

[containers.image_vars]
  FOO = "BAR"

[containers.constraints]
  regions = [ "ENAM", "WNAM" ]
  jurisdiction = "fedramp"

[[durable_objects.bindings]]
name = "MY_CONTAINER"
class_name = "MyContainer"

[exports.MyContainer]
type = "durable-object"
storage = "sqlite"

durable_object scheduling policy

The durable_object policy is in beta. It lets each Durable Object supply its Container image or snapshot and instance size to ctx.container.start(). Set scheduling_policy to "durable_object" explicitly. The linked Durable Object must use SQLite storage.

A durable_object entry accepts only the following options. Wrangler rejects every other Container application field for this policy, including image, instance_type, max_instances, rollout settings, and placement constraints.

  • scheduling_policy string required
  • Must be set to "durable_object".
  • images Record<string, object> optional
  • Named images that Durable Object code can access through ctx.container.images. A configuration can contain up to 100 named images, and each name must contain 1-128 characters.
  • Each named image must set exactly one of dockerfile or image.
  • images.<name>.dockerfile string conditional
  • Path to a local Dockerfile. wrangler deploy builds and pushes the image.
  • images.<name>.build_context string optional
  • Build context, relative to the Wrangler configuration file. Defaults to the directory of dockerfile. Only valid with dockerfile. Equivalent to image_build_context in the default policy.
  • images.<name>.build_vars Record<string, string> optional
  • Build-time variables, equivalent to image_vars in the default policy. Only valid with dockerfile.
  • images.<name>.image string conditional
  • A digest-pinned image reference in the Cloudflare Registry.
  • class_name string conditional
  • The corresponding Durable Object class name.
  • Omit this field when the Container is linked by name from exports.<Class>.container.
  • name string conditional
  • The name of the Container application. Defaults to a combination of your Worker name and the class name.
  • Required when class_name is omitted so that exports.<Class>.container can reference the Container.
  • observability object optional
  • Set either observability.enabled or observability.logs.enabled to enable or disable application-wide Container logs.
  • Instance targeting with target_instance_count or target_instance_percentage is not supported. If you omit observability, Wrangler preserves the application's existing setting instead of inheriting the root Worker setting.
  • unsafe.configuration.experimental_flags string[] optional
  • Experimental application flags. This is the only unsafe setting accepted with the durable_object policy.
  • ssh object optional
  • Configuration for SSH through Wrangler. Refer to SSH. The deprecated wrangler_ssh alias is not accepted with the durable_object policy.
  • authorized_keys object[] optional
  • Public keys that should be added to the Container's authorized_keys file. Refer to Authorized keys.

Name one or more images and select one from Durable Object code when the Container starts:

{
    "containers": [
        {
            "class_name": "AgentComputer",
            "scheduling_policy": "durable_object",
            "images": {
                "base": {
                    "dockerfile": "./container/Dockerfile",
                    "build_context": ".",
                    "build_vars": {
                        "APP_ENV": "production",
                    },
                },
            },
        },
    ],
    "durable_objects": {
        "bindings": [
            {
                "name": "AGENT_COMPUTER",
                "class_name": "AgentComputer",
            },
        ],
    },
    "exports": {
        "AgentComputer": {
            "type": "durable-object",
            "storage": "sqlite",
        },
    },
}

[[containers]]
class_name = "AgentComputer"
scheduling_policy = "durable_object"

[containers.images.base]
dockerfile = "./container/Dockerfile"
build_context = "."

[containers.images.base.build_vars]
  APP_ENV = "production"

[[durable_objects.bindings]]
name = "AGENT_COMPUTER"
class_name = "AgentComputer"

[exports.AgentComputer]
type = "durable-object"
storage = "sqlite"

Configure the startup image or snapshot and instance size in ctx.container.start(). Refer to Scheduling policy for a code example.

Custom instance types

In Wrangler configuration, custom instance types apply only to the default scheduling policy. With the durable_object policy, pass a custom instance object to ctx.container.start() instead. Refer to Scheduling policy.

In place of the named instance types, you can set a custom instance type by individually configuring vCPU, memory, and disk. See the limits documentation for constraints on custom instance types.

The following options are available:

  • vcpu number optional
  • The vCPU to be used by your container. Defaults to 0.0625 (1/16 vCPU).
  • memory_mib number optional
  • The memory to be used by your container, in MiB. Defaults to 256.
  • disk_mb number optional
  • The disk to be used by your container, in MB. Defaults to 2000 (2GB).
{
    "containers": [
        {
            "image": "./Dockerfile",
            "instance_type": {
                "vcpu": 1,
                "memory_mib": 3072,
                "disk_mb": 4000,
            },
        },
    ],
}

[[containers]]
image = "./Dockerfile"

[containers.instance_type]
  vcpu = 1
  memory_mib = 3_072
  disk_mb = 4_000

SSH

Configuration for SSH access to a Container instance through Wrangler. SSH configuration applies to both the default and durable_object scheduling policies. For a guide on connecting to Containers via SSH, refer to SSH.

The following options are available:

  • enabled boolean optional
  • Whether SSH through Wrangler is enabled. Defaults to true. Set to false to disable SSH access.
  • port number optional
  • The port for the SSH service to run on. Defaults to 22.

Authorized keys

An authorized key is a public key that can be used to SSH into a Container.

The following are properties of a key:

  • name string required
  • The display name of the key.
  • public_key string required
  • The public key itself.
  • Currently only the ssh-ed25519 key type is supported.

Bundling

Note

Wrangler bundling is not applicable if you're using the Cloudflare Vite plugin.

Wrangler can operate in two modes: the default bundling mode and --no-bundle mode. In bundling mode, Wrangler will traverse all the imports of your code and generate a single JavaScript "entry-point" file. Imported source code is "inlined/bundled" into this entry-point file.

It is also possible to include additional modules into your Worker, which are uploaded alongside the entry-point. You specify which additional modules should be included into your Worker using the rules key, making these modules available to be imported when your Worker is invoked. The rules key will be an array of the below object.

  • type string required
  • The type of module. Must be one of: ESModule, CommonJS, CompiledWasm, Text or Data.
  • globs string[] required
  • An array of glob rules (for example, ["**/*.md"]). Refer to glob ↗︎.
  • fallthrough boolean optional
  • When set to true on a rule, this allows you to have multiple rules for the same Type.

Example:

{
    "rules": [
        {
            "type": "Text",
            "globs": ["**/*.md"],
            "fallthrough": true,
        },
    ],
}

[[rules]]
type = "Text"
globs = [ "**/*.md" ]
fallthrough = true

Importing modules within a Worker

You can import and refer to these modules within your Worker, like so:

index.jsjs

import markdown from "./example.md";

export default {
    async fetch() {
        return new Response(markdown);
    },
};

Find additional modules

Normally Wrangler will only include additional modules that are statically imported in your source code as in the example above. By setting find_additional_modules to true in your configuration file, Wrangler will traverse the file tree below base_dir. Any files that match rules will also be included as unbundled, external modules in the deployed Worker. base_dir defaults to the directory containing your main entrypoint.

See https://developers.cloudflare.com/workers/wrangler/bundling/ ↗︎ for more details and examples.

Python Workers

By default, Python Workers bundle the files and folders in python_modules at the root of your Worker (alongside your wrangler config file). The files in this directory represent your vendored packages and is where the pywrangler tool copies packages into. In some cases, you may find that the files in this folder are too large and if your worker doesn't require them then they just grow your bundle size for no reason.

To fix this, you can exclude certain files from being included. To do this use the python_modules.exclude option, for example:

{
    "python_modules": {
        "exclude": ["**/*.pyc", "**/__pycache__"],
    },
}

[python_modules]
exclude = [ "**/*.pyc", "**/__pycache__" ]

This will exclude any .pyc files and __pycache__ directories inside any subdirectory in python_modules.

By default, python_modules.exclude is set to ["**/*.pyc"], so be sure to include this when setting it to a different value.

Local development settings

Note

If you're using the Cloudflare Vite plugin, you should use Vite's server options ↗︎ instead.

You can configure various aspects of local development, such as the local protocol or port.

  • ip string optional

  • IP address for the local dev server to listen on. Defaults to localhost.