Decide where the rewritten spec states one cluster or one tenant as an instance #359

Activity

1. ExtraToast

   added

   type: docsDocumentation-only change.Documentation-only change.

   area: deployhomelab-deploy, deploy-v2, manifests, and rollout flow.homelab-deploy, deploy-v2, manifests, and rollout flow.

   wayfinder:grillingWayfinder ticket resolved by conversation (HITL)Wayfinder ticket resolved by conversation (HITL)

   on Oct 9, 2026
2. ExtraToast

   added a parent issue on Oct 9, 2026

   • Map: re-establish deploy-kit's goals, rewrite its spec, and order the work until the estate is handed over #341
3. ExtraToast

   self-assigned this

   on Oct 12, 2026
4. ExtraToast commented on Oct 12, 2026

   

   ExtraToast

   on Oct 12, 2026

   ContributorAuthor

   More actions

   Resolution

   Settled with the maintainer on 2026-10-12. The inputs were Decide what deploy-kit is for after the course, Decide what is cut, merged or deferred from the spec and the register and Decide the chapter layout of the rewritten spec.

   What was found

   • The cluster is already a named value in five documents: Infrastructure Intent's cluster.name, the Platform document's metadata.cluster, the ClusterState snapshot's cluster, the composition lock's metadata.cluster and the node contract's cluster. No rule ties the five together.
   • Four places state "one cluster" as a fact or an exclusion: chapter 15 ("exactly one in v1"), chapter 14 ("One Platform document per estate"), chapter 55 ("A second cluster" out of scope), and three open items that repeat one parked question (chapter 00 item 6, chapter 14 item 1, chapter 40 item 3).
   • There is no Tenant, and no Estate entry in CONTEXT.md, although "estate-wide" scopes dozens of rules. "Tenant" appears six times meaning a Project that is not the platform's, which collides with the Tenant that 0097 parks.
   • "Cluster Target" is used in chapter 10 and CONTEXT.md and defined nowhere.
   • The per-cluster env overlay is specified and implemented, and nothing uses it: the examples hold 18 base.env files and no overlay, and the live-needs inventory names no need for one. An overlay for a cluster nothing declares is kept and never selected, so a misspelt overlay is skipped silently.

   The seam rule

   A named instance, with its cardinality stated once. The Cluster stays one named object. "Exactly one" is stated in chapter 15 and nowhere else. Every other chapter says "the Cluster a render is for" and never asserts how many there are. No field becomes a list, and nothing is added for a lab.

   Infrastructure Intent keeps a singular cluster key, so a second cluster cannot be written at all. That needs no refusal code of its own.

   What changes

   statement today	what it becomes
   five unrelated copies of the cluster's name	Infrastructure Intent's cluster.name declares it. The Platform document's metadata.cluster and the ClusterState snapshot's cluster refer to it, and one refusal fires when either names another cluster. The node contract and the lock are generated from checked inputs and need no check.
   "One Platform document per estate" (chapter 14)	"A Platform document is written for one Cluster, the one metadata.cluster names." substrate stays in chapter 14.
   Application Id and Project name unique "estate-wide"	unique "within the composed union", which is true at any count
   open items in chapter 00 (item 6), chapter 14 (item 1) and chapter 40 (item 3); the exclusion in chapter 55	all four leave the chapters. Chapter 00's non-goals carry the one "no second cluster" line. Whether a union spans clusters joins 0097's questions, rewritten in place.
   base.env plus one overlay per Cluster Target (chapter 10)	the overlay is cut. Env is one file per scope, and Project Intent never names a Cluster: clusters enter only through the Platform and Infrastructure documents. A per-cluster overlay returns the day a second cluster does, as 0097's question.
   "Cluster Target"	retired. The one term is Cluster, the named instance Infrastructure Intent declares. DEPLOYMENT_ENVIRONMENT derives from its name.
   "tenant" for a Project that is not the platform's	the six uses become "Project". "Tenant" means only 0097's parked concept.
   no word for the scope above a Project	Estate enters the glossary as that scope. There is no Tenant class and no Estate field. Rules about namespaces, Secret Store paths, human grants, Dashboards and the label prefix say "estate-wide" on purpose.

   What stays a fixed fact

   Each of these would cost a field that can only ever hold one value, the reason 0097 rejects a cluster dimension on placement. They are stated as plain rules in their chapters, with no "because one cluster" aside, and listed once in 0097 as what a second cluster or tenant breaks:

   • the svc.cluster.local DNS domain;
   • the Stable Address as an ExternalName;
   • one Secret Store with one kubernetes auth mount;
   • one Flux root and one Release Gate;
   • the *.jorisjonkers.dev API groups and annotation keys.

   Where the premise won over the seam

   One project file cannot carry env for two clusters. A lab render therefore needs its own copy of a project file. That is accepted: a silently skipped overlay is a real maintainer mistake at this scale, and the purpose decision says the premise wins such a conflict.

   Consequences for other tickets

   • The 1.0.0 contract pull request (Decide between a spec/v2 and reworking v1 in place) carries the overlay's removal with the other removals. staging.env in stalwart-provisioner goes at that Project's handover.
   • The chapter 15 rewrite adds the cluster-name refusal and the Cluster glossary entry. The chapter 10 rewrite removes the overlay and "Cluster Target", and settles whether the one remaining env file keeps the name base.env.
   • The compiler-structure, register-reshaping and research-gap fog graduates into tickets, since no model decision is left open on the map.

   Record

   This answer is recorded here, on the ticket. No new ADR: 0097 is the record and is rewritten in place. Each CONTEXT.md change (Estate, Cluster, and "tenant" and "Cluster Target" as avoided words) lands in the pull request that rewrites the chapter using the term, so the glossary and the spec never disagree on main.
5. ExtraToast

   closed this as completedon Oct 12, 2026