ecr.pull-through-cache.createMirror an upstream registry under a prefix
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
prefixRequiredstring
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]+)*)*$/
upstreamRegistryRequiredenum
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.comusernameOptionalstring
Upstream user name, 1–255 characters; given together with passwordSecretId or not at all. Omitted: anonymous pulls
Constraints: 1-255 chars
passwordSecretIdOptionalstring
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.iocurl -X POST "https://console.platform-development.deutschecloud.app/ecr/api/pull-through-cache-rules" \
-H "Authorization: EWS-ACCESS-KEY $ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"prefix":"example","upstreamRegistry":"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.