0003. nereus init prepares the platform; reefs and Nereids are added at runtime¶
In short
nereus init prepares a cluster with the built-in core reef and a profile's reefs; every other capability arrives later as a reef, with Nereids added at runtime. Status: Proposed (2026-10-17, rewritten 2026-10-25). What init installs is revised by ADR 0014.
Status: Proposed (2026-10-17, rewritten 2026-10-25)
Context¶
In the project this one grew from, platform init installs the whole platform: identity, API, every controller, ingress, observability. Adding or swapping a capability means changing init, and there is no way to run the platform with less, or with something else.
There is one exception to "less": secrets. Every other reef needs a place for credentials, and the first Nereid that keeps secrets needs something to exist outside the cluster before any Nereid runs (in Azure: a Key Vault, a Managed Identity federated with the cluster's issuer). That chicken-and-egg can only be solved by the person's own login, once.
Decision¶
nereus init prepares a cluster with the built-in core reef, then installs the reefs of a profile (ADR 0014, profiles: core is only the engine, and a profile lists what to install). The secrets reef is not fixed at init: it comes when the profile, or a Nereid it installs, requires it. Every other capability arrives later as a reef, added by name, and Nereids that look after it:
# Core only, the default profile core: to build piece by piece
nereus init
# A local platform on k3d: core, then the profile internal-developer-platform: authentication with
# keycloak, after what keycloak requires, the secrets reef kept by OpenBao
nereus init --profile internal-developer-platform
# A platform whose first secrets Nereid is Azure Key Vault
nereus init --target azure
# Every other reef and its Nereids, added at runtime
nereus reef list
nereus reef apply authentication --from-file ./reefs/authentication/
nereus nereid apply keycloak --reef authentication
- The profile decides whether the secrets reef comes with init (#420).
core, the default, installs nothing beyond core (#424).internal-developer-platforminstallsauthenticationwith thekeycloakNereid, which requires thesecretsreef: so thesecretsreef, its first Nereid, the reef's default Mandatevault, and the Mandate's RSA key come first, with its public key published in the Mandate's status for the CLI (ADR 0011). With no target that Nereid isopenbao, with OpenBao in dev mode in its Pod (in memory: a restart makes a new key, whichinitand the Mandate's status say). A Nereid that needs secrets declares that it requires the reef; nothing installs secrets because it is secrets. - With
--target azure, init still installs the secrets reef with Azure Key Vault, since the cloud bootstrap needs it; how a profile follows the target is left to its own issue (ADR 0014). - Adding the secrets reef again is not part of the person's flow once a profile installed it.
nereus reef create secretsfails as anycreateof a thing that exists (ADR 0013), and the message points tonereus reef list;nereus reef apply secretsreportsreef/secrets unchanged, orconfiguredwhen it changed something. --target <provider>decides the first secrets Nereid and provisions what it needs to be reachable. Forazure: Key Vault, Storage, DNS zone and a Managed Identity, with the RSA key of the secrets reef (ADR 0011). Init uses the person's ownazlogin, since no Nereid exists yet; from then on, the Nereid uses workload identity, with no stored secret.- The cluster's issuer is made public: the OIDC discovery document and the JWKS of the cluster are published to the Storage account, and the Managed Identity is federated with that URL, so Azure accepts tokens signed by the local cluster.
- Undercloud and overcloud. A local k3d cluster (the undercloud) bootstraps and provisions the overcloud (for example AKS); then the platform pivots to the overcloud, the federated credential moves to the overcloud's issuer as an explicit step, and the undercloud is deleted.
nereid applyrecords the Nereid (name, image, reefs, parameters) and runs its image as a Deployment. The Nereid reportsReadyin itsstatuswhen it is up.- Until the Platform API exists, the CLI does this with the kubeconfig, as
helmdoes. The API itself becomes one more Nereid added this way; after it, everything goes through the API. initinstalls the chartnereuswith Helm (amended 2026-11-05, #1044): the kinds, the namespace and the Nereus API come fromcli/src/nereus/charts/nereus, the API throughhelm upgrade --install nereusinnereus-system, so the cluster holds a release a HelmRelease can take over later (#1045). Helm runs with the same kube context and kubeconfig as the Kubernetes client, and no other credential; it is the one tool besides the client, checked atinit'sprerequisitesstep (4.0 or newer, for--take-ownershipand--force-conflicts, which takes a kind or an object changed in the cluster back to the chart's). The kinds come before it from their own chart,cli/src/nereus/charts/nereus-reefs, as templates withhelm.sh/resource-policy: keep(amended 2026-11-05, #1050):helm upgrade --install nereus-reefsupdates them on every run, andhelm uninstallnever deletes one. The chart holds theInstallationtoo (#1051), named byinstallation.name, its id kept bylookupof the stored one; init still creates it with the client before Helm, until #1055. The profile's reefs stay with the client.- Removing a Nereid removes its Deployment and the commands it added to the CLI (ADR 0004).
The Vault kind¶
The secrets Nereid is installed once; each vault it keeps is a Vault, a kind of the secrets reef (secrets.getnereus.dev/v1alpha1), one object per vault inside that Nereid. A person names the vault a secret goes to with --vault, and leaves it out to use the default vault (order 20261026-0640):
# The default vault, when --vault is left out
nereus secrets apply google-sso --from-file google-sso.json
# Another vault the same Nereid keeps
nereus secrets apply google-sso --from-file google-sso.json --vault team-a
kubectl get vaults.secrets.getnereus.dev
# NAME NEREID DEFAULT FINGERPRINT
# default openbao true SHA256:aA57xN3...
# team-a openbao SHA256:Qm9vY2...
apiVersion: secrets.getnereus.dev/v1alpha1
kind: Vault
metadata:
name: team-a
spec:
nereid: openbao
default: false
params: {} # where the Nereid keeps it: a path, a Key Vault URL
status:
publicKey: {} # what the Mandate's status.publicKey holds today (ADR 0011)
- One Nereid, many vaults: the Nereid is not installed again for a second vault; a new
Vaultobject is enough, and the Nereid makes it ready. - One default: at most one
Vaulthasspec.default: true, and a secret with no--vaultgoes to it. A command that would make a second default fails and names the current one. - The profile that installs the secrets reef (ADR 0014) creates its default vault, as it creates the default Mandate
vaulttoday. - No
--vaultexists yet: on 2026-10-26 the CLI has no secrets command at all (nereus secrets applyis designed in ADR 0011, not built), so the flag is born with the command.
Prior art¶
- Kubernetes default StorageClass (kubernetes.io, "Storage Classes"): a claim that names no
storageClassNamegets the class annotatedstorageclass.kubernetes.io/is-default-class: "true". A secret with no--vaulttakes the defaultVaultthe same way; Nereus allows one default, where Kubernetes takes the most recent of several. - cert-manager Issuers (cert-manager.io, "Issuer"): one installed cert-manager serves many
IssuerandClusterIssuerobjects, each a certificate authority it signs with. AVaultis the same shape: one secrets Nereid, many vaults as objects. - Cluster API, bootstrap and pivot (
clusterctl move): a temporary bootstrap cluster creates the management cluster, andclusterctl movetransfers the resources to it; the undercloud and overcloud take the same shape and the word "pivot".
Consequences¶
- A platform is the set of reefs and Nereids in it. Two installations can differ in what they offer.
- Adding a Nereid is running code with permissions in the cluster. Once the API exists,
nereid applyis for platform admins only, and images are pinned by digest. Before that, whoever holds the kubeconfig already has that power. - The order matters (the secrets reef and its Nereid come first, a Nereid that installs others before them); init takes the first part on itself, and the rest has to be visible to the person running it: each output ends with
Next steps:(ADR 0013). - With
--target, the platform starts with a cloud dependency; with no target, the secrets Nereid runs in the cluster (OpenBao), when the profile requires it. - After a plain
nereus init(the profilecore),nereus nereid apply keycloakis refused until a Nereid looks after thesecretsreef, as any Nereid whose required reef has none.
Open questions¶
- How a
Vaultrelates to the Mandate: ADR 0011 says the key belongs to the Mandate, which picks the target vault through its params. Recommendation: the key and the target move to theVault, and the Mandate only binds the reef to its Nereid. -
The default vault's name:
default, orvaultas the default Mandate is named today. -
Whether init prints what the person's login granted, so it can be removed afterwards (least privilege).
- How OpenBao, the secrets Nereid of
nereus initwith no target, is unsealed after a restart. Demos may run it in dev mode or with auto-unseal; the production answer is open.
Rewritten 2026-10-25 from voice session; raw data in Drive #pontos/raw/2026-10-25. Rewritten again 2026-10-25 (order 20261025-1724): init installs the secrets reef, its first Nereid, the default vault Mandate and the reef's RSA key. Rewritten 2026-10-26 (order 20261026-0508, divergence 4): the secrets reef is not fixed at init; the profile decides, and keycloak requires it (#420). Revised 2026-10-26 (order 20261026-0640): the default profile is core (#424); the Vault kind, one object per vault inside the secrets Nereid; the ADR stays Proposed.