For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /reference/docs/decisions/0051-distributed-inventory-setup.md.

0051 — Inventory-driven distributed platform setup

Status: Proposed; implementation and qualification are recorded in DD-0051. 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 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 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.

Page source

Source snapshot · Revision f928834c8.