Skip to content

0006. Installation identity: a name, an id and an alias for each installation

Status: Proposed (2026-10-18)

Changed by answer 15 on PR #151 (spec 0005); built by #251.

Intent

Every installation of the platform has a unique, stable identity (#154), so that whatever it creates outside itself (cloud resources and their tags, spec 0005 and #82; cost data, #64; the stricter tag rules of #155) can be traced back to it without ambiguity, even when several installations share a cloud account.

The identity is three values: a name a person chooses or accepts (tailwind), which never changes and is the installation's part of every name the platform generates outside itself; an id (a random UUID, version 4) that never changes either; and an alias, what listings show, which may change. All live in one object of the platform's API group in the nereus namespace, as the SLO of spec 0004 does, so the pivot (#61) moves it to the overcloud with the rest of the platform's objects: the undercloud and the overcloud are one installation, one identity (owner, #82). The role (undercloud or overcloud) is a separate attribute, not part of the identity.

The scene that ends the slice

nereus init --yes                                      # step "installation": created, with its name
nereus config installation show
# NAME            ALIAS           ID
# nereus-local  nereus-local  3f2c0d4e-...
nereus init --yes                                      # step "installation": kept; the name and the id are the same
nereus config installation set --alias acme-prod       # the alias changes, the name and the id do not

The object

One Installation object in the nereus namespace (names.NAMESPACE), of the platform's API group (names.API_GROUP, v1alpha1), named after the installation; its CRD is cli/src/nereus/crds/installation.yaml, applied by init with the other kinds.

kind: Installation
metadata:
  name: tailwind
spec:
  id: 0b7e4c1a-…
  alias: Tailwind Prod
  naming:
    overrides:
      issuer:
        storage: tailwindissuers01

The init file holds the object itself (owner, 2026-10-18): nereus init --generate-file writes two documents, how to build the platform from this machine and the installation exactly as it goes to the cluster, and the first init writes the generated id back into it, so recreating the undercloud from the file (#61) keeps the same installation:

# how to build the platform from this machine
apiVersion: platform.example.com/v1alpha1
kind: InitConfig
spec:
  # the target cloud; without it, only the local cluster
  cloud: azure

  # this machine's k3d cluster
  undercloud:
    create: true
    name: tailwind-undercloud

  # the cloud cluster, created at the pivot (#61)
  overcloud:
    create: true
---
# the installation, as it goes to the cluster
apiVersion: platform.example.com/v1alpha1
kind: Installation
metadata:
  name: tailwind
spec:
  # written by the first init
  id: 0b7e4c1a-…
  alias: Tailwind Prod

installationName leaves InitConfig, and createCluster becomes undercloud.create. With its id, the file is the installation's definition: two machines with the same file are the same installation.

Field Type Written by Meaning
metadata.name string, the installation's name init, once The installation's name, which Kubernetes never lets change, so it is the installation's part of every generated name: its resource group tailwind-platform, its identities tailwind-<interface> (spec 0005). A company that wants its resources under another name gets a new installation and migrates to it (#249).
spec.id string, a UUID init, once The identity. Generated by the CLI with uuid.uuid4() when the object is created; the CRD refuses any change to it (self == oldSelf). Its first 16 hex characters, dashes removed (<id16>), name the cloud resources whose names are global and short (spec 0005).
spec.alias string, free text (owner, 2026-10-18), at most 63 characters, no control characters init when it creates the object, equal to the name; nereus config installation set --alias later What listings show. Changing it changes no resource name; the name in #155's tags is the installation's name.
spec.naming.overrides map, grouped by what a resource serves, then its kind the person: the answer to the CLI's question, or nereus config installation set --naming-override <path>=<name> The names a person gives when a generated one is taken by someone else (spec 0005): issuer.storage, state.storage, secrets.vault. Each is validated against its resource's own rules, and cannot change once its resource exists.
  • A name is lowercase letters, digits and -, starts with a letter, and has at most 63 characters: [a-z][a-z0-9-]{0,62}, validated with re.fullmatch by the CLI and by the CRD's pattern. A name is a valid Kubernetes object name, a GCP label value and the start of an Azure resource name (#82). Further rules of other clouds are #155's.
  • Spec only. The CLI writes spec (ADR 0005); there is no Nereid and no status.
  • spec.id and spec.alias required. An object without an id is never valid.
  • One object per installation. A namespace holds the platform of one installation, so init and the command read the only Installation there; a second one is an error that names both.

Where the name comes from

init takes it from a setting, installation_name (flag --installation-name, or the metadata.name of the settings file's Installation), else from the cluster name (the name setting, nereus-local by default), with the source cluster name. A name that breaks the rules stops init before anything changes, naming the setting to fix; a cluster name that is not a valid name (2026-demo, starting with a digit) asks for --installation-name. --generate-file writes the Installation with its name, so the file is the installation's definition (#251).

What init does

A new step, installation, after kinds and namespace:

  • No object yet: it generates the id, creates the object with the name and an alias equal to it, and prints created <name>.
  • An object already there: it changes nothing and prints kept <name>. The name and the id never change; the alias is nereus config installation set's. When a name was given (flag or file) and differs from the one in the cluster, the line says so: the name cannot change, so a different name means a new installation.
  • Two init runs at once cannot create two identities: the object is created, never replaced, and the run that loses the race reads the other's.

A recreated cluster (nereus-local deleted and created again) is a new installation, with a new id, unless it is restored from a backup that carries the object.

The command

The walkthrough shows it: The installation.

nereus config installation, next to nereus config slo (spec 0004):

  • show: one row, NAME, ALIAS and ID. With no object, it fails and asks for nereus init.
  • set --alias <alias> and set --naming-override <path>=<name>: change the alias and the overrides, keep the name and the id, and print one line per change: the object's field and its new value, then the settings file it updated, with its path, when the installation came from one (owner, 2026-10-18). It never creates the object: only init makes an id.

There is no reset and no rename: deleting the identity would make a new installation.

Security and quality attributes

Under the lens of #28, this slice is alpha.

  • An id identifies, it does not authenticate. Nothing grants rights because a tag carries it; a collision or a spoofed tag misleads a report, never an access decision.
  • The name and the id cannot drift: Kubernetes never changes an object's name, the CLI never writes the id after creation, and the CRD refuses a change, so a hand edit fails too.
  • What a person types is validated before it reaches the cluster (re.fullmatch), and again by the CRD's schema; each naming override against its resource's own rules.
  • Fitness functions of the slice: unit tests of the name rules, of the overrides' validation, of init's step and of the command; the CRD contract tests; test/scene checks the object exists and its id stays the same across a second init.

Learn more

  • UUID version 4 (RFC 9562): the installation's id, random.
  • Fitness functions come from Building Evolutionary Architectures (Neal Ford, Rebecca Parsons, Patrick Kua, O'Reilly, 2017; evolutionaryarchitecture.com): an automated check that a quality of the architecture holds, run on every change. This spec lists its own under "Security and quality attributes".