[ECR] Blob mounting should follow OCI spec - mount blobs by existence, not manifest reference
- Dominant language
- Shell
- Stars
- 5.4k
- Forks
- 334
- PR merge metrics
- No merged PRs in 30d
Description
### Community Note
* Please vote on this issue by adding a 👍 [reaction](https://blog.github.com/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/) 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](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#mounting-a-blob-from-another-repository): 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](https://github.com/opencontainers/distribution-spec/tree/main/conformance).
**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//blobs/` returns `200 OK` — the blob is present and served.
3. `POST /v2//blobs/uploads/?mount=&from=` 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
Contributor guide
Research direction
Start with the OCI Distribution Specification's blob-mounting section and the linked OCI conformance tests for mounting an unreferenced blob. Reproduce the POST mount request after uploading a blob, then verify that ECR returns 201 Created based on blob existence rather than manifest references.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws
- Domain
- cloud, devops
- Issue type
- Bug
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100