ecr.pull-through-cache.create

Mirror an upstream registry under a prefix

POST /ecr/api/pull-through-cache-rulesIAM ecr:CreatePullThroughCacheRuleChanges state

Then `docker pull <org>.ecr.<root>/<prefix>/<name>:<tag>` fetches <name> from the upstream on first pull and serves it from this registry after that (Docker Hub official images: `<prefix>/node` = `library/node`). Tags are re-checked upstream after 6 hours; when upstream fails, the cached copy is served. Bringing new images in needs ecr:BatchImportUpstreamImage. upstreamRegistry: docker.io, ghcr.io, quay.io, registry.k8s.io, public.ecr.aws, mcr.microsoft.com. A login (username + passwordSecretId, a Deutsche Cloud Secret granted to the `registry` consumer) raises Docker Hub's anonymous pull limit and reaches private upstream images.

Request syntax

POST /ecr/api/pull-through-cache-rules
{
  "prefix": "string",
  "upstreamRegistry": "enum",
  "username": "string",
  "passwordSecretId": "string"
}

Request body

  • prefixRequired

    string

    The path images are pulled under, e.g. dockerhub: <prefix>/<name> mirrors <name> upstream. 2–64 characters of lowercase path components (letters, digits, . _ - inside, / between). A prefix another rule has is refused with 409

    Constraints: 2-64 chars, /^[a-z0-9]+(?:[._-][a-z0-9]+)*(?:\/[a-z0-9]+(?:[._-][a-z0-9]+)*)*$/

  • upstreamRegistryRequired

    enum

    The registry mirrored: docker.io, ghcr.io, quay.io, registry.k8s.io, public.ecr.aws or mcr.microsoft.com

    One of: docker.io, ghcr.io, quay.io, registry.k8s.io, public.ecr.aws, mcr.microsoft.com

  • usernameOptional

    string

    Upstream user name, 1–255 characters; given together with passwordSecretId or not at all. Omitted: anonymous pulls

    Constraints: 1-255 chars

  • passwordSecretIdOptional

    string

    Id of a Secret of this organization holding the upstream password or token, granted to the registry consumer; given together with username. An id that names no secret is refused with 400

Response

201 with the rule: id, prefix, upstreamRegistry, upstreamLabel (e.g. Docker Hub), username and passwordSecretId (null without a login), repositories (how many cache repositories it has filled), createdAt (repositories 0). 409 when the prefix is taken, or with code QuotaExceeded at the organization's rule quota; 400 when passwordSecretId names no secret of the organization.

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow ecr:CreatePullThroughCacheRule on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud ecr pull-through-cache create --prefix example --upstream-registry docker.io

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_ecr_pull-through-cache_create.