Image Management

Push images during wrangler deploy

When running wrangler deploy, if you set the image attribute in your Wrangler configuration to a path to a Dockerfile, Wrangler will build your container image locally using Docker, then push it to a registry run by Cloudflare. This registry is integrated with your Cloudflare account and is backed by R2. All authentication is handled automatically by Cloudflare both when pushing and pulling images.

Just provide the path to your Dockerfile:

wrangler.jsonc

{
  "containers": [
    {
      "image": "./Dockerfile"
    }
  ]
}

wrangler.toml

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

And deploy your Worker with wrangler deploy. No other image management is necessary.

On subsequent deploys, Wrangler will only push image layers that have changed, which saves space and time.

Note

Docker or a Docker-compatible CLI tool must be running for Wrangler to build and push images. This is not necessary if you are using a pre-built image, as described below.

Use pre-built container images

Containers support images from the Cloudflare managed registry at registry.cloudflare.com, Docker Hub ↗, and Amazon ECR ↗.

Note

Cloudflare does not cache images pulled from Docker Hub or Amazon ECR.

Docker Hub pulls may be subject to Docker Hub pull limits or fair-use restrictions. Pulling images from Amazon ECR may incur AWS egress charges.

Use public Docker Hub images

To use a public Docker Hub image, set image to a fully qualified Docker Hub image reference in your Wrangler configuration.

For example:

wrangler.jsonc

{
  "containers": [
    {
      "image": "docker.io/<NAMESPACE>/<REPOSITORY>:<TAG>"
    }
  ]
}

wrangler.toml

[[containers]]
image = "docker.io/<NAMESPACE>/<REPOSITORY>:<TAG>"

Public Docker Hub images do not require registry configuration.

Private Docker Hub images use the private registry configuration flow described next.

If Docker Hub credentials have been configured, those credentials are used to pull both public and private images.

Note

Official Docker Hub images use the library namespace. For example, use docker.io/library/<IMAGE>:<TAG> instead of docker.io/<IMAGE>:<TAG>.

Configure private registry credentials

To use a private image from Docker Hub or Amazon ECR, run wrangler containers registries configure for the registry domain.

Wrangler prompts for the secret and stores it in Secrets Store. If you do not already have a Secrets Store store, Wrangler prompts you to create one first.

Use --secret-name to name or reuse a secret, --secret-store-id to target a specific Secrets Store store, and --skip-confirmation for non-interactive runs. In CI or scripts, pass the secret through stdin.

Use private Docker Hub images

Configure Docker Hub in Wrangler using these values:

• registry domain: docker.io
• username flag: --dockerhub-username=<YOUR_DOCKERHUB_USERNAME>
• secret: Docker Hub personal access token with read-only access

To create a Docker Hub personal access token:

1. Sign in to Docker Home ↗.
2. Go to Account settings > Personal access tokens.
3. Select Generate new token.
4. Give the token Read access, then copy the token value.

Interactive:

npm

npx wrangler containers registries configure docker.io --dockerhub-username=<YOUR_DOCKERHUB_USERNAME>

yarn

yarn wrangler containers registries configure docker.io --dockerhub-username=<YOUR_DOCKERHUB_USERNAME>

pnpm

pnpm wrangler containers registries configure docker.io --dockerhub-username=<YOUR_DOCKERHUB_USERNAME>

CI or scripts:

printf '%s' "$DOCKERHUB_PAT" | npx wrangler containers registries configure docker.io --dockerhub-username=<YOUR_DOCKERHUB_USERNAME> --secret-name=<SECRET_NAME> --skip-confirmation

After you configure the registry, use the same fully qualified Docker Hub image reference shown above.

Use private Amazon ECR images

Configure Amazon ECR in Wrangler using these values:

• registry domain: <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com
• access key flag: --aws-access-key-id=<AWS_ACCESS_KEY_ID>
• secret: matching AWS secret access key

Public ECR images are not supported. To generate the required credentials, create an IAM user with a read-only policy. The following example grants access to all image repositories in AWS account 123456789012 in us-east-1.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": ["ecr:GetAuthorizationToken"],
      "Effect": "Allow",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage"
      ],
      // arn:${Partition}:ecr:${Region}:${Account}:repository/${Repository-name}
      "Resource": [
        "arn:aws:ecr:us-east-1:123456789012:repository/*"
        // "arn:aws:ecr:us-east-1:123456789012:repository/example-repo"
      ]
    }
  ]
}

After you create the IAM user, use its credentials to configure the registry in Wrangler. Wrangler prompts you to create a Secrets Store store if one does not already exist, then stores the secret there.

Interactive:

npm

npx wrangler containers registries configure <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com --aws-access-key-id=<AWS_ACCESS_KEY_ID>

yarn

yarn wrangler containers registries configure <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com --aws-access-key-id=<AWS_ACCESS_KEY_ID>

pnpm

pnpm wrangler containers registries configure <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com --aws-access-key-id=<AWS_ACCESS_KEY_ID>

CI or scripts:

printf '%s' "$AWS_SECRET_ACCESS_KEY" | npx wrangler containers registries configure <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com --aws-access-key-id=<AWS_ACCESS_KEY_ID> --secret-name=<SECRET_NAME> --skip-confirmation

After you configure the registry, use the fully qualified Amazon ECR image reference in your Wrangler configuration:

wrangler.jsonc

{
  "containers": [
    {
      "image": "<AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/<REPOSITORY>:<TAG>"
    }
  ]
}

wrangler.toml

[[containers]]
image = "<AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/<REPOSITORY>:<TAG>"

Use images from other registries

If you want to use a pre-built image from another registry provider, first make sure it exists locally, then push it to the Cloudflare Registry:

docker pull <PUBLIC_IMAGE>
docker tag <PUBLIC_IMAGE> <IMAGE>:<TAG>

Wrangler provides a command to push images to the Cloudflare Registry:

npm

npx wrangler containers push <IMAGE>:<TAG>

yarn

yarn wrangler containers push <IMAGE>:<TAG>

pnpm

pnpm wrangler containers push <IMAGE>:<TAG>

Or, you can use the -p flag with wrangler containers build to build and push an image in one step:

npm

npx wrangler containers build -p -t <TAG> .

yarn

yarn wrangler containers build -p -t <TAG> .

pnpm

pnpm wrangler containers build -p -t <TAG> .

This will output an image registry URI that you can then use in your Wrangler configuration:

wrangler.jsonc

{
  "containers": [
    {
      "image": "registry.cloudflare.com/<YOUR_ACCOUNT_ID>/<IMAGE>:<TAG>"
    }
  ]
}

wrangler.toml

[[containers]]
image = "registry.cloudflare.com/<YOUR_ACCOUNT_ID>/<IMAGE>:<TAG>"

Note

With wrangler dev, image references from the Cloudflare Registry, Docker Hub, and Amazon ECR are supported in local development.

With vite dev, image references from external registries such as Docker Hub and Amazon ECR are supported, but vite dev cannot pull directly from the Cloudflare Registry.

If you use a private Docker Hub or ECR image with vite dev, authenticate to that registry locally, for example with docker login.

Push images with CI

To use an image built in a continuous integration environment, install wrangler then build and push images using either wrangler containers build with the --push flag, or using the wrangler containers push command.

Registry limits

Images are limited in size by available disk of the configured instance type for a Container.

Delete images with wrangler containers images delete to free up space, but reverting a Worker to a previous version that uses a deleted image will then error.