Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 30 additions & 10 deletions packaging/ns8/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,12 +37,20 @@ Replace `calnode` with the actual registry namespace if you built your own
image (see Development). The command prints the instance name, usually
`ns8-calnode1`.

> **Use `:edge`, not `:latest`.** This module has not had a release tag yet, so
> `:latest` still points at the first build, which predates the fixes for a
> missing `create-module` action, non-executable action scripts and an
> invalid schema pattern. That build fails at `add-module`. `:latest` becomes
> usable at the next module release, at which point a pinned version tag
> (`ghcr.io/calnode/ns8-calnode:0.10.2`, say) is the better thing to install.
> **Use `:edge`, not `:latest`.** A release has been cut, but `:latest`,
> `:0.10` and `:0.10.1` all point at the **same amd64-only** image. It installs
> and works on an amd64 node, and **fails on an arm64 node** (a Raspberry Pi, for
> example), which cannot pull it.
>
> That release predates the multi-arch publishing work, so each architecture was
> pushed straight onto the public tags instead of being assembled into one
> manifest list. `:edge` is a proper multi-arch image and is correct on both.
>
> When the next module release lands, `:latest` will be multi-arch too, and a
> pinned version tag (`ghcr.io/calnode/ns8-calnode:0.11.1`, say) becomes the
> better thing to install. CI now asserts that every published tag really is a
> multi-arch index before a release is allowed to pass, so this specific

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This promise does not hold yet: the gate is failing on every publish before it can inspect anything. ns8-module.yml:257 passes MODULE_REPO: ghcr.io/Calnode/ns8-calnode, assert-multiarc.py:66 builds the GHCR token scope straight from that string, and the redundant ghcr.io/ prefix makes the token endpoint answer 400 NAME_INVALID. Main run 38836790601 (the #149 merge) dies here with cannot fetch ghcr.io/Calnode/ns8-calnode:edge: HTTP 400, so nothing is being asserted about :edge or any version tag.

Either fix the workflow first (push-manifest.sh:36 already normalises with ${repobase,,}; the assert path has no equivalent) or soften this sentence and its twin in Development. Same applies to "fails the release rather than shipping" on line 169: the assert runs after push-manifest.sh has already pushed, so it can turn a run red but cannot keep a bad tag out of the public registry.

Technical details
# The multi-arch release gate never actually runs

## Affected sites
- `.github/workflows/ns8-module.yml:257` — `MODULE_REPO: ghcr.io/${{ github.repository_owner }}/ns8-calnode` expands to `ghcr.io/Calnode/ns8-calnode`
- `packaging/ns8/assert-multiarc.py:66` — `scope=repository:{repo}:pull` takes `repo` exactly as passed in, host prefix and mixed case included
- `packaging/ns8/README.md:51` and `packaging/ns8/README.md:166` — both new sentences rest on this gate holding

## Evidence
- main run `38836790601` (push of `212f779`), step "Assert the published tags are multi-arch", `IMAGETAGS: edge`:
  `FAIL cannot fetch ghcr.io/Calnode/ns8-calnode: HTTP 400` after 4 retries
- reproduced directly:
  `https://ghcr.io/token?scope=repository:ghcr.io/Calnode/ns8-calnode:pull` → `400 {"code":"NAME_INVALID"}`;
  the same scope with the host prefix stripped, or lowercased, → `200` with a token
- `push-manifest.sh:36` already does `repobase="${repobase,,}"`, and the build step's `REPOBASE` works because `manifest add` tolerates the mixed case; only the assert's token scope is case and prefix sensitive

## Required outcome
- the gate resolves the published tags and inspects them, so a green `ns8-module.yml` run means the registry really is multi-arch
- the README states the guarantee only once it holds, in both the Install callout and the Development section

## Open question for the human
- sequencing: the assert reads the registry after `buildah manifest push --all`, so even once the casing is fixed it cannot stop a bad tag from shipping, only make the publish red. The guard that actually keeps a single-arch tag out is the arch-count refusal in `push-manifest.sh:89-95`. If "fails the release rather than shipping" is to be literally true, either reword it (the run goes red, the tag is already public) or move the assertion ahead of the push.

> breakage cannot recur silently.

Then configure it with your public hostname:

Expand Down Expand Up @@ -147,15 +155,27 @@ tag pushes, mirroring the app tags in `docker-publish.yml`:
- push a `vX.Y.Z` tag pushes module `:X.Y.Z`, `:X.Y` and `:latest`, running
app `:X.Y.Z`, so a module release always runs the matching app release

Because `:latest` only moves on a release tag, and no module release has been
cut yet, `:latest` is currently unusable (see Install). Use `:edge` until the
first module release lands.
Because `:latest` only moves on a release tag, and the one release so far was
cut before the multi-arch work landed, `:latest` is currently amd64-only. Use

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This contradicts line 162, three lines below: "Every published module tag is a multi-arch manifest (amd64 + arm64)". As written, an arm64 admin reading Development is told every tag is fine, installs :latest, and hits the exact failure this PR exists to prevent. Scope the claim to what is true, multi-arch from the next publish onward with 0.10.1 named as the amd64-only holdover.

Technical details
# "Every published module tag is multi-arch" contradicts the paragraph above it

## Affected sites
- `packaging/ns8/README.md:158-160` — "the one release so far was cut before the multi-arch work landed, `:latest` is currently amd64-only"
- `packaging/ns8/README.md:162` — "Every published module tag is a **multi-arch** manifest (amd64 + arm64)"

Both sentences are in the same section, two lines apart, and cannot both be true: `latest`, `0.10` and `0.10.1` all resolve to the amd64-only manifest `sha256:01ceca48…`.

## Required outcome
- the Development section carries one scoped claim: tags published from the next module release onward are multi-arch, and the 0.10.1 release is the known exception
- the `:latest` advice in the same section stays consistent with it

`:edge` until the next module release (see Install).

Every published module tag is a **multi-arch** manifest (amd64 + arm64). NS8
runs modules as rootless containers on the node, so a single-arch image would
install on amd64 and fail on arm64. CI builds each arch to a private
`:build-<arch>` tag and only then assembles the public tags, so an interrupted
release cannot publish a single-arch image under a version tag.
release cannot publish a single-arch image under a version tag. After
assembling, CI reads the published tag back out of the registry and asserts it
really is a two-arch index with coherent per-arch labels, so a publish that
silently produced a single-arch tag fails the release rather than shipping.

**arm64 status, stated honestly.** The image is built for both architectures and
the manifest lists both, so an arm64 node can install it. The arm64 app binary
has been executed and works: it generated its encryption key, applied all
database migrations, and served HTTP. That was under CPU emulation, though, so
**arm64 is not yet verified on real hardware.** Nothing here has run on a
physical arm64 machine or on an arm64 NS8 node, and emulation cannot show native
kernel behaviour or performance. Treat arm64 as untested until it has been
exercised on a device.

To build locally on a machine with podman and buildah, from this directory:

Expand Down
Loading