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
uvon thePATH: the template runs through Copier, pinned and run byuvx, so there is nothing else to install. - The reef the Nereid looks after, and the Tool it drives: here the
edgereef 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
✓ 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
............. [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¶
- Build a Nereid's image, with the labels that name its reef, and apply it.
- Require a reef when the Nereid needs another reef's work.
- Pass the conformance tests: every verb of every kind of its reef.
Learn more¶
- Reef, Nereid and Mandate: what a Nereid looks after.
- Spec 0003: the contract a Nereid honours.