Skip to content

Build a Nereid's image

Build a Nereid's image whose labels name its reef, push it to the local registry and apply it: the CLI reads the labels before anything runs in the cluster.

Before you start

  • A cluster from Prepare the cluster: nereus init creates the local registry localhost:5111.
  • The reef applied, here release: Apply your first reef.
  • Docker, to build and push. The example is the reference Nereid of controllers/reference, whose commands only simulate output.

Steps

1. Declare the reef in labels

The Dockerfile names the reef the Nereid looks after, the reefs it requires, its name and its version:

LABEL ${API_GROUP}/reef=${REEF} \
      ${API_GROUP}/requires=${REQUIRES} \
      ${API_GROUP}/nereid=${NEREID} \
      ${API_GROUP}/reference=${REFERENCE} \
      org.opencontainers.image.version=${VERSION} \
      org.opencontainers.image.title=${TITLE}

${API_GROUP} is core.getnereus.dev. The reference Nereid's commands are data, in commands.yaml, each with its help and an example:

- path: [repo, add]
  help: Add a chart repository.
  arguments:
    - name: name
      help: Name of the repository.
    - name: url
      help: URL of the repository.

2. Build and push

make reference builds the image for the release reef and pushes it; a Nereid from the template builds with make nereids.

make reference
output
✓ localhost:5111/reference-release-controller:0.1.0 pushed: nereus nereid apply --image localhost:5111/reference-release-controller:0.1.0

3. Apply it

nereus nereid apply reads the labels, pins the image to its digest and waits for Ready.

nereus nereid apply reference-release \
  --reef release \
  --image localhost:5111/reference-release-controller:0.1.0
output
✓ core/nereids/reference-release created, Ready, pinned to sha256:ffb8e8957c6e: see 'nereus release --help'

Next steps:

  nereus nereid list

4. Move it to a new image

Applied again with another image, the Nereid is updated in place; --dry-run shows what would change and writes nothing.

nereus nereid apply reference-release \
  --image localhost:5111/reference-release-controller:0.1.1 \
  --dry-run
output
Would configure core/nereids/reference-release for reef release: image sha256:ffb8e8957c6e → sha256:3f2a9c1d7e4b.
Nothing changed (--dry-run).

Without --dry-run, the apply waits for the new pod and says what the image was:

nereus nereid apply reference-release \
  --image localhost:5111/reference-release-controller:0.1.1
output
✓ core/nereids/reference-release configured, Ready, pinned to sha256:3f2a9c1d7e4b (was sha256:ffb8e8957c6e): see 'nereus release --help'

Check it worked

nereus nereid list shows the Nereid Ready on its reef:

nereus nereid list
output
NEREID             REEFS    IMAGE                                                 STATUS  AGE
reference-release  release  localhost:5111/reference-release-controller:0.1.0     Ready   10s
openbao            secrets  localhost:5111/openbao-controller:0.1.0               Ready   1m

The commands it published are under its reef: nereus release --help.

Clean up

nereus nereid delete removes it; its reef stays.

nereus nereid delete reference-release
output
✓ core/nereids/reference-release deleted

Next

Learn more