Skip to content

Start a new Nereid

Render a new Nereid from the template: a skeleton that already reports Ready, serves its metrics and passes its tests, so you only write the Tool's work.

Before you start

  • A checkout of Nereus, with uv on the PATH: the template runs through Copier, pinned and run by uvx, so there is nothing else to install.
  • The reef the Nereid looks after, and the Tool it drives: here the edge reef and Caddy.

Steps

1. Render the skeleton

scripts/nereid/new renders templates/nereid into controllers/<tool>/ and refuses a folder that exists.

scripts/nereid/new --reef edge --tool caddy
output
✓ controllers/caddy/ created from templates/nereid (copier 9.19.1)
  server.py            the reconcile loop on nereid-sdk, Ready, status.kinds, GET /metrics, the commands' HTTP server
  kube.py              the Kubernetes API, standard library
  requirements.txt     nereid-sdk==0.2.0 (#754), pinned
  Dockerfile           edge-caddy-controller, nereid-sdk from the build context (#741)
  README.md            what the Nereid does, and what every Nereid must do
  test_server.py       the loop's tests, a failing pass counted with its reason
  .copier-answers.yml  the answers, for copier update
Next steps:
  add caddy to NEREIDS in the Makefile, its tests and lint to make test and make lint
  make nereids
  nereus nereid apply caddy --reef edge --image localhost:5111/caddy-controller:0.1.0

By default it serves the kind <reef>s; --kinds hostnames,certificates names the reef's kinds it serves instead.

2. Write the Tool's work

The Tool's work goes in reconcile() of server.py. The generated README.md lists what every Nereid must do: serve every verb of every kind of its reef, with the status its contract declares.

3. Wire it into the build

Add caddy to NEREIDS in the Makefile, and its tests and lint to make test and make lint, as the skeleton's next steps say.

4. Take a later change of the template

From the root of a clean checkout, Copier brings a change of the template as a diff that keeps the Nereid's own changes:

uvx copier==9.19.1 update \
  --defaults \
  --vcs-ref HEAD \
  controllers/caddy

Check it worked

The skeleton's tests run on the library of the checkout, as the other Nereids' do in make test:

uv run --project cli --with lib/nereid pytest -q controllers/caddy
output
.............                                                            [100%]
13 passed in 0.18s

make nereid-check, part of make test, fails when a Nereid does not pin nereid-sdk at the version of lib/nereid/pyproject.toml, in requirements.txt and in its Dockerfile.

Next

Learn more