Merge pull request 'Issue 046 — an upstream image cannot be mirrored into the mesh's registry' (#40) from issue/mirroring-an-upstream-image into main

2026-09-14 13:27:59 +02:00
parent e773bf4c34 24d52a8380
commit 9359542990
1 changed files with 69 additions and 0 deletions
@@ -0,0 +1,69 @@
+---
+status: open
+opened: 2026-09-14
+located-in: []
+fixed-by:
+amended-design:
+---
+
+# 046 — An upstream image cannot be mirrored into the mesh's own registry
+
+## Symptom
+
+A module may declare that one of its artifacts is an image published elsewhere, to be copied into
+the mesh's own registry so machines fetch it by a digest this mesh assigned rather than by a name
+somebody else controls. Asking for such a module fails:
+
+```
+docker push <registry>/<module>/<artifact>: exit status 1
+image with reference …:latest was found but does not provide any platform
+```
+
+Nothing reaches the registry — its log has no entry for the attempt at all.
+
+## Why this matters
+
+**It is the only way a third-party image becomes the mesh's own.** Everything else a module can do
+with an image names it where it lives, so every machine fetches it from the internet, separately,
+for ever, and by whatever that name points at on the day it asks. Mirroring is what makes an image
+a thing the mesh holds and can speak about — and it is the shape most of a migration would want,
+because the services being moved are overwhelmingly third-party.
+
+Today exactly one module uses it, so nothing is broken that was working. That is also why it went
+unnoticed.
+
+## What was established
+
+Each of these was tried and observed, not assumed:
+
+- The image named is an **index over several architectures**, which is what a published image
+  ordinarily is and what a module sensibly writes down.
+- Fetching it leaves *the index* in the runtime's store. Asking about it reports a resolved
+  operating system and architecture while still holding the index, so inspecting it looks fine.
+- **Asking for a platform at fetch time does not help.** The store still holds the index.
+- **Resolving the index first does not help either.** The runtime will name the one manifest for
+  this architecture, and fetching *that digest specifically* still leaves something the registry
+  refuses, with the same message.
+- **Nor does naming the platform at push time.** The message changes to `does not provide the
+  specified platform (linux/amd64)` — for the platform that was just fetched by its own digest.
+- The tooling that exists to copy images between registries without any of this is not present on
+  the machine, and the runtime's own suggestion — push one platform — is the thing that fails.
+
+A speculative fix along those lines was written, tested, and **reverted**: it did not make the
+mirror work, and leaving machinery that resolves indexes without achieving what it was added for
+would be complexity plus a comment claiming something untrue.
+
+## How it would be checked
+
+A module declaring an upstream artifact is asked for, and the mesh's registry serves what it named
+under the module's own repository. Today that check fails at the push, which is where it should
+be checked from: the registry either serves it or it does not.
+
+## Open questions
+
+- Is copying between registries the right shape here, rather than going through a machine's image
+  store at all? A copy never needs a platform, because it moves what is there.
+- Should the mesh mirror an index or a platform? Every machine on one mesh being the same
+  architecture is an assumption that holds today and is not stated anywhere.
+- Is this the runtime's newer image store specifically? Worth knowing before working around it,
+  because a workaround for a behaviour that is itself a bug is a thing nobody removes later.