Skip to content

0026. The environment reef: an Environment is only the request, and the kept cluster is naxos

In short

The environment reef has one kind, Environment, which is only the request; the cluster kept for it is naxos. Status: Proposed (2026-11-14).

Status: Proposed (2026-11-14)

Context

The Environment kind and the vcluster Nereid exist (#620), installed by the internal-developer-platform profile (#827), and a release Target with an environmentRef delivers into that Environment's cluster through the flux Nereid (#828). No ADR records the reef: what a person writes, what a Nereid writes, and how the release reef finds where to deliver. ADR 0010 (reefs at runtime) says only that the environment "knows the cluster and its credentials".

The kept k3d cluster, k3d-nereus, runs Triton and serves as production, but no Nereid knows it: #556 (two local k3d clusters at most) calls it production, and #159 and #160 (the always-on environment deployed from main) call it live. ADR 0017 (resource reefs) is Accepted and settles how a request picks its Mandate; this reef is its first user with two Nereids. #568 asked for the refinement, in the design session of 2026-10-30 on the catalog (#559), the tenancy (#21) and the resource reefs (#560).

Decision

An Environment is only the request. The reef is environment.getnereus.dev/v1alpha1, with one cluster-scoped kind, Environment. One writer per field (ADR 0005):

Field Writer What it holds
spec.owner the person who it is for, {kind, name} in the tenancy tree (ADR 0015)
spec.region the person optional, where it should run
spec.expires the person optional, a duration after which it goes away
spec.mandate the person optional, the Mandate to go through, by name
status.nereid, status.mandate, status.phase the Nereid who made it, through which Mandate, and its state
status.expiresAt the Nereid creationTimestamp plus spec.expires
status.kubernetes.context, status.kubernetes.secretRef the Nereid how to reach a Kubernetes environment: a context name and a reference to the Secret holding its kubeconfig

spec names no technology (ADR 0002, the model): the person never names a cluster type, a provider or a Tool. A kept cluster, a vcluster, Cloud Run, Azure Container Apps or AWS Fargate are each a Nereid behind a Mandate, and each writes what it made in status. Credentials are never inline: secretRef points at a Kubernetes Secret today, and the secrets reef (#529) takes the kubeconfig over when it exists, without changing the field.

The Mandate is the one named, else the reef's default (ADR 0017's order, steps 3 and 4: no match key fits an environment's request today). The vcluster Nereid's Mandate is the reef's default, so every environment a person asks for, a PR's included, is a vcluster unless it names another Mandate. The kept cluster is the only environment that names one: nereus init creates it with --mandate local. match gets no expires key: ADR 0017 compares values, and "has an expiry" is a presence test (owner, 2026-11-14). Each Nereid acts only on the Environments whose Mandate names it, so the vcluster and k3d Nereids share the reef without touching each other's objects, as the vcluster Nereid already does.

The kept k3d cluster is the Environment naxos, an Aegean island (owner, 2026-10-30). The name is a disposable label like any other environment's, never prod: migrating data, restoring a backup, or swapping the cluster under a Workload changes the environment, not the Workload, all through the platform. It replaces production in #556 and live in #159 and #160 with one name.

A k3d Nereid registers naxos (a stand-in). It runs in the local-nereids image and knows only the cluster it runs in: it adopts that cluster for an Environment whose Mandate names it, writes status.kubernetes, refuses to make a second one, and never deletes the cluster; deleting naxos removes only the record. Only a Nereid writes its reef's status (ADR 0002), so nereus init asks for naxos like a person would and does not write its status, and the release reef reads naxos like any other environment (owner, 2026-11-14). It retires when a real environment Nereid makes clusters. #575 (the reef's first slice) builds it.

At expires, the Nereid that made the environment removes it, writes Expired in status.phase, and leaves the Environment until nereus environment delete, so the history stays visible. The vcluster Nereid already does it; naxos takes no expires.

The release reef finds its target in the Environment's status. A release Mandate's match on environment (ADR 0017) picks the Nereid that knows how to deliver there: flux for a Kubernetes environment, another Nereid for Cloud Run, with the same nereus release create. A Target with no environmentRef keeps meaning the cluster Nereus runs in, which is naxos on k3d; whether a Target may name a cluster directly stays ADR 0010's open question.

Hostnames per environment belong to the edge reef. Internal hostnames <workload>.<environment>.getnereus.dev (triton.naxos.getnereus.dev) behind the public <workload>.getnereus.dev are #470's (the edge reef), not this reef's.

# The admin, once (nereus init does it on k3d)
$ nereus mandate create vcluster \
    --reef environment \
    --nereid vcluster \
    --default
✓ core/mandates/vcluster created (reef: environment, nereid: vcluster, default)

$ nereus mandate create local \
    --reef environment \
    --nereid k3d
✓ core/mandates/local created (reef: environment, nereid: k3d)

# The kept cluster, registered by nereus init
$ nereus environment create naxos \
    --owner project/nereus \
    --mandate local
✓ environment/environments/naxos created (mandate: local, nereid: k3d)

# A PR environment: the default Mandate
$ nereus environment create pr-123 \
    --owner project/nereus \
    --expires 72h
✓ environment/environments/pr-123 created (mandate: vcluster, nereid: vcluster)

$ nereus environment list
ENVIRONMENT  OWNER           NEREID    STATUS  EXPIRES
naxos        Project/nereus  k3d       Ready   -
pr-123       Project/nereus  vcluster  Ready   2d

# A release into naxos: the release reef reads its status
$ nereus release create triton \
    --source triton \
    --target naxos
✓ release/releases/triton created (mandate: flux)

nereus environment create is nereus environment environment create (ADR 0013: a kind named after its reef takes the reef's verbs). The deck is docs/specs/cli/reefs/environment.yaml.

Stand-ins: the k3d Nereid, which knows only its own cluster, until a Nereid makes clusters; the kubeconfig in a Kubernetes Secret until the secrets reef (#529) holds it; owner has nothing behind it until the authorization reef (#897).

Prior art

  • Crossplane's claims and compositions: the person's claim names no provider; the composition the admin chose makes it and writes back its connection details, here the Mandate and the Nereid's status.
  • Kubernetes StorageClass: a default class and a class named per request, the order ADR 0017 follows here.
  • Argo CD's cluster secrets and Flux's kubeConfig.secretRef: a delivery target reached through a referenced kubeconfig, never inline.
  • Preview environments removed at an expiry, as the vcluster Nereid already does (#620).

Consequences

  • One shape for every environment, whatever makes it: the release reef, the delivery reef (ADR 0020) and the catalog read status, never a technology.
  • nereus init gets one more step: the local Mandate and the Environment naxos, through the k3d Nereid (#575).
  • The reef has two Nereids at once, which ADR 0017 allows; neither acts on the other's Environments.
  • 159, #160 and #556 use the one name naxos.

  • A new provider (Cloud Run, Fargate) is a Nereid and a Mandate, with no change to spec or to a person's command.

Open questions

  • Whether a Target may name a cluster directly (ADR 0010).
  • What status a non-Kubernetes environment publishes (Cloud Run, Fargate): decided with its first Nereid.
  • Whether region takes part in match (ADR 0017 lists only engine, environment and owner).

Origin: the owner's decisions of 2026-10-30 in the design session on the catalog, tenancy and resource reefs (#568), and of 2026-11-14 on its visual summary (the default Mandate and the stand-in for naxos). Raw data in Drive dump-mental-prompts/opinions/2026-10-30/ and #pontos/raw/2026-11-14/.