# 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

```bash
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.

```yaml
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:

```yaml
# 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](../reference/installation.md).

`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](https://www.rfc-editor.org/rfc/rfc9562)): the installation's id, random.
- **Fitness functions** come from *Building Evolutionary Architectures* (Neal Ford, Rebecca Parsons, Patrick Kua, O'Reilly, 2017; [evolutionaryarchitecture.com](https://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".
