aws / aws/containers-roadmap

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

Open
#2,860 0 comments 3 reactions 0 assignees View on GitHub
ECR Proposed
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.