Skip to content

0002. Reef at runtime: a reef added from the CLI, and the reference Nereid installed into it from its image label

Status: Done (2026-10-17)

Intent

Prove ADR 0010 end to end from the CLI with the least new code, the way the first slice proved ADRs 0003 and 0004: a reef is an object added at runtime, a Nereid is installed into the reef its image declares, and the command group is named after the reef, not the Nereid (ADR 0011). It is the second cut of #45 (#99), after the system group of #98, and the first part of layer 1 of spec 0003: the reef label, read from the registry.

The scene that ends the slice

nereus init --yes                                   # also creates the local registry localhost:5111
make reference                                             # builds the reference image with its label, pushes it there
nereus reef apply release --from-file ./reefs/release/
nereus reef list
# NAME     NEREID
# release  -
nereus nereid apply reference-release \
  --reef release \
  --image localhost:5111/reference-release-controller:0.1.0
nereus release --help                               # the group is named after the reef
nereus release repo add example https://charts.example.com
nereus release repo list
nereus nereid list
# NEREID             REEFS    IMAGE                                              STATUS  AGE
# reference-release  release  localhost:5111/reference-release-controller:0.1.0  Ready   5s
nereus nereid delete reference-release
nereus release --help                               # the reef stays: no Nereid installed
nereus reef delete release

test/scene runs it on a throwaway k3d cluster, and also checks the two refusals: installing before the reef was added, and an image with no reef label.

Parts

  1. The Reef kind (CRD, cluster-scoped): only a name for now. spec.active comes with #72; the contract of a reef with #18. Written by the CLI (ADR 0005).
  2. The reefs on the Nereid kind, spec.reefs, required, written by the CLI.
  3. nereus reef apply | list | delete.
  4. apply refuses a name that is not a command name or that a command of the CLI already uses (init, system), and is idempotent.
  5. list shows each reef with the Nereid installed into it.
  6. delete is refused while a Nereid of the reef is installed, naming the nereus nereid delete to run.
  7. nereus nereid apply <name> --image <ref> [--reef <reef>] follows steps 1, 3 and 4 of spec 0003's layer 1, with its messages:
  8. It reads the label <API_GROUP>/reef (cli/src/nereus/names.py) from the registry. Its value is a comma-separated list.
  9. With --reef, it uses that reef, which must be one the label lists when there is a label.
  10. With no --reef, it uses the one name the label lists; it refuses several names or none.
  11. It refuses a reef that was not added (nereus reef apply <name> --from-file ./reefs/<name>/).
  12. The registry client (cli/src/nereus/registry.py), standard library only, behind one function, labels(image, platform):
  13. References are read as Docker reads them (reference-release-controller is docker.io/library/reference-release-controller).
  14. GET /v2/<name>/manifests/<ref>; for an index, the manifest of the platform of the cluster's first node (attestation entries have none and are skipped); then GET /v2/<name>/blobs/<config digest> and its .config.Labels.
  15. A 401 with a Bearer challenge gets an anonymous token from its realm, scoped to repository:<name>:pull.
  16. HTTPS, except for localhost, *.localhost and loopback addresses, as Docker does.
  17. Command groups named after the reef (ADR 0004, ADR 0010). The cache holds one entry per reef with its Nereid and the commands it published. A group with no Nereid says so, with the install hint. The first slice's group named after the Nereid is gone.
  18. The local registry. nereus init --create-cluster on k3d creates the registry k3d-nereus-registry.localhost on port 5111 (names.REGISTRY, names.REGISTRY_PORT), or reuses it. It creates the cluster with --registry-use, and with a mirror of localhost:5111 to that registry, so one reference serves docker push on the machine, the CLI's read and the cluster's pull. One registry serves every cluster init creates. Docker pushes over plain HTTP to localhost:<port>, but not to k3d-*.localhost:<port>, so the mirror is needed.
  19. The reference image gets LABEL ${API_GROUP}/reef=${REEF}. API_GROUP is a build argument with no default, passed from names.py by make reference and test/scene, so a rename stays a one-line change. REEF defaults to release; empty, it builds an image that declares no reef, for the scene's refusal.

Decisions

  1. One Nereid per reef until #72. Installing a second one into a reef was refused, naming the one to uninstall: before spec.active existed, nothing said which one the group's commands would go to. Superseded (owner, 2026-11-19, #1894): a reef takes several Nereids, one the default and the others reached through a Mandate (ADR 0011).
  2. nereus init creates and owns the local registry, shared by every cluster it creates, on a fixed port so the reference reads the same in the docs and on every machine. A cluster reused by init keeps the registries it was created with.
  3. The platform of an index is the first node's. Mixed-architecture clusters wait for a need.
  4. The labels the image declares beyond reef (requires, nereid, the version) are spec 0003's, not this slice's.

Security and quality attributes

Under the lens of #28, this slice is alpha: a proof that works end to end on a throwaway cluster, never production.

  • Read before run. The reef is read from the registry before anything is pulled or run, two or three small requests and no layer, so a wrong image is refused before it reaches the cluster.
  • What the CLI trusts from a registry.
  • References are validated before they become a URL.
  • A manifest fetched by digest, and the config blob, are checked against their digest.
  • Responses are capped at 4 MiB.
  • Redirects are followed by hand: the token is dropped when the host changes, and HTTPS never falls back to HTTP.
  • Label values are checked as command names before they name a group.
  • The digest gap, closed by #126. The labels were read from a tag, and the cluster pulled the same tag: a tag pushed again between the read and the pull ran an image whose labels were never read. The install now resolves the tag to the digest of the manifest it read and records spec.image as <repository>@sha256:... (spec 0003, Good Citizen rule 3), so the cluster pulls what was read. Signature verification comes later (#126).
  • Anonymous only. A registry that asks for credentials is refused with a message that points to #87. Private registries and their credentials are #87.
  • Plain HTTP only for this machine's registry, the local one init creates.
  • What beta would need:
  • two Nereids of one reef, with one active (#72), instead of refusing the second;
  • private registries (#87);
  • the rest of spec 0003's layer 1: requires checked, the Nereid's name and version from its labels.
  • Fitness functions:
  • unit tests of the registry client against a local HTTP registry: a plain manifest, an index, a missing label, the bearer challenge, a refused 401, a config that does not match its digest;
  • unit tests of every refusal;
  • test/scene end to end.

Constraints

Every rule in CLAUDE.md and docs/adr/ applies, especially "one writer per field" (ADR 0005) and "the API never names a Nereid": the CLI reads the reef from the image, never from a list of known Nereids.

Learn more

  • Fitness functions come from Building Evolutionary Architectures (Neal Ford, Rebecca Parsons, Patrick Kua, O'Reilly, 2017; evolutionaryarchitecture.com): an automated check that a quality of the architecture holds, run on every change. This spec lists its own under "Security and quality attributes".
  • OCI image annotations (opencontainers/image-spec): the standard keys an image's labels use (spec 0003).