Skip to content

0014. Profiles: core is only the engine, and a profile lists the reefs, Nereids and Mandates to install

In short

Core is only the engine; a profile lists the reefs, Nereids and Mandates to install, run as the commands a person would type. It revises what nereus init installs (ADR 0003). Status: Proposed (2026-10-26).

Status: Proposed (2026-10-26)

Context

Today nereus init installs the core kinds and, with them, the secrets reef, the openbao Nereid, the default vault Mandate and the Mandate's key (ADR 0003 (init prepares core and secrets; reefs and Nereids come at runtime), #404, #406). Every other reef comes later, one command at a time: nereus reef apply, nereus nereid apply, nereus mandate create (ADR 0011, #409). A person who wants a working platform has to know which reefs, Nereids and Mandates to apply, and in which order.

Two things are mixed in init today. One is the engine: the kinds that let reefs, Nereids and Mandates exist at all. The other is a choice of capabilities, the secrets reef, made for the platform Nereus is built for first. Nereus is meant as a generic engine, and the Internal Developer Platform is one use of it.

Decision

Core is only the engine. The core reef is the Reef, Nereid, Mandate and Profile kinds of core.getnereus.dev/v1alpha1, plus the User of ADR 0006 (the person belongs to core, not to an authentication Nereid), and nothing else. Core installs no other reef: the secrets reef, the openbao Nereid and the vault Mandate move into a profile. This revises what nereus init does since #406 (ADR 0003); the change is planned here and made in its own issue.

A profile is a list of what to install: reefs, Nereids and Mandates. It runs as the commands a person would type, nereus reef apply, nereus nereid apply and nereus mandate create (ADR 0013), so a profile adds nothing the commands cannot do. The install order is not written in the profile: it comes from each Nereid's requirements (spec.requires, from the image's label core.getnereus.dev/requires). For example, keycloak requires the vault, so the vault comes first.

# Core only, the default: to build piece by piece
nereus init

# The Internal Developer Platform: secrets, authentication, authorization, policy and environments
nereus init --profile internal-developer-platform
# A sketch of the profile; its exact fields belong to the issue that builds it.
apiVersion: core.getnereus.dev/v1alpha1
kind: Profile
metadata:
  name: internal-developer-platform
spec:
  reefs: [secrets, release, authentication, authorization, policy, environment]
  nereids:
    - {name: openbao, reefs: [secrets]}
    - {name: flux, reefs: [release]}
    - {name: keycloak, reefs: [authentication]}
    - {name: openfga, reefs: [authorization]}
    - {name: kyverno, reefs: [policy]}
    - {name: vcluster, reefs: [environment]}
  mandates:
    - {name: vault, reef: secrets, nereid: openbao, default: true}
    - {name: flux, reef: release, nereid: flux, default: true}

Profiles are named by purpose, never by size. There are two:

Profile What it installs
core core only, nothing else, the default: for building piece by piece
internal-developer-platform the first full profile: Nereus as an Internal Developer Platform with interchangeable pieces. The secrets reef with openbao and the vault Mandate, release with flux and the flux Mandate, authentication with keycloak (Keycloak itself a Release of release), authorization with openfga, policy with kyverno, and environment with vcluster (open source, a virtual cluster on the local k3d)
  • The name internal-developer-platform is written in full on purpose: "IDP" is often read as Internal Developer Portal. The docs use no short name and no alias.
  • There is no minimal, default, empty or full: the profile of core alone is named after what it installs, core (it was empty until order 20261026-0640).

Nereus is a generic engine, and the Internal Developer Platform is its first distribution: a profile. Other domains may come as other profiles on the same engine.

A profile never carries a secret. Credentials reach a Nereid through the secrets reef after the profile is installed (nereus secrets apply, encrypted on the client, ADR 0011), never through the profile.

nereus init with no --profile installs core, core alone (#424). The full platform comes only when asked for, with --profile internal-developer-platform. A plain init stays fast and installs nothing a person did not ask for; the trade-off is one more flag to see something working. This reverses the first decision (order 20261026-0006), which made internal-developer-platform the default.

The name is "Profile", with no word from the sea: it says what it is to a person who meets it for the first time.

Origin

All decided by the owner: on 2026-10-25 (order 20261025-2359, which supersedes order 20261025-2352) and on 2026-10-26 (orders 20261026-0003, 20261026-0006, 20261026-0035 for the environment reef, and 20261026-0640 for the default core and the decisions below).

Decided on 2026-10-26 (order 20261026-0640), on the open points of order 20261026-0508:

  • The stand-in stays: keycloak's requirements on the secrets and release reefs are written in the CLI's table of the local Nereids until each local Nereid has its own image label.
  • A cloud target refuses --profile and installs Azure Key Vault as its secrets Nereid; accepted until the issue that joins profiles and targets.
  • #414 (the secrets Reef missing after nereus init in one CI run) stays open until its cause is found, with no rush.
  • Core holds the User kind (ADR 0006): confirmed.
  • Every ADR stays Proposed until the profile internal-developer-platform runs complete, with its five reefs. The orders are in Drive #pontos/beach/.

Prior art

  • Istio installation profiles (istio.io, "Installation Configuration Profiles"): istioctl install --set profile=<name> picks a set of components. default, demo, minimal, remote, empty, preview and ambient are mostly named by size or stage. Nereus takes the empty base and the idea of one command that installs a known set, and names its profiles by purpose instead.
  • Debian tasksel (wiki.debian.org/tasksel): during installation, a person picks a task ("web server", a desktop), and tasksel installs the packages for it. A Nereus profile is the same shape: a task named by purpose, made of pieces that also install one by one.
  • Helm umbrella charts (helm.sh, "Complex Charts with Many Dependencies"): one chart that lists its subcharts as dependencies. A profile differs in two ways: it lists pieces that each keep their own commands, and it leaves the order to the Nereids' requirements.

Consequences

  • nereus init installs core, then the profile through the same code paths as nereus reef apply, nereus nereid apply and nereus mandate create. Built in #420: --profile empty (now core, the default since #424) and --profile internal-developer-platform, whose keycloak Nereid requires the secrets reef, so the secrets reef comes as that requirement (order 20261026-0508); ADR 0003 is rewritten with it. The profiles are a table in the CLI (cli/src/nereus/profiles.py) until the Profile kind exists.
  • --target azure (ADR 0003) still decides the first secrets Nereid (Azure Key Vault). The issue that builds --profile settles how the profile's secrets entry follows the target.
  • The policy reef and the kyverno Nereid do not exist yet. The profile installs the other reefs of its list: authorization with openfga and its default Mandate openfga (#1655, spec 0011), which turns the check on in the Nereus API, and environment with vcluster. The teams reef, which no Nereid serves, is applied by a lane of its own before openfga, which reads its Teams and Members. The environment reef is the first PoC's environment API group (an environment was a virtual cluster); an azure-aks Nereid may come later as its interchangeable alternative, decided when the first real environments are provisioned.
  • The order comes from the Nereids. A Nereid's image declares what it requires (core.getnereus.dev/requires): keycloak's must name the secrets reef for the vault to come first. Every local Nereid's Dockerfile declares it since #1368, which retired the requires column of the CLI's table that stood in for it.
  • The default init stays fast, since it installs core alone; the time SLO of init (spec 0004) is checked in CI on that path, and the profile's own time shows in nereus profile apply.
  • nereus profile apply <name> layers a profile on core (#425), idempotent as kubectl apply: the demo is nereus init, then nereus profile apply internal-developer-platform, and nereus init --profile <name> is the shortcut for both. nereus profile list and nereus profile describe <name> show the built-in profiles; nereus profile create (custom profiles) is parked.
  • The profile is a setting of init (#426): spec.profile in init.yaml, besides --profile; the flag wins over the file.
  • The Profile kind joins core (ADR 0009). First the CLI ships the profiles and runs them. Later the applied Profile becomes an object in the cluster.
  • Later, better than good enough:
  • The Profile is applied as a resource in the cluster, and nereus status shows the drift between what the profile asks for and what runs. The PoC's hand-written "Divergences" list becomes a CI check.
  • An engine-boundary test proves that a reef outside the platform domain can be added without touching core.

Amendment (2026-10-30): the tenancy reef counts as part of core

Every nereus init applies the tenancy reef, the default core profile included, and a cloud target too (#646, #651). This does not change the decision above: core is still only the engine, and a profile still lists the reefs, Nereids and Mandates a person chooses. The tenancy reef counts as part of core, not as a choice of a profile, for three reasons:

  • The API keeps the tree, as it keeps the core kinds (ADR 0015, tenancy: a tenancy reef whose kinds come from each instance, with one fixed shape): the reef has no Nereid, no Mandate and no secret, so applying it installs no capability a person did not ask for.
  • Whatever says whose a thing is points to it: the catalog, an Environment, a resource Instance and a Mandate's match name an owner in the tenancy group, so every installation needs the tree before its first reef with an owner.
  • It is still a reef, not more kinds in core.getnereus.dev: each instance applies its own kinds from its reefs/tenancy/, and a tenancy Nereid may come later to sync the tree with another system; ADR 0015 says why tenancy is not in core.

So "core installs no other reef" reads: no other reef that a Nereid looks after. nereus status shows the tenancy reef Ready with no Nereid (#651), and nereus profile describe names it under every profile.

Origin: the open points of #646 (the tenancy reef's CRDs and admission), recorded in #651 by an agent on 2026-10-30; pending the owner's review, as the whole ADR.

Proposed 2026-10-26 from orders 20261025-2359, 20261026-0003 and 20261026-0006; the environment reef added from order 20261026-0035; the default core from order 20261026-0640; keycloak requires the release reef, which releases Keycloak, from order 20261026-0840 (step 2). Raw data in Drive #pontos/beach/. Amended 2026-10-30 from #651: the tenancy reef counts as part of core.

Amendment (2026-11-05): the order lives in thetis, the installer Nereid

A profile installed from the chart nereus runs in the cluster, in thetis' reconcile (#1053, parent #1049). The chart's value profile writes the Profile named nereus (spec.profile), and thetis, a Nereid that comes up with core, runs the profile's steps: the same profiles.steps that nereus init --profile runs, from the CLI's own package in its image. The order still comes from each Nereid's requirements, never from the profile. It now lives in that reconcile, not in init and not in Helm hooks.

  • Why a Nereid: each Nereid's step resolves its image by digest for the nodes' platform, reads the image's labels, creates its Secrets, and waits for it to report Ready. Helm cannot do that at run time, and its hooks order only the creation of objects and stay out of the release.
  • The status shows each step (Done, Waiting with why, Pending) and a Ready condition; a Nereid whose required reef has no Ready Nereid waits and names it.
  • thetis' rights are wide: it writes CRDs, admission policies, Deployments, Secrets and each Nereid's RBAC, so its ClusterRole holds bind and escalate.
  • The Profile is the embryo of the Operator of #77 (the Platform resource): one description of the platform, kept reconciled after the install.
  • The first profile thetis installs is secrets, the secrets reef with openbao alone; #1054 brings internal-developer-platform.
  • nereus init --profile runs no step of the profile (#1055): it passes the profile to the chart nereus as a value, then waits for the profile's Nereids and the Profile to be Ready, printing each Nereid's time. nereus profile apply still runs the same steps from a laptop.

Origin: decided by the owner on 2026-11-05, in #1049 and #1053.

Amendment (2026-11-08): the Profile wins

thetis keeps a Profile's Nereids installed, so a Nereid leaves the platform through the Profile, never by a delete by hand (#1231, from #1056). thetis runs the Profile's steps every 30 s and puts back a Nereid of the profile deleted by hand; that stays, as with Flux.

  • spec.exclude lists the Nereids of the profile a person left out: thetis does not install them and deletes them, the last installed first, as nereus nereid delete does. Leaving out a Nereid that a kept one requires is refused, naming it.
  • nereus profile apply <profile> --without <nereid> writes that list, repeated for each Nereid; the list given replaces the one the Profile holds, as apply does. It waits until thetis reconciled it. The profile itself stays the chart's value.
  • nereus nereid delete refuses a Nereid the Profile holds, --force or not, naming the Profile and the profile apply line that leaves it out.

Origin: decided by the owner on 2026-11-08, in #1231.

Amendment (2026-11-11): a profile is one YAML file the chart renders into the Profile's spec

Status of this amendment: Proposed.

A profile is one YAML file, keyed by reef, that the chart nereus ships and renders into the spec of the single Profile named nereus; thetis installs what that spec describes (#1363). It replaces the sketch of the Decision above, which named openfga and kyverno, which no profile installs:

profile: secrets
reefs:
  - name: secrets
    nereids:
      - name: openbao
        # Optional: with none, <registry>/<nereid>-controller:<chart version>, the convention (#1364).
        image: {repository: ghcr.io/getnereus/nereus/openbao-controller, tag: 0.1.0, digest: "sha256:..."}
    mandates:
      - {name: default, nereid: openbao, default: true}
  • The files live at cli/src/nereus/charts/nereus/profiles/<name>.yaml, outside templates/. The chart renders the one its value profile names under spec: with .Files.Get, and fails on a name with no file. There is still one Profile, named nereus, and spec.profile stays the name; spec.exclude is unchanged.
  • A Nereid serving a second reef is repeated there by name, without its image. A Mandate's params are never secret, as the Decision says of a profile.
  • thetis reconciles the object's spec, what this installation asked for; the CLI (profile apply, describe, list, init) reads the files. One parser, profiles.py: load(name) reads a file, from_spec(spec) reads an object, both into one dataclass that steps() takes.
  • spec.reefs is required (#1370): thetis, nereus status and nereus nereid delete read the spec alone, never the file of its name; a spec with no reefs is refused (the CRD, and thetis in the Profile's status).
  • One profile per installation: profiles are alternatives, not layers; composing them waits for a marketplace.
  • The order is never in the file: it comes from what each Nereid requires, its image's label core.getnereus.dev/requires, read from the registry; the label wins (#1368). With no registry answering (nereus profile describe or --dry-run with the network off), the offline list cli/src/nereus/requires.yaml stands in: make chart writes it from the labels of controllers/*/Dockerfile, and a test fails when a Dockerfile that names a Nereid lacks the label or when the list differs from the labels.
  • An image the profile pins runs as pinned; the local registry (NEREUS_NEREIDS_REGISTRY, NEREUS_NEREIDS_TAG) rewrites its repository prefix and its tag, and drops its digest only when it names another registry or another tag than the pinned ones (#1403). A release pins tag and digest (#1369). Replaced on 2026-11-12, below: nothing rewrites an image.
  • Reef contract versions stay in contracts.pinned; the ClusterRole stays generated by make chart.

The steps: the profile secrets first, as a walking skeleton, with spec.reefs optional and the other profiles falling back to their list in the CLI (#1365); internal-developer-platform and core as files, the entrance becoming ingress with its versions in the profile (#1366); Mandates from the file (#1367); the order from the image label (#1368); tag and digest pinned by a release (#1369); spec.reefs required (#1370).

Prior art: Istio's manifests/profiles/*.yaml (one file per profile, rendered by the installer), Flux's OCIRepository.ref (a tag for people, a digest for the machine), Crossplane's Configuration lock.

Origin: decided by the owner on 2026-11-11, in #1363.

Amendment (2026-11-12): the Profile names every image, and thetis installs it as written

The list of images is a parameter of what thetis is asked to install: the Profile (#1425). The chart writes every Nereid's image into the Profile's spec, and thetis installs each one as written: no convention and no registry override inside thetis.

  • The convention moves to the chart (#1364): for a Nereid the profile file leaves without image:, the template writes the one the profile pins for it in another reef, else <nereids.registry>/<nereid>-controller:<nereids.tag>; nereids.tag defaults to the chart's version. profiles.filled is the same rule in Python, and a test holds both equal.
  • Where the images come from is the installer's choice, the chart's values nereids.registry (default ghcr.io/getnereus/nereus) and nereids.tag. The CLI's init passes the local registry, or the one NEREUS_NEREIDS_REGISTRY names, for a cluster that cannot reach the local one, such as Nereus inside an Environment.
  • thetis refuses a spec with a Nereid and no image in the Profile's status: that spec was not rendered by this chart. NEREUS_NEREIDS_REGISTRY and NEREUS_NEREIDS_TAG leave thetis' Deployment; LOCAL_REGISTRY stays, the local registry's address from a Pod, so thetis reads an image's labels there.
  • This replaces the rewrite of #1363 and #1403: a pinned digest is never dropped, and a local build is named by the values the chart is given, not by thetis' environment.

Origin: decided by the owner on 2026-11-12, in #1425, after #1406's recorded run found that thetis inside an Environment cannot reach the local registry.