Say what Nereus has¶
Register what a repository says it runs and publishes, Workloads and Packages, from its files in catalog/, and check that it holds together: the files are the truth, the catalog reef holds a copy.
Before you start¶
- A cluster from Prepare the cluster with
--profile internal-developer-platform: it brings the catalog reef with its Nereidcatalog, which writes each entry's status and changes nothing an entry names. - The tenancy tree the entries name as owners.
- A checkout with a
catalog/folder, such as Nereus's own.
Steps¶
1. Register the repository's catalog¶
nereus catalog apply takes the folder, types first, then the entries. An owner that does not exist, or a registry a type does not take, refuses the whole folder; a second run prints unchanged.
nereus catalog apply \
--from-file catalog/
✓ catalog/workloadtypes/controller created
✓ catalog/workloadtypes/service created
✓ catalog/packagetypes/cli created
✓ catalog/packagetypes/image created
✓ catalog/workloads/flux created (owner: Project/nereids, type: controller)
✓ catalog/workloads/keycloak created (owner: Project/nereids, type: controller)
✓ catalog/workloads/openbao created (owner: Project/nereids, type: controller)
✓ catalog/workloads/triton created (owner: Project/triton, type: service)
✓ catalog/packages/nereus created (owner: Project/core, type: cli, registry: pypi)
✓ catalog/packages/openbao-image created (owner: Project/nereids, type: image, registry: oci)
Next steps:
nereus catalog check
2. Write a new entry as a file¶
nereus catalog workload create with --dry-run --output yaml prints the file to commit in catalog/, then apply. --audience is required: none says nobody talks to it. Without --owner, the owner set by nereus config set owner is used.
nereus catalog workload create edge-cloudflare \
--type controller \
--audience none \
--ref branch=main \
--dry-run \
--output yaml
apiVersion: catalog.getnereus.dev/v1alpha1
kind: Workload
metadata:
name: edge-cloudflare
spec:
owner:
kind: Project
name: nereids
type: controller
source:
ref:
branch: main
3. Check that it holds together¶
nereus catalog check fails with ✗ on a contradiction, such as an owner whose Project was deleted; a gap prints ! with its issue and passes. A lookup that did not run is a gap, never a pass.
nereus catalog check
✓ tenancy: 1 organization, 5 projects, every owner resolves
✓ types: every workload type and package type resolves, every registry allowed
! catalog/workloads/triton: audience people, agents, no edge reef (#470)
! catalog/workloads/triton: uses nats, no messaging reef (#576)
! catalog/packages/nereus: not found on pypi
0 contradictions, 3 gaps
make catalog-check runs it on the repository's files before a pull request, with a cluster that has the tenancy reef.
Check it worked¶
nereus catalog list shows each Workload with what the catalog Nereid found, - until its first pass.
nereus catalog list
WORKLOAD OWNER TYPE AUDIENCE STATUS
catalog Project/nereids controller - Ready
flux Project/nereids controller - NereidNotInstalled
keycloak Project/nereids controller - NereidNotInstalled
openbao Project/nereids controller - NereidNotInstalled
triton Project/triton service agents, people DeploymentNotFound
Next¶
- Follow the golden path: a Workload deployed into an Environment of its own.
Learn more¶
- The catalog reef: Workloads, Packages, their types, every status and command.
- ADR 0016: the files in the repository are the truth, the cluster holds a copy.