Symmetric node model: an shcnode for every node, shccluster becomes pure config (2026-07-15)
Archived, shipped. Now described in SHC Terraform provider.
Symmetric node model: an shc_node for every node, shc_cluster becomes pure config (2026-07-15)
Section titled “Symmetric node model: an shc_node for every node, shc_cluster becomes pure config (2026-07-15)”STATUS: IMPLEMENTED (2026-07-17), with flag-family renames. The symmetric model landed:
terraform/provider/internal/provider/node_resource.godeclares “EVERY node in a cluster is an shc_node; exactly one carriesbootstrap = true”, with the genesis inputs on bothshc_nodeand the pure-configshc_cluster. Two input families were renamed by F8/F9 between this design and the landed shape; read the mapping tables below with these substitutions:
traefik_le {email, staging}→ theacmenested block (named providers + default), forwarded asshc init --acme-provider/--acme-directory/--acme-email(the--traefik-le*flags are deleted;init_test.gopins them absent). See the acme-providers proposal.system_apps(string,--system-apps) → themodulesmap (per-app overrides; the key set is the install selection), forwarded asshc init --modules-config.
The refactor
Section titled “The refactor”Today the cluster/node resource split is ASYMMETRIC. shc_cluster owns the
bootstrap node (nodes[0]) AND carries the cluster’s genesis config;
shc_node is only the join nodes. So an N-server cluster is 1 shc_cluster + (N-1) shc_node. The bootstrap node is special-cased twice
over, once as “the config lives here” and once as “the SSH-init happens
here”, which is why cluster_resource.go re-implements a whole parallel
copy of the SSH engine handoff (bootstrapSSH, adopt) that
node_resource.go already has (joinSSH, waitJoined).
TARGET: symmetric. There is an shc_node for EVERY node (all N). Exactly
one is flagged bootstrap = true and runs shc init; the rest run shc node join. shc_cluster becomes PURE CONFIG: the declarative home for the
cluster’s genesis parameters (host_domain, package default,
vault_password, system_apps, nebula, traefik_le). It no longer owns
a node, does no SSH, and emits no endpoint.
This is a clean schema break (no back-compat, per the estate doctrine,
docs/proposals/ house rule; no_backcompat_no_direct_dns). Existing
deployed clusters migrate their STATE by hand (§5) because moved{} cannot
cross resource types.
Physics that constrain the design (none of this can be erased, only relocated)
Section titled “Physics that constrain the design (none of this can be erased, only relocated)”-
Some node MUST init first. The bootstrap node runs
shc init, which mints the cluster CA + genesis (vault seal, endpoint, join token, admin surface). Join nodes runshc node join <token>and CONSUME endpoint/ca_pem/token from the bootstrap. This data dependency is irreducible. Grounding:ssh_engine.go:693buildInitArgvvs:747buildJoinArgv;internal/modules/cluster/service.go(CA mint + genesis at lifecycle priority 7, only on the init node). -
shc initgenesis flags are init-time-only.--host/--host_domain,--system-apps,--nebula,--vault-password-file,--traefik-le*are all consumed once, at genesis, on the init node (buildInitArgv,ssh_engine.go:693). There is NO daemon route to re-key the vault, change the installed system-app set, or flip nebula after init; today’sclusterResource.Updatealready REFUSES avault_passwordchange (cluster_resource.go:531) and treatshost_domain/system_apps/nebulaas “persist-only, does not re-run init”. This is the crux of the cycle resolution (§2): these fields are genesis inputs, not post-init config. -
Podman clusters are single-node only.
service.go:629-631warns “podman clusters are single-node only” when the detected runtime isModePodman. A podman bootstrap can have no join nodes. -
Runtime is orthogonal to control-plane leadership. The bootstrap node may be any runtime (
compose/swarm/podman);buildInitArgvpasses--runtimestraight through. The only coupling is the podman single-node rule (3). Bootstrap-eligibility is NOT otherwise runtime-dependent. -
shc initmints no HTTP-usable admin credential. Unchanged from today (cluster_resource.go:62-73,ssh_engine.go:82-97): the daemon’s only remote-auth scheme is a Keycloak OIDC bearer with no non-interactive bootstrap client.admin_tokenon the init node echoes the provider block’s token (null when none). Not a regression, a relocation.
§1: Exact new schemas (before/after)
Section titled “§1: Exact new schemas (before/after)”shc_node: BEFORE (join-only)
Section titled “shc_node: BEFORE (join-only)”node_resource.go:71-89. Attributes: cluster (opt nested override),
host (req, replace), package (opt {deb_url, version}), ssh (opt
{user, private_key(sens), port, host_key}), adopt (opt bool), name
(req, replace), nic (opt, replace), runtime (opt, replace),
public_address (opt), private_ip (opt). Computed: node_id, healthy,
id.
shc_node: AFTER (every node; bootstrap flag)
Section titled “shc_node: AFTER (every node; bootstrap flag)”The join surface is retained verbatim; the schema GAINS a bootstrap flag,
the genesis-config inputs the init node needs, and the cluster-cred outputs
the init node emits. All genesis inputs and all init-only outputs are
meaningful only when bootstrap = true (null/ignored otherwise;
plan-time validated; see §2).
| attribute | kind | mode | notes |
|---|---|---|---|
bootstrap | bool | Optional (default false) | NEW. true ⇒ shc init; else shc node join. RequiresReplace (init vs join is a different genesis identity). |
cluster | nested | Optional | Unchanged shape (shared.go:15 clusterResourceAttribute: endpoint/token/ca_pem/insecure/ssh). JOIN nodes point it at the bootstrap node’s outputs. Bootstrap nodes normally omit it (they are the origin). |
host | string | Required | SSH target + HTTP endpoint base. RequiresReplaceIf(!bootstrap): join keeps today’s replace-on-host; bootstrap keeps today’s shc_cluster in-place endpoint re-derive on a VM IP reshuffle (cluster_resource.go:614-622). |
package | nested {deb_url, version} | Optional | The .deb to install. Required when ssh is set (both modes). Change ⇒ in-place rolling upgrade (upgrade.go, unchanged). |
ssh | nested {user, private_key(sens), port, host_key} | Optional | THIS node’s install+init/join transport (was shc_node.ssh / shc_cluster.bootstrap.ssh, identical shape). |
adopt | bool | Optional | Self-init/self-join via cloud-init, poll over HTTP. Both modes. |
name | string | Required | --name. RequiresReplace (both modes). |
nic | string | Optional | --nic. RequiresReplace (both modes). |
runtime | string | Optional | --runtime. RequiresReplace (both modes). |
public_address | string | Optional | --public-address. In-place repair over SSH (both modes; unchanged). |
private_ip | string | Optional | plane-NIC readiness gate (ssh_engine.go:501 nodePreparedProbe). Init/join-time only. |
nebula | bool | Optional | NEW (bootstrap-only input). shc init --nebula. Ignored for join (node join has no --nebula, by design, ssh_engine.go:731). |
host_domain | string | Optional | NEW (bootstrap-only input). shc init --host. |
system_apps | string | Optional | NEW (bootstrap-only input). shc init --system-apps; SET-but-empty ("") is meaningful (“install none”). |
vault_password | string | Optional, Sensitive | NEW (bootstrap-only input). shc init --vault-password-file. Update REFUSED (§2). |
traefik_le | nested {email, staging} | Optional | NEW (bootstrap-only input). --traefik-le*. |
node_id | string | Computed | daemon node id. |
healthy | bool | Computed | healthy cluster member. |
id | string | Computed | resource id (node name). |
endpoint | string | Computed | NEW (bootstrap emits; null on join). daemon API endpoint derived from host. |
ca_pem | string | Computed | NEW (bootstrap emits; null on join). cluster global-root CA (/api/auth/ca). |
admin_token | string | Computed, Sensitive | NEW (bootstrap emits; null on join). echoes the provider block’s token (physics 5). |
join_token | string | Computed, Sensitive | NEW (bootstrap emits; null on join). a minted shc node token for the cloud-init/adopt join path. Best-effort, short-lived (see §2 staleness note). |
ready | bool | Computed | NEW (bootstrap emits; null on join). daemon healthy at last refresh. |
Genesis inputs (nebula/host_domain/system_apps/vault_password/traefik_le)
are declared directly on shc_node so a direct provider user can init a
cluster without ever declaring shc_cluster. In the modules/core path the
module wires them from shc_cluster.main.* (§3), so shc_cluster stays the
single declarative home.
shc_cluster: BEFORE (bootstrap-owning + config)
Section titled “shc_cluster: BEFORE (bootstrap-owning + config)”cluster_resource.go:81-95. Inputs: package (req), nebula,
host_domain, system_apps, vault_password(sens), traefik_le,
bootstrap (req nested: host/ssh/adopt/nic/name/runtime/public_address/private_ip).
Computed: id, endpoint, ca_pem, admin_token(sens), ready,
bootstrap_node_id.
shc_cluster: AFTER (pure config, INPUTS-ONLY)
Section titled “shc_cluster: AFTER (pure config, INPUTS-ONLY)”Everything node-shaped is removed: the whole bootstrap {} block,
endpoint, ca_pem, admin_token, ready, bootstrap_node_id. What
remains is the genesis-config record.
| attribute | kind | mode | notes |
|---|---|---|---|
package | nested {deb_url, version} | Required | Cluster-wide .deb default; every shc_node inherits it (module-wired). |
vault_password | string | Optional, Sensitive | genesis vault seal. Update REFUSED (physics 2). |
host_domain | string | Optional | genesis --host seed. |
system_apps | string | Optional | genesis --system-apps (SET-but-empty meaningful). |
nebula | bool | Optional | genesis --nebula. |
traefik_le | nested {email, staging} | Optional | genesis LE posture. |
id | string | Computed | stable id = host_domain when set, else the literal "shc-cluster". No endpoint, ever (physics/cycle, §2). |
shc_cluster emits nothing load-bearing. Its computed surface is just a
stable id. Nothing downstream references an shc_cluster output; that is
what keeps the DAG acyclic (§2).
§2: CRUD behavior + the cycle resolution
Section titled “§2: CRUD behavior + the cycle resolution”Bootstrap shc_node (bootstrap = true)
Section titled “Bootstrap shc_node (bootstrap = true)”- Create: exactly today’s
shc_clusterbootstrap path, moved ontoshc_nodeand reusing the existing engine.adopt = true⇒ poll/api/healthuntil ready, fetch CA (cluster_resource.go:646adopt).ssh {}⇒ node-prepared gate → deb install → registry pre-auth →shc initover SSH with the genesis flags (ssh_engine.go:799runClusterInitOverSSH,buildInitArgv) → readiness poll. Then EMITendpoint,ca_pem,admin_token(echo),ready,node_id, and mintjoin_tokenviashc node token(ssh_platform.go:333mintNodeTokenOverSSH) on its own socket. - Read: refresh
ready+ca_pem+node_idvia a single health/CA probe (cluster_resource.go:478Read, verbatim). A transient outage marksready=false, never removes the resource. - Update:
packagechange ⇒ in-place roll over SSH (upgrade.go).public_addresschange ⇒shc node updateover SSH.hostchange ⇒ re-derive endpoint in place (VM IP reshuffle).vault_passwordchange ⇒ REFUSED loud (cluster_resource.go:531; the vault stays sealed with the genesis password; persisting a new one would make state lie about DR). - Delete: state-only (
cluster_resource.go:633). Tearing down the VM is the substrate module’s job; the node self-leaves raft when its server dies.
Join shc_node (bootstrap = false, the default)
Section titled “Join shc_node (bootstrap = false, the default)”Byte-for-byte today’s shc_node (node_resource.go:231 Create →
joinSSH/adopt; :392 waitJoined; :548 Delete = shc node forget
with the quorum/daemon-down tolerations; node_join_recovery.go
X400021ALRCLS force-rejoin). Emits node_id/healthy/id; the
bootstrap-only computed attrs are null.
Pure-config shc_cluster
Section titled “Pure-config shc_cluster”- Create: validate (
package.deb_urlpresent), setid, write state. No SSH, no node, no endpoint: a declarative settings record. - Read: no-op (nothing external to reconcile).
- Update:
vault_passwordchange ⇒ REFUSED (mirrors the init node, the seal is immutable). All other genesis fields ⇒ persist to state and print a warning that they are genesis-only (they will not re-init a live cluster; a real re-genesis is a bootstrap-node replace). - Delete: state-only.
The cycle resolution: RECOMMENDED: Design A (bootstrap node applies genesis; shc_cluster is inputs-only)
Section titled “The cycle resolution: RECOMMENDED: Design A (bootstrap node applies genesis; shc_cluster is inputs-only)”The question the refactor forces: does shc_cluster take the endpoint as an
INPUT and apply config after init, or does the bootstrap shc_node apply
that config at init and shc_cluster stay thin? Pick A.
Design A (recommended). shc_cluster holds the genesis config as pure
inputs. The bootstrap shc_node REFERENCES those inputs and applies ALL of
them at shc init. shc_cluster performs no SSH, takes no endpoint, and
emits no endpoint. The dependency DAG:
shc_cluster.main ──(package default: every node; genesis config: bootstrap node)──▶ shc_node[bootstrap] ──(endpoint/ca_pem/admin_token/join_token/ssh)──▶ shc_node[join…] └──(package default)──────────────────────────────────────────────────────▶ shc_node[join…]shc_clusterhas NO inputs from any node and NO load-bearing outputs → it is a pure source leaf. No edge points back into it.shc_node[bootstrap]depends onshc_cluster(genesis config) and emits the creds.shc_node[join]depends onshc_node[bootstrap].- No cycle. The dreaded cycle (
shc_cluster → bootstrap node → shc_cluster) never forms becauseshc_clusterconsumes nothing from the bootstrap node and exposes no endpoint for anyone to consume back.
Why not Design B (shc_cluster applies post-init config against the
endpoint). Every field the user assigned to shc_cluster (host_domain,
system_apps, nebula, vault_password, package) is an init-time
genesis parameter with NO post-init apply path (physics 2; today’s Update
already refuses/ignores them). So a Design-B shc_cluster would have nothing
legitimate to apply post-init, yet would need an shc_cluster → bootstrap node edge (to read the endpoint) for no benefit, and the genuinely
post-init-mutable cluster config (dns.provider, acme.email, connections,
mesh, LB ports) already lives in shc_config/shc_connection/shc_mesh/
shc_stack_ports, which reference the bootstrap node’s endpoint directly.
B adds an edge and a temptation to “apply” un-appliable config; A does not.
join_token staleness note. The bootstrap node’s join_token is a
minted shc node token (default TTL 1h). It is emitted for the
cloud-init/adopt consumers (data.shc_cloudinit, data.shc_enrollment_token).
The modules/core SSH path does NOT consume it; the SSH join mints a FRESH
token per node over the bootstrap socket at join time (node_resource.go:287
mintNodeTokenOverSSH), which is correct under long applies. This split is
documented so a stale stored token is never load-bearing. Open decision for
sign-off: emit join_token at all (per the refactor brief) vs. leave
enrollment entirely to data.shc_enrollment_token (a data source that
re-reads each plan). Recommendation: emit it best-effort, document the
staleness, keep the SSH path minting fresh.
§3: The modules/core rewrite
Section titled “§3: The modules/core rewrite”terraform/modules/core/variables.tf and the module "core" call sites are
UNCHANGED (var.nodes / var.ssh / var.bootstrap / var.topology
keep their shapes, confirmed against hetzner/main.tf:309-324 and
mixed-proxmox-hetzner/main.tf’s direct module "core" call). Only
main.tf’s bootstrap layer and two lines of outputs.tf change.
core/outputs.tf: cluster_endpoint / cluster_ca_pem now read the
bootstrap node’s outputs instead of shc_cluster.main[0]:
output "cluster_endpoint" { value = local.bootstrap_set ? shc_node.nodes[local.bootstrap_node.name].endpoint : null}output "cluster_ca_pem" { value = local.bootstrap_set ? shc_node.nodes[local.bootstrap_node.name].ca_pem : null}core/main.tf LAYER bootstrap (replaces cluster_resource.go-era
shc_cluster.main + shc_node.workers):
locals { bootstrap_set = try(var.bootstrap.host, null) != null || try(var.bootstrap.package.deb_url, null) != null bootstrap_node = var.nodes[0] # ssh material resolution unchanged (var.ssh.private_key | file(private_key_path)) ssh_private_key = var.ssh == null ? null : ( var.ssh.private_key != null ? var.ssh.private_key : file(pathexpand(var.ssh.private_key_path)) ) # platformSSH = the BOOTSTRAP node's admin-CLI SSH, wired onto every join # node's cluster.ssh + every topology resource (UNCHANGED shape). platform_ssh = local.bootstrap_set && var.ssh != null ? { host = local.bootstrap_node.public_ipv4 user = var.ssh.user private_key = local.ssh_private_key port = var.ssh.port host_key = var.ssh.host_key } : null
# cluster_ref now points at the BOOTSTRAP NODE's outputs, not shc_cluster. cluster_ref = local.bootstrap_set ? { endpoint = shc_node.nodes[local.bootstrap_node.name].endpoint token = shc_node.nodes[local.bootstrap_node.name].admin_token ca_pem = shc_node.nodes[local.bootstrap_node.name].ca_pem ssh = local.platform_ssh } : null}
# Podman single-node guard (physics 3): a podman node cannot have peers.check "podman_single_node" { assert { condition = !local.bootstrap_set || local.bootstrap_node.runtime != "podman" || length(var.nodes) == 1 error_message = "podman clusters are single-node only (internal/modules/cluster/service.go:629); a podman bootstrap node cannot have join nodes." }}
# PURE-CONFIG cluster: the declarative genesis home. No node, no ssh.resource "shc_cluster" "main" { count = local.bootstrap_set ? 1 : 0
package = var.bootstrap.package host_domain = var.bootstrap.host != "" ? var.bootstrap.host : null nebula = var.bootstrap.nebula system_apps = var.bootstrap.system_apps vault_password = sensitive(var.bootstrap.vault_password)}
# EVERY node: bootstrap flag on nodes[0].resource "shc_node" "nodes" { for_each = local.bootstrap_set ? { for n in var.nodes : n.name => n } : {}
bootstrap = each.value.name == local.bootstrap_node.name
# Join nodes reference the bootstrap node's creds; the bootstrap node omits # cluster (it is the origin). cluster.ssh (platform_ssh) is what the join # node's token-mint + membership-poll ride (ssh_platform.go). cluster = each.value.name == local.bootstrap_node.name ? null : local.cluster_ref
# Genesis config on the bootstrap node ONLY, sourced from shc_cluster.main. host_domain = each.value.name == local.bootstrap_node.name ? shc_cluster.main[0].host_domain : null system_apps = each.value.name == local.bootstrap_node.name ? shc_cluster.main[0].system_apps : null nebula = each.value.name == local.bootstrap_node.name ? shc_cluster.main[0].nebula : null vault_password = each.value.name == local.bootstrap_node.name ? sensitive(shc_cluster.main[0].vault_password) : null
host = each.value.public_ipv4 adopt = false name = each.value.name nic = each.value.nic runtime = each.value.runtime public_address = try(each.value.public_address, null) private_ip = try(each.value.private_ip, null)
package = shc_cluster.main[0].package # cluster-wide deb default, all nodes ssh = { user = var.ssh.user private_key = local.ssh_private_key port = var.ssh.port host_key = var.ssh.host_key }}The LAYER topology block (main.tf:154-306) is unchanged EXCEPT
depends_on = [shc_node.workers] becomes depends_on = [shc_node.nodes] on
every topology resource, and local.cluster_ref already resolves to the
bootstrap node’s outputs, so shc_connection/shc_config/shc_mesh/
shc_stack_ports need no other edit.
§4: Degenerate cases
Section titled “§4: Degenerate cases”- Single node (bootstrap only), N=1.
for_eachovervar.nodesyields one node withbootstrap = true; no join nodes.shc_cluster.mainpure config. Theall_nodeslist from the front doors already supports N=1 (nodesvalidation:length > 0,core/variables.tf:41). Works unchanged. - Podman (always single-node). The
check "podman_single_node"block fails the plan if a podman bootstrap has peers. A podman bootstrap node inits fine (buildInitArgvpasses--runtime podman;service.go:650handles podman NIC-optional). Runtime stays orthogonal otherwise (physics 4). adoptpath.bootstrap = true, adopt = true⇒ the node self-inits via its cloud-initdata.shc_cloudinit(role=cluster) and the resource polls/api/health, fetches CA, emits creds (today’sclusterResource.adopt, relocated). Join nodesadopt = truepoll membership. The adopt path is the one exercised by the existing acc tests and byprovider/examples/{hetzner,aws}; it stays first-class.
§5: State migration (moved{} can’t cross types)
Section titled “§5: State migration (moved{} can’t cross types)”An existing old-model cluster in state is shc_cluster.main (owns node-1 +
config) + shc_node.workers["…"] (joins). moved{} cannot lift
shc_cluster.main → shc_node (type change), so this is manual state
surgery. Both Deletes are state-only and both shc_node matchers are
identity-first, so nothing below touches the live cluster.
Path 1: surgical in-place (recommended for live clusters)
Section titled “Path 1: surgical in-place (recommended for live clusters)”# 0. Snapshot state first.terraform state pull > pre-migrate.tfstate
# 1. Drop the OLD bootstrap-owning shc_cluster from state (Delete is# state-only; the real node/cluster is untouched). Its schema is about# to change to pure-config, so the old state must go, not be refreshed.terraform state rm 'module.core.shc_cluster.main[0]'
# 2. Rewrite config to the new model (new pure-config shc_cluster +# shc_node.nodes for-each ALL nodes). Add same-type moved{} for the join# nodes whose address changes shc_node.workers -> shc_node.nodes:# moved { from = module.core.shc_node.workers to = module.core.shc_node.nodes }# (same type, ALLOWED. Terraform re-keys every join instance in place.)
# 3. IMPORT the bootstrap node into the new symmetric shc_node (adopt# semantics; Read reconciles membership, never re-inits):terraform import 'module.core.shc_node.nodes["node-1"]' node-1
# 4. Verify: NO destroy/replace of any node, NO re-init, NO forget.terraform plan # expect: shc_cluster.main create (no-op record); nodes in-place/no-opAfter step 3 the imported bootstrap node has name/id seeded; the first
plan/apply derives endpoint from config host and refreshes
ca_pem/ready via Read. admin_token re-echoes the provider token;
join_token re-mints best-effort. The new pure-config shc_cluster.main is
created fresh (no-op Create). Estates driving modules/core through a front
door do this ONCE per state (the addresses are module.core.…).
Path 2: rebuild (non-prod / where re-genesis is acceptable)
Section titled “Path 2: rebuild (non-prod / where re-genesis is acceptable)”terraform destroy the platform layer (or state rm all shc_* and let
the VMs stay) then re-apply on the new model from empty. Simpler, but
re-runs shc init (new CA, new genesis), only for throwaway clusters.
No provider UpgradeState upgrader is written. A within-type v0→v1
upgrader cannot turn a node-owning shc_cluster into a pure-config one
(the node is leaving the resource entirely), and the cross-type move is
inexpressible in schema versioning, hence the documented surgery.
§6: Test + docs changes
Section titled “§6: Test + docs changes”Provider Go tests:
cluster_resource_test.go: rewrite. DropTestAccClusterResource_Adopt,_SSHBootstrap,_BootstrapHostUpdate,_MissingBootstrapMechanism,_PEMWhitespaceNoOpPlan(all assert the bootstrap-owning shape). Replace with a pure-config test: createshc_clusterwithpackage+ genesis fields, assertid, assertvault_passwordupdate is refused, assert NO endpoint/ca_pem/bootstrap attrs exist.node_resource_test.go: extend. Keep_Adopt,_SSHJoin,_MissingJoinMechanism,_PEMWhitespaceNoOpPlan(join path). ADDTestAccNodeResource_Bootstrap*: the init path (adopt + SSH), asserting the emittedendpoint/ca_pem/admin_token/join_token/readyand that theshc initargv (notnode join) hits the fake SSH server. Move the_SSHBootstrapinit-argv assertions here fromcluster_resource_test.go.provider_schema_test.go:30: update the offline schema assertions for the newshc_nodeattribute set (bootstrap + genesis inputs + init-only outputs) and the trimmedshc_cluster.mock_test.go/bootstrap_data_sources_test.go: check forshc_clusterendpoint/adopt fixtures; repoint toshc_node[bootstrap].
Module + acceptance:
terraform/modules/core/main.tf(rewrite §3),outputs.tf(2 lines).tests/hetzner/terraform/*: config unchanged (goes through the front door); it validates the new core wiring end-to-end on a live 4-node LB cluster. Re-runmake test/hetzneras the standing gate.
Example configs (direct-resource roots only):
terraform/provider/examples/hetzner/main.tfand.../aws/main.tf: rewrite.resource "shc_cluster" "main"loses itsbootstrap {}block and becomes pure config; a newresource "shc_node" "bootstrap"(bootstrap = true, host = node[0]) is added; everycluster = { endpoint = shc_cluster.main.endpoint, token = shc_cluster.main.admin_token, ca_pem = shc_cluster.main.ca_pem }reference (≈12 per file) repoints toshc_node.bootstrap.{endpoint,admin_token,ca_pem}. Same for thejoindata.shc_cloudinitcluster block.terraform/provider/examples/provider/provider.tf: doc comment mentionscluster = shc_cluster.main; update toshc_node.bootstrap.terraform/examples/*(per-cloud + mixed): no change: they consume the front-door /module "core"public interface, which is unchanged.
Docs:
terraform/modules/core/README.mdand eachterraform/modules/shc/*/README.mdthat narrates “shc_cluster on nodes[0] / shc_node join nodes[1:]”; reword to “shc_node per node, bootstrap flag on nodes[0]; shc_cluster pure config”.- Provider resource docs (generated from the schema
MarkdownDescriptions): regenerate.
§7: Clean-break call-outs
Section titled “§7: Clean-break call-outs”- What breaks for direct provider consumers. The
shc_cluster.bootstrap {}block is gone;shc_cluster.{endpoint,ca_pem,admin_token,ready,bootstrap_node_id}outputs are gone. Anything referencingshc_cluster.main.endpoint(etc.) must repoint toshc_node.<bootstrap>.endpoint. The bootstrap node is now a first-classshc_nodewithbootstrap = true. State needs the §5 surgery. - What does NOT break. The front-door module public interface is
unchanged:
module "shc/hetzner"(and every peer cloud) and the directmodule "core"call inmixed-proxmox-hetznerkeep the samenode_groups/nodes/ssh/bootstrap/topologyvariables and the samecluster_endpoint/cluster_ca_pemoutputs. Estates driving through a front door do not churn their configs at all, only their STATE migrates once (§5), and only if they manage the platform in the same root. The joinshc_node’s day-2 surface (node join, forget, in-place package roll, public-address repair, X400021ALRCLS recovery) is byte-for-byte preserved.
§8: Effort estimate + recommended order
Section titled “§8: Effort estimate + recommended order”| area | files | effort | notes |
|---|---|---|---|
Provider Go: shc_node | node_resource.go, node_join_recovery.go (unchanged) | M-L | Add bootstrap branch to Create; fold in bootstrapSSH/adopt from cluster_resource; add genesis inputs + init-only computed outputs; RequiresReplaceIf(!bootstrap) on host; conditional plan preserve. Reuses ssh_engine.go/ssh_platform.go verbatim (no engine changes). |
Provider Go: shc_cluster | cluster_resource.go | S-M | Mostly DELETION → pure-config record. Keep the vault-refuse Update guard. |
| Provider Go: wiring | provider.go (unchanged), client.go (doc), shared.go (doc) | S | No new resource registration; clusterModel shape unchanged. |
| Core module | core/main.tf, core/outputs.tf | M | §3 rewrite + podman check + 2 output lines. variables.tf unchanged. |
| Tests | cluster_resource_test.go, node_resource_test.go, provider_schema_test.go, mock fixtures | M | Rewrite cluster tests, extend node tests, schema assertions. |
| Examples + docs | provider/examples/{hetzner,aws}/main.tf, provider/examples/provider, module READMEs, generated docs | S-M | Mechanical repoint of ≈12 refs/file + narration rewording. |
| State migration | doc + moved{} block in core | S | §5 recipe; one moved{} for the join address change. |
Recommended implementation order (each step green before the next):
- Provider Go first, TDD. (a) Add
bootstrap+ genesis inputs + init-only outputs toshc_node, portbootstrapSSH/adoptinto the Create bootstrap branch, write the bootstrap-node acc tests. (b) Stripshc_clusterto pure config, rewrite its tests. (c) Updateprovider_schema_test.go. Ship the provider as a sha-tarball. - Core module against the new provider: rewrite
main.tfbootstrap layer +outputs.tf, add the podmancheckand the join-nodemoved{}. Validate withterraform validate+ aplanontests/hetzner/terraform. - Examples + docs: repoint the two direct-resource roots, reword READMEs, regenerate provider docs.
- Live gate:
make test/hetzner(4-node LB cluster from empty): proves the symmetric model end-to-end, including the podman guard on a single-node variant. - Migration doc: land §5 in the module README; dry-run Path 1 against a throwaway old-model state before publishing.
Open decisions for human sign-off
Section titled “Open decisions for human sign-off”- Emit
join_tokenat all? (§2 staleness note.) Recommend: yes, best-effort + documented; SSH path keeps minting fresh. hoston the bootstrap node: replace or in-place? Recommend: in-place re-derive (RequiresReplaceIf(!bootstrap)) to preserve today’sshc_clusterVM-IP-reshuffle behavior; alternative is uniform RequiresReplace (simpler, but a bootstrap IP change would re-genesis the whole cluster).- Keep
shc_clusterat all for direct provider users? It is optional in Design A (the bootstrapshc_nodecan carry genesis config itself). Keep it as the declarative single-config home the module references, but a direct user could skip it. Confirm we want the (small) input duplication.