> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 0051 — Inventory-driven distributed platform setup

Status: Proposed; implementation and qualification are recorded in
[DD-0051](/reference/docs/dd/0051-distributed-inventory-setup.md).
Date: 20 October 2026. Stacked on `fix/workstation-env` at `d0837f84e`.

## Decision

Native Ansible inventory remains the authority for machines, transport, groups,
labels, taints and per-host storage devices. Resolve its variables and templates
through Ansible. Derive Kubespray's renamed groups without another authored node
list; exclude unrelated inventory members from cluster installation.

Shared administration lives in `devops/platform`, independent of personal tooling.
`ENV` selects a committed public policy; `TARGET` retains the personal workflow.
Mixed selections fail before SSH. Inventory, vault access and administrator
kubeconfig stay on the selected administration machine outside checkouts.
That machine is normally an SSH runner selected with `DEPLOY_RUNNER` and
recorded per environment. It reuses the personal workflow's runner mechanism,
shared from `devops/platform`: the workstation sends the exact commit as Git
objects; the runner holds private inputs, state, lock and log. Without a runner,
the workstation itself is the administration machine.
Restrictive local operation records hold observed identities and progress, never
a second authored topology. No new business context or API is introduced.

An explicit fresh-host profile installs one Kubespray topology, then distributed
Rook/Ceph, Istio and Argo. Existing-foundation mode observes the installed site
and invokes no installer, disk operation or legacy reset. Keep personal K3s
behaviour and its single-host safeguards. Fresh storage uses stable by-id devices,
three host replicas and the native kubelet directory.

Kubespray 2.32.0 pins Ansible 12.3.0 and supplies the reviewed Kubernetes 1.35.8
checksums. Give it a separate Python 3.12/Ansible 12.3.0 tools environment; the shared host/foundation
tools retain Ansible 2.19 on Python 3.13. Preserve source provenance under
[0042](/reference/docs/decisions/0042-legacy-source-relocation.md) before adapting its original playbook.

Ansible owns foundation layers. Argo owns the selected exact-commit application
composition. Share source bundles, image fingerprints/builds, scoped projects
and readiness including administration hooks. A foundation milestone manages Argo
only: it must not install development AAI to impersonate a complete site release.
[ADR-0058](/reference/docs/decisions/0058-distributed-services-composition.md) defines the complete
distributed services composition and retained `themelio-compat` cutover boundary.

Public exposure accepts explicit per-service hostnames and one declared
certificate owner. `existing` keeps an approved external issuer, including the
CSLab inventory's Certbot layout, and only verifies what it installed. `certbot`
lets the edge issue and renew one certificate per approved host over an HTTP-01
listener that serves only `/.well-known/acme-challenge/` and redirects everything
else to HTTPS; the renewal hook validates the configuration before reloading
nginx. Either way the closed backend and management policies are unchanged, and a
site that names no owner fails before installation. A separate SMTP TLS client
performs delayed DNS resolution and verifies upstream identity; its failure cannot
prevent HTTPS from starting. Existing DNS/sender names are references, not
approved new bindings.

Icarus retains Kubernetes/CNI, Ceph/CSI, GPUs, compatible mesh and other retained
consumers. Prepare one bounded application cutover with exact current identities,
writer fencing and explicitly disposable claims. Execution waits for a later
cutover decision and its maintenance window. Ordinary reconciliation never
performs that cutover.

## Consequences

The disposable `icaruscloudlab` qualifies the AMD64 Debian 12 fresh-host profile.
Its single control plane and etcd member do not establish HA. Debian 13, GH200,
live Icarus inventory, external identity and production activation need separate
evidence. Repeats must preserve the new cluster, data and credentials. Scaling,
Kubernetes/Ceph upgrades, data migration and destructive resets remain separate
operations. See the [operator guide](/reference/docs/distributed-setup.md).

<details class="page-source"><summary>Page source</summary>

<a href="/source/docs/decisions/0051-distributed-inventory-setup.md.txt">Source snapshot</a> · Revision `f928834c8`.

</details>