novox/mesh-host
3
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

bootstrap: read the image id back from the runtime, never predict it

Browse Source 
An image id does not survive `docker save` -> transfer -> `docker load`. The id is
the digest of the image's *configuration*, and a runtime rewrites that
configuration as it loads: a newer Docker saves in one format, an older one stores
it in another. Same layers, same program, different name. Measured on a live raise:

  saved on the workstation  sha256:b86bb81ca2f9691f24f4725f50962d1e49c98c5ffe211113241243d42d18ceea
  loaded on the machine     sha256:2dc219046c73702fc640317f0342a28ec962ef1e9ef547b2f02861c508ca78fb

`internal/image`.ID read the id out of the carried tar and its comment said that
was the id the runtime would assign. That is true on the machine the image was
built on and false on every machine it is carried to — which is every machine this
program exists for. The installer then either stopped at step 2 refusing the
runtime's answer, or would have written a bundle naming an image the machine does
not hold; and nothing serves an image named by the digest of its own configuration,
which is the whole point of naming one that way, so the apply would have died
inside a pull that cannot succeed. The lab hit this.

So the image is identified by its TAG, which is ordinary metadata the tar carries
through unchanged. The runtime is asked what that tag resolves to before the load
(already held, nothing to do) and again after (this is what the bundle names). The
tag never reaches the bundle — a pinned bundle may not rely on one, ADR 0006 — it
is how the id is obtained, not what is written down.

  - image.ID becomes image.ArchiveID, and says plainly that it is a fact about the
    file and not a prediction about any machine. It is kept for reports, and printed
    beside the runtime's answer whenever the two differ.
  - Idempotence is decided from what the runtime holds under the tag, not from a
    predicted id, which cannot answer the question at all here.
  - An untagged archive is refused, in preflight and again at the load: there would
    be no portable name to ask about, and the only thing left is scraping a sentence
    `docker load` writes for a person. `make bootstrap` refuses an id or an untagged
    image, so it is caught in front of whoever can fix it.
  - A dry run cannot know the id and says so rather than pretending. Run refuses to
    write a bundle carrying an unconfirmed id at all.

Tests: the injected Runner now answers with an id DIFFERING from the tar's, and the
runtime's answer is what must be used. The test that refused a differing id encoded
the mistake and is replaced by one refusing an answer that is not an id at all.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF
This commit is contained in:
jschoubben
2026-09-11 00:12:36 +02:00
parent 0a88dc1f9d
commit cb5e137297
7 changed files with 410 additions and 142 deletions
Download Patch File Download Diff File Expand all files Collapse all files
internal/image/image.go
+33 -16
View File
@@ -82,20 +82,33 @@ type manifestEntry struct {
RepoTags []string `json:"RepoTags"`
}
// ID is the image id the runtime will give this image once it is loaded, read out of the tar.
// ArchiveID is what this archive calls the image it holds. **It is not necessarily the id the
// runtime will assign when the archive is loaded, and it must never be what a bundle names.**
//
// **Read here rather than parsed out of what `docker load` prints.** The load prints a sentence
// for a person — `Loaded image: name:tag` or `Loaded image ID: sha256:…`, depending on whether the
// image was saved with a tag — and a program that scraped it would be depending on which of those
// a particular runtime version chose. The id is a fact about the file, available before the
// runtime is asked anything, which is also what makes the load idempotent: the installer can ask
// whether the machine already holds THIS image before loading it.
// This was called ID, and its comment said it was the id the runtime would give the image once
// loaded. That was wrong, and wrong in the worst available way: right on the machine the image
// was saved on, and wrong on the machine it was carried to. An image id is the sha256 of the
// image's *configuration document*, and a runtime rewrites that document as it loads — a newer
// Docker saves in one format and an older one stores it in another. Same layers, same program,
// different name. Measured on a live raise:
//
// An image id is the sha256 of the image's configuration document (novox/hq ADR 0006, and see
// `internal/declaration`'s checkImage). `manifest.json` names that document by its digest — as
// `<64hex>.json` in the older layout and `blobs/sha256/<64hex>` in the OCI one — so both forms
// reduce to the same sixty-four characters.
func ID(saved []byte) (string, error) {
// saved on the workstation sha256:b86bb81ca2f9691f24f4725f50962d1e49c98c5ffe211113241243d42d18ceea
// loaded on the machine sha256:2dc219046c73702fc640317f0342a28ec962ef1e9ef547b2f02861c508ca78fb
//
// A bundle naming this id would then name an image the machine does not hold — and nothing serves
// an image named by the digest of its own configuration, which is the whole point of naming one
// that way, so the apply would stop at a pull that cannot succeed. The id a bundle names is read
// back from the runtime after the load (`internal/bootstrap`.Load), which is the only place it is
// a fact rather than a prediction.
//
// What it is still good for is a statement about the FILE — which build somebody embedded — and
// as a hint printed beside the runtime's answer when the two differ, so a person can see that
// they did.
//
// `manifest.json` names the configuration document by its digest — as `<64hex>.json` in the older
// layout and `blobs/sha256/<64hex>` in the OCI one — so both forms reduce to the same sixty-four
// characters.
func ArchiveID(saved []byte) (string, error) {
manifest, err := fileFromTar(saved, "manifest.json")
if err != nil {
return "", err
@@ -125,11 +138,15 @@ func ID(saved []byte) (string, error) {
return "sha256:" + digest, nil
}
// Tags is what the saved image was called when it was saved, for a person reading a report.
// Tags is what the saved image was called when it was saved.
//
// Decoration, and said so: the installer names the image by its id everywhere it matters, because
// a tag is exactly what a pinned bundle may not rely on (novox/hq ADR 0006). This is here so a
// report can say which build somebody embedded, which is otherwise sixty-four characters of hex.
// **Not decoration any more, and this comment used to say it was.** A tag is exactly what a pinned
// bundle may not rely on (novox/hq ADR 0006) and none of this ever reaches a bundle — but the tag
// is how the installer ASKS the runtime what id it assigned, because the id itself is not
// knowable beforehand (see ArchiveID). It is the one name that survives `docker save` and
// `docker load` unchanged, which is precisely what the id does not.
//
// It also still says which build somebody embedded, which is otherwise sixty-four hex characters.
func Tags(saved []byte) []string {
manifest, err := fileFromTar(saved, "manifest.json")
if err != nil {
internal/image/image_test.go
+23 -15
View File
@@ -39,20 +39,25 @@ func manifest(t *testing.T, config string, tags ...string) string {
return string(raw)
}
// The image id is read from the FILE, before any runtime is asked anything.
// The archive's own id is read from the FILE, in both layouts `docker save` has used.
//
// That is what makes the load idempotent: knowing the id in advance lets the installer ask "do you
// already hold exactly this" instead of loading and then finding out. Scraping it from what
// `docker load` prints would only be possible after loading, so the second run of an installer
// would load again every time and be unable to say it had not.
func TestTheImageIdIsReadFromTheSavedFile(t *testing.T) {
// **This test used to say that reading it here was what made the load idempotent — that knowing
// the id in advance let the installer ask "do you already hold exactly this". That was wrong.** An
// id is the digest of the image's configuration document, and a runtime rewrites that document as
// it loads, so this is a fact about the archive and not a prediction about any machine. What the
// installer asks a runtime by is the TAG, and what a bundle names is the answer the runtime gives
// back (`internal/bootstrap`.Load).
//
// It is still read and still checked, because it is what says which build somebody embedded — and
// because printing it beside the runtime's answer is how a person sees that the two differ.
func TestTheArchivesOwnIdIsReadFromTheSavedFile(t *testing.T) {
digest := strings.Repeat("a", 64)
// Both layouts `docker save` has used. The older one names the config `<digest>.json`; the OCI
// one names it `blobs/sha256/<digest>`. They carry the same sixty-four characters, and a
// reader that understood only one would work until somebody upgraded their runtime.
for _, config := range []string{digest + ".json", "blobs/sha256/" + digest} {
saved := savedImage(t, map[string]string{"manifest.json": manifest(t, config)})
id, err := ID(saved)
id, err := ArchiveID(saved)
if err != nil {
t.Fatalf("config %q: %v", config, err)
}
@@ -62,7 +67,10 @@ func TestTheImageIdIsReadFromTheSavedFile(t *testing.T) {
}
}
func TestTheSavedTagsAreReadForAPersonToRecognise(t *testing.T) {
// The tag is read, and it is not decoration: it is the name the installer asks a runtime by,
// because it is the one thing that survives `docker save` and `docker load` unchanged. The id
// does not.
func TestTheSavedTagsAreRead(t *testing.T) {
saved := savedImage(t, map[string]string{
"manifest.json": manifest(t, strings.Repeat("b", 64)+".json", "mesh-control:v1"),
})
@@ -74,18 +82,18 @@ func TestTheSavedTagsAreReadForAPersonToRecognise(t *testing.T) {
// A tar that is not a saved image is refused with what is wrong, not with a nil id.
//
// The installer names the control plane by this id in the bundle it writes. An id it could not
// read, treated as empty, would produce a bundle naming nothing — refused by the host two steps
// later, with a message about a declaration rather than about what somebody embedded.
// Nothing here reaches a bundle any more, but this is still the earliest moment somebody can be
// told they embedded the wrong file — and the alternative is finding out at the load, from a
// container runtime, in a sentence about a tar rather than about what was built.
func TestSomethingThatIsNotASavedImageIsRefused(t *testing.T) {
notAnImage := savedImage(t, map[string]string{"hello": "world"})
if _, err := ID(notAnImage); err == nil {
if _, err := ArchiveID(notAnImage); err == nil {
t.Error("a tar with no manifest.json was accepted as a saved image")
} else if !strings.Contains(err.Error(), "docker save") {
t.Errorf("the refusal does not say what to embed instead: %v", err)
}
if _, err := ID([]byte("this is not a tar at all")); err == nil {
if _, err := ArchiveID([]byte("this is not a tar at all")); err == nil {
t.Error("bytes that are not a tar were accepted")
}
}
@@ -101,7 +109,7 @@ func TestATarHoldingSeveralImagesIsRefused(t *testing.T) {
t.Fatal(err)
}
saved := savedImage(t, map[string]string{"manifest.json": string(entries)})
if _, err := ID(saved); err == nil {
if _, err := ArchiveID(saved); err == nil {
t.Error("a tar holding two images was accepted")
}
}
@@ -112,7 +120,7 @@ func TestATarHoldingSeveralImagesIsRefused(t *testing.T) {
func TestAConfigThatIsNotADigestIsRefused(t *testing.T) {
for _, config := range []string{"config.json", "abc.json", "blobs/sha256/" + strings.Repeat("a", 63)} {
saved := savedImage(t, map[string]string{"manifest.json": manifest(t, config)})
if _, err := ID(saved); err == nil {
if _, err := ArchiveID(saved); err == nil {
t.Errorf("config %q was accepted and is not a digest", config)
}
}