Configure a private external image registry

POST/accounts/{account_id}/containers/registries

Registers credentials for a supported private external image registry so Containers can pull images from it. This endpoint does not create a registry or upload an image. Public Docker Hub images and images in the Cloudflare managed registry do not require this configuration.

Refer to Image management for supported registries and instructions for storing registry credentials.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

Accepted Permissions (at least one required)

Workers Containers Write

Path ParametersExpand Collapse

account_id: string

Body ParametersJSONExpand Collapse

auth: object { private_credential, public_credential }

Credentials for authenticating to a private external image registry. Store the private credential in Secrets Store before calling the API. Refer to Image management for the credential required by each supported registry provider.

private_credential: object { secret_name, store_id }

A reference to the private registry credential in Secrets Store. The referenced secret must have the containers scope. Raw secret values are not accepted.

secret_name: string

Name of the secret within the store.

maxLength255

minLength1

store_id: string

Identifier of the Secrets Store containing the secret.

maxLength32

minLength32

public_credential: string

The non-secret part of the registry credential: an AWS access key ID for ECR, a username for Docker Hub, or a service account email for Google Artifact Registry.

domain: string

Hostname of the private registry, without a scheme or image path. Supported hostnames are docker.io, AWS ECR hostnames, and Google Artifact Registry *-docker.pkg.dev hostnames.

kind: "ECR" or "DockerHub" or "GAR"

Registry provider. This must match domain: DockerHub for docker.io, ECR for AWS ECR, or GAR for Google Artifact Registry.

One of the following:

"ECR"

"DockerHub"

"GAR"

is_public: optional false

Omit this field or set it to false. Public Docker Hub images do not require registry configuration and cannot be added with this endpoint.

ReturnsExpand Collapse

errors: array of object { code, message, documentation_url, source }

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

messages: array of object { code, message, documentation_url, source }

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

result: object { created_at, domain, kind, public_key }

An image registry added in a customer account.

created_at: string

UTC timestamp string in ISO 8601 format.

domain: string

A string representation of a domain name. See RFC-1034 (https://www.ietf.org/rfc/rfc1034.txt). Consider that the limit of a domain name is min 3 and max 253 ASCII characters.

kind: optional "ECR" or "DockerHub" or "GAR" or "default"

The type of registry that is being configured.

One of the following:

"ECR"

"DockerHub"

"GAR"

"default"

public_key: optional string

Public component of the registry credentials. For managed registries this is a base64-encoded public key; for external registries the format depends on the registry provider.

success: boolean

Whether the API call was successful.

Configure a private external image registry

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/containers/registries \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{
          "auth": {
            "private_credential": {
              "secret_name": "API_KEY",
              "store_id": "14758f1afd44c09b7992073ccf00b43d"
            },
            "public_credential": "example-user"
          },
          "domain": "docker.io",
          "kind": "ECR"
        }'

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": {
    "created_at": "2021-04-01T12:32:41.488Z",
    "domain": "docker.io",
    "kind": "ECR",
    "public_key": "public_key"
  },
  "success": true
}

Returns Examples

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": {
    "created_at": "2021-04-01T12:32:41.488Z",
    "domain": "docker.io",
    "kind": "ECR",
    "public_key": "public_key"
  },
  "success": true
}