[ECR] Blob mounting should follow OCI spec - mount blobs by existence, not manifest reference

[david-a-aws]

Community Note

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request
• Please do not leave "+1" or "me too" comments, they generate extra noise for issue followers and do not help prioritize the request
• If you are interested in working on this issue or have submitted a pull request, please leave a comment

Tell us about your request

Make Amazon ECR cross-repository layer sharing ("blob mounting") conform to the OCI Distribution Specification: a blob mount request should succeed with 201 Created based solely on the blob existing in the source repository, regardless of whether any manifest in that repository references the blob.

Today, ECR only mounts a blob once it is referenced by at least one image manifest in the source repository. For an unreferenced-but-present blob, ECR returns 202 Accepted (falling back to a fresh upload session) instead of 201 Created. We would like ECR to mount any blob that exists in the source repository, matching the spec and passing the official OCI conformance tests.

Which service(s) is this request for?

ECR

Tell us about the problem you're trying to solve. What are you trying to do, and why is it hard?

We push container image layers to ECR from a build cluster and want to reuse layers that ECR already stores instead of re-uploading them. Upload volume is large, so layer reuse has a direct effect on build times.

The problem: our build cluster uploads layers before any image/manifest exists — at that point there is no manifest to write. When we then try to mount an already-uploaded layer into a target repository, the mount fails because no manifest in the source repository references the blob yet.

1. Upload a blob to repository A (monolithic or chunked upload completes with 201 Created).
2. HEAD /v2/<repo-a>/blobs/<digest> returns 200 OK — the blob is present and served.
3. POST /v2/<repo-b>/blobs/uploads/?mount=<digest>&from=<repo-a> returns 202 Accepted (a new upload session) instead of the expected 201 Created.

The OCI spec makes the mount conditional on the blob existing, not on a manifest referencing it. It states the response to a successful mount MUST be 201 Created, and that a registry SHOULD return 202 only if it "does not support cross-repository mounting or is unable to mount the requested blob." Since HEAD returns 200 and ECR does mount the blob successfully once a manifest references it, the 202 fallback for a present, servable blob is a deviation from the spec.

Are you currently working around this issue?

Yes. Before issuing a mount, we push a normal image (a dummy manifest that references the layer also works) to the source repository so the blob becomes manifest-referenced. The subsequent mount then returns 201 Created with no data transfer. This works but requires generating and pushing throwaway manifests purely to satisfy ECR's requirement, which does not fit a workflow that uploads layers before any image exists.

Additional context

• OCI Distribution Spec — Mounting a blob from another repository: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#mounting-a-blob-from-another-repository
• OCI conformance tests (push a blob and mount it without a manifest): https://github.com/opencontainers/distribution-spec/tree/main/conformance
• ECR cross-repository layer sharing announcement: https://aws.amazon.com/about-aws/whats-new/2026/01/amazon-ecr-cross-repository-layer-sharing/

Attachments

N/A