Module library
Two reusable modules build on the shc provider:
core: the platform-agnostic layer. Takes a node list (from any substrate) plus bootstrap/topology config and creates everyshc_*resource. No cloud provider inrequired_providers.shc/<cloud>: 14 per-substrate front doors (aws, azure, gcp, hetzner, proxmox, digitalocean, linode, scaleway, vultr, exoscale, alibaba, cloudstack, openstack, hostinger). Each builds the cloud infra (instances, network, firewall, keys), assembles thenodeslist, and callscore.hostingeris the outlier: the substrate has no network, firewall or volume tier to build at all, so it builds only nodes + keys + a prep script.
Reference a published module by its selfhostedcloud.org tarball URL. The
version lives in the URL, with no version argument. Use a local relative
path when developing in-tree:
module "shc" { source = "https://selfhostedcloud.org/terraform/0.1/modules/0.1.30/shc-hetzner-0.1.30.tgz" # published # source = "../../modules/shc/hetzner" # in-tree # ...}The state file is a secret store
Section titled “The state file is a secret store”Read access to the state backend is equivalent to holding the estate’s vault password. Everything else in this section is detail hanging off that one sentence.
bootstrap.vault_password is written in plaintext into Terraform
state. The modules mark it sensitive (sensitive(...) at the call
site, and Sensitive: true on the provider’s own schema attribute), and
that mark redacts the value from plan and apply output only. It is
not encryption. Terraform has never encrypted state on account of a
sensitive mark, and a jq one-liner reads the password back out of
terraform.tfstate.
This is accepted and is not being fixed. Ruled by the owner on 2026-08-16: state is treated as a secret store and documented as one, rather than worked around with write-only variables, a state-encryption layer, password rotation, or cloud-init generation. If you came here looking for the flag that keeps it out of state, there isn’t one and there isn’t going to be one.
What that obliges you to do
Section titled “What that obliges you to do”Because the password is in state, the state backend’s access list is the control protecting the vault, not an implementation detail of how your team runs Terraform. Manage it as a vault ACL:
- Grant read on the backend to exactly the people you would hand the vault password to, and review that list on the cadence you review vault access.
- Use a remote backend with encryption at rest and per-principal
access control (S3 + SSE-KMS, GCS + CMEK, or equivalent) for
anything past a scratch estate. A local
terraform.tfstate(plus its.backupsibling and any.terraform/copy) is an unencrypted secret sitting on an operator’s disk. - Never commit state, and never let it into a repo, a build artifact, or a CI cache whose readers are a wider set than the vault password’s readers.
- Remember that rotating the vault password does not scrub the old one: prior state versions still carry it, so backend versioning and backup retention set how long the old secret stays readable.
- The same logic covers state’s other secrets: the cluster SSH private
key, the restic
backup_password, DNS and volume credentials. The vault password gets its own section because it unlocks everything else on the estate.
Which modules put it there
Section titled “Which modules put it there”Every shc/<cloud> front door accepts bootstrap.vault_password and
hands it to core, which wires it to shc_cluster.main.vault_password.
That is all 14 front doors, not a subset:
shc/alibaba | shc/aws | shc/azure |
shc/cloudstack | shc/digitalocean | shc/exoscale |
shc/gcp | shc/hetzner | shc/hostinger |
shc/linode | shc/openstack | shc/proxmox |
shc/scaleway | shc/vultr |
…plus core itself, which is where the value actually reaches a
resource. A root module that skips the front doors and calls core
directly (the split examples/mixed-proxmox-hetzner pattern) is in
scope for exactly the same reason.
One place it is wider than state
Section titled “One place it is wider than state”The shc_cloudinit data source embeds the vault password verbatim in
the rendered user_data, which means the cloud provider’s
instance-metadata service holds a copy too. None of the 14 front doors
uses it (they bootstrap over SSH), but a root module that does inherits
that extra exposure on top of the state exposure. The attribute carries
its own warning in the provider reference.
The core module
Section titled “The core module”source = ".../modules/core" (or the core-shc-<version>.tgz tarball).
Turns a node list ANY substrate already provisioned into a running cluster.
The node model is symmetric: every node is an shc_node:
shc_node.bootstrap (on nodes[0], runs shc init and emits the cluster
creds) plus one shc_node.workers per remaining node (join), alongside a
pure-config shc_cluster genesis record and the topology resources
(shc_connection / shc_config / shc_stack_ports). Everything
applies over the provider’s SSH transport (no bearer token, no
driver.sh). required_providers is shc only.
nodes[0] is always the bootstrap node; order the list yourself (the front
doors put the bootstrap node first: the first node of the alphabetically-first
node_groups key).
Two gated layers
Section titled “Two gated layers”| Layer | Gate | What it creates |
|---|---|---|
| bootstrap | bootstrap != null | the pure-config shc_cluster, shc_node.bootstrap (SSH init) on nodes[0], one shc_node.workers (SSH join) per remaining node. (A podman bootstrap node must be single-node; a check block enforces it.) |
| topology | topology != null (requires bootstrap) | dispatched by topology.kind: "lan" → optional internal DNS shc_connection/shc_config; "wan" → mesh0 with no topology resources; "lb" → proxy shc_connection + dns.provider/ACME + optional volume config + shc_stack_ports (traefik LB attach). |
The shc_mesh data source reads mesh0 status. The core module does not
instantiate it because no output or check consumes that status.
Inputs
Section titled “Inputs”| Name | Type | Default | Required | Description |
|---|---|---|---|---|
nodes | list(object) | none | yes | Every node, bootstrap-first. Each: {name, management?, internal?, public?, runtime, group, index, nic, location?, provider?, control_plane?, host_key?, jump?}. host_key is the node’s SSH host key (a known_hosts line), lowered onto shc_node.ssh.host_key and the node’s cluster_ssh_hosts entry; it falls back to ssh.host_key, and a node with neither fails the plan unless ssh.insecure_ignore_host_key = true. jump = { host, port?, user?, host_key } is the one host terraform reaches that node through, lowered onto shc_node.ssh.jump; it uses the ssh key, so nodes carries no private key, and its host_key is required the same way. A node with a jump is left out of cluster_ssh_hosts, because the platform transport dials those hosts directly, so the bootstrap node cannot have one. control_plane is lowered onto shc_node.control_plane (--control-plane): true puts the node in the control plane, null sends nothing. location/provider are the node facts lowered onto shc_node.location/cloud (null = the node detects them; modules/shc/hetzner stamps the server’s location and hetzner); the three address roles are {ipv4, ipv6, fqdn} containers carrying EXACTLY ONE member each; an absent role is null (internal is null on a public-plane cluster). The pre-M10 scalars (public_ipv4/private_ip/public_address) are tombstoned: writing one fails the plan with the rename spelled out. |
ssh | object | null | with bootstrap | The install/join/admin credential: one key for every node. Fields: user (default admin), private_key, private_key_path, port, host_key, insecure_ignore_host_key (default false). Set exactly ONE of private_key (material) or private_key_path (local file). host_key is the host key of every node that states none of its own. insecure_ignore_host_key = true lets a node or jump host with no pin through unchecked, for a first contact in a lab or VMs whose keys nothing here knows; a node with its pins is still checked, and so is its cluster_ssh_hosts entry. |
ssh_address | string | "public" | no | WHICH ADDRESS PLANE every SSH channel this module opens is dialed on: shc_node.management (install/init/join, and the base of the derived daemon endpoint), the platform-resource transport, and the cluster_ssh_hosts output. "public" reads nodes[*].management, "private" reads nodes[*].internal. A plane on which NO node has an address fails the plan rather than yielding an empty host list. "fabric" is refused: a node’s fabric /24 is allocated by the raft leader at enrollment, so it does not exist until after the very init/join this channel carries. Changing this on a live estate REPLACES every join node. |
bootstrap | object | null | no | Bootstrap config (see below). null skips the bootstrap layer (nodes provisioned but no shc_* resource touched). |
topology | object | null | no | Platform/topology config, dispatched by kind (see below). Requires bootstrap != null. |
bootstrap_node_name | string | null | no | The nodes[*].name that runs shc init, who holds the genesis ROLE. Optional: null resolves to nodes[0].name, deterministically and by position alone (first node in, first node inits). Set it to state the role instead of deriving it: nodes is ordered by node-group key, so deleting the group holding the bootstrap slides position 0 onto an already-joined node, and a name makes that reordering inert. Re-pointing it is supported, and is how a bootstrap is retired: name another member and apply. bootstrap is a create-time serializer read once to pick init-vs-join, so a genesis relabel applies IN PLACE (nameRequiresReplaceIfJoin forces replacement on join nodes only; the plan-time refusal is deleted, rulings M8 + M11). A pinned name that vanishes from nodes degrades to nodes[0] and plans. The destructive legs are refused at APPLY by the daemon, which reads live membership: voter floor (M9), occupancy (M7), vault cold-start X409906VLTCSH (M8). The pre-genesis refusal that stops a from-empty apply minting a second cluster beside a live estate is raised by the PROVIDER, before it ever dials the daemon, and is documented with the resource it guards; see the provider reference. |
on_destroy | string | null | no | The whole-estate teardown consent (ruling M7). Handed verbatim to EVERY shc_node this module owns, bootstrap included; that is what “set once per node” means. null (the default) keeps the refusal: a destroy of a node deployment rows still name hard-fails, naming the stacks. "force" pre-consents to orphaning them. Validated to null|"force" here, so a typo fails the plan instead of reading as absent at every node below. Read from STATE at destroy time, so tofu apply it BEFORE tofu destroy. |
license_dns_token | string | null | no | The vendor-signed licence token for the estate’s serving domain, the shclic.v1.… value from shc license mint --domain <host> --dns. The estate reads its licence from its own zone at _shc-license.<host>, so the apply that builds the cluster also produces the record that licenses it: this module returns it on the license_dns_record output and does not create it, and installs the token through shc_license. Set this or bootstrap.license, not both. |
bootstrap object:
| Field | Type | Default | Description |
|---|---|---|---|
package | object {version, repository?} | none (required) | The SHC package; flows to shc_cluster and every worker. version is the shc version every node installs by apt from the Based repository (https://apt.basedlinux.com/deb/based, suite d13), which the provider adds with Based’s key and a preference taking shc alone from it, then holds so no apt upgrade moves it. Changing version on a live cluster does an in-place rolling upgrade, one node at a time. repository is for UNRELEASED builds only: one more flat apt repository holding a build Based does not carry (scripts/apt-flat-repo.sh writes one). It is UNSIGNED, so every node trusts what that URL serves; leave it unset on an estate. |
vault_password | string | none (required) | Seals the system vault; the SSH engine hard-errors when empty. Marked sensitive, which redacts it from plan output but does not keep it out of state: it is stored there in plaintext; see The state file is a secret store. Changing it on a live cluster rotates the vault in place on the bootstrap node; see the provider reference. No leading/trailing whitespace (shc init trims what it reads). |
fabric | string | "" | The cluster’s cross-node data plane (shc init --fabric): "shc" (routed WireGuard on shc0, UDP 4243) or "none" (only where the runtime cannot attach the fabric: apple). "" omits the flag. The daemon then selects shc where the runtime can attach it. |
address_block | string | "" | The cluster’s address block (shc init --address-block; daemon default 10.64.0.0/16). Every SHC range is carved from it: deployment networks, the fabric, mesh addresses and service VIPs, so it applies in every fabric mode. A /8 to a /16, clear of 172.16.0.0/12 and of every network a node is on. Fixed at genesis; shc cluster block add adds room later. See the address block. |
host | string | "" | The public domain seed (shc init --ingress-host), NOT an address. |
acme | object | none | Named ACME providers + a cluster default: providers (map of {directory, email, eab_kid, eab_hmac}), default, email. Blank directory = Let’s Encrypt production. |
modules | map(object) | none | System-app selection + per-app overrides ({host?, base_path?, vars?}). Key set = install selection: unset = daemon default, {} = traefik alone, populated = those plus traefik (nodes join through it on 443). |
connections | map(object) | none | Connections made by shc init --connection-file before the platform stacks install, keyed by name, each {type, tenant?, scope?, credentials?, zones?} like shc_connection. Each is also declared as shc_connection.bootstrap[<name>], which owns it once the cluster runs. |
storage | string | "" | The volume connection the platform stacks’ durable volumes go on (shc init --storage), also written as the shc_config.storage row. Set this or topology.volume_provider, not both. |
topology object:
| Field | Type | Default | Description |
|---|---|---|---|
kind | string | none (required) | "lan", "wan", or "lb". |
dns | object | none | {name, type, zones?, credentials?}. Required when kind == "lb" (type becomes the LB connection’s provider_type); optional for “lan”; unused for “wan”. Give the LB a project-unique name (the shared VIP is shc-<name>). |
public_address | string | "" | Cluster public entrypoint address (lan/lb DNS). |
lb_ports | map(object) | none | For “lb”: extra LB port attaches, keyed by "external[/udp]", value {container?, service?} (service default traefik). |
volume_provider | object | none | For “lb”: {provider, config?}, the block-volume storage provider config. |
volume_secrets | map(string) | {} | For “lb”: secret keys for the volume provider. |
Outputs
Section titled “Outputs”| Name | Description |
|---|---|
cluster_endpoint | The daemon API endpoint. null unless bootstrap != null. |
cluster_ca_pem | The cluster’s global-root CA PEM. null unless bootstrap != null. |
module "core" { source = "../../modules/core"
nodes = [ { name = "n1", management = { ipv4 = "198.51.100.10" }, internal = null, public = null, runtime = "docker", group = "control", index = 0, nic = "eth0", host_key = "ssh-ed25519 AAAA..." }, { name = "n2", management = { ipv4 = "198.51.100.11" }, internal = null, public = null, runtime = "docker", group = "control", index = 1, nic = "eth0", host_key = "ssh-ed25519 AAAA..." }, ]
ssh = { user = "admin", private_key_path = "~/.ssh/id_ed25519" }
bootstrap = { package = { version = "0.1.2" } vault_password = var.vault_pw host = "cloud.example.com" }
topology = { kind = "lb" dns = { name = "hetzner", type = "hetzner", zones = ["example.com"], credentials = { token = var.hcloud_token } } acme = { } # ACME is configured via bootstrap.acme }}Real deployments usually drive core through a substrate front door rather
than calling it directly. Call it directly for the mixed-substrate shape:
call each front door with manage_platform = false, concat() their nodes
outputs, and call one core at the root over the combined list (see the
mixed-proxmox-hetzner example).
Ownership boundary.
corenever manages DNS records for the cluster’s own public hostname, and the mesh always designates the current raft leader as the bootstrap node, so bootstrap on the node you want to be leader.
The shc/<cloud> front doors
Section titled “The shc/<cloud> front doors”source = ".../modules/shc/<cloud>": one module per substrate. Each creates
the cloud’s infra (instances, network/VPC, firewall/security groups, SSH
keys), builds the platform-agnostic nodes list, and calls core (unless
manage_platform = false, infra-only). They share a common contract;
the infra-shaping inputs differ per cloud (instance sizing, region/zone
naming, root volume, IP assignment).
Documented below in full for shc/hetzner (the canonical front door); the
cross-substrate variance table lists what changes
elsewhere.
shc/hetzner inputs
Section titled “shc/hetzner inputs”| Name | Type | Default | Required | Description |
|---|---|---|---|---|
cluster_name | string | none | yes | Cluster name; every node is "<role><NN>.<cluster_name>"; also prefixes and labels every hcloud resource. |
region | string | "fsn1" | no | Default Hetzner location. Per-group override: node_groups.<key>.region. |
generation | string | null | no | BLUE/GREEN BUILD MARKER for this set of iron ("g2", "g3", …), the INFRASTRUCTURE identity, kept apart from cluster_name, which is the licence-bound SERVICE identity. Set on its own it is INVENTORY ONLY: it stamps generation=<g> onto every resource this module labels and moves NO name, which is how a standing estate is grandfathered. Pair with generation_in_names for the dotted naming. null renders labels and names BYTE-IDENTICAL to the pre-generation module, so an existing root plans clean. Validated as g<positive-int> so it is a legal single DNS label. IMMUTABLE once applied (terraform_data.generation_lock): changing it fails the plan instead of planning an estate rebuild. Set the matching shc config set cluster.generation <g> --scope global so DNS ownership can tell two generations apart (ce X403047DNSGEN). |
generation_in_names | bool | false | no | Make generation its own DNS label in every module-derived NAME: nodes become <role><NN>.<generation>.<cluster_name>, and the placement group, SSH keys, network and firewalls carry <generation>.<cluster_name>. FRESH ROOTS ONLY, AND IMMUTABLE: flipping it on a root that has already applied renames every node, key, firewall and placement group (destroy + recreate of the whole estate) while the licence-bound service identity stays put, so the module REFUSES it at plan time. ★ The generation NEVER reaches a served host: application hostnames, the control-plane host, the auth host and anything the licence binds stay un-generationed forever; this flag governs node and cloud-resource names only. Requires generation to be set. |
image | string | "debian-13" | no | Default OS image (keep a Debian image). Per-group override available. |
create_ssh_key | bool | false | no | Mint the cluster keypair IN Terraform (ED25519) instead of bringing one; the private key feeds core’s SSH transport and lands in state (read it via ssh_private_key). Flipping on an existing cluster REPLACES every node. |
ssh_public_key | string | null | no* | SSH public key. create_ssh_key = false: required (BYO). create_ssh_key = true: optional break-glass key. |
extra_authorized_keys | list(string) | [] | no | Extra public keys appended to the admin user via cloud-init. Create-time on hcloud_server: changing later REPLACES servers. |
nic_name | string | null | no | Override the auto-derived plane NIC hint (private ? "enp7s0" : "eth0"). Per-group override available. |
labels | map(string) | {} | no | Extra labels merged onto every hcloud resource. |
estate | string | null | no | Org-estate marker stamped as estate=<name> on every resource. |
ssh | object | null | with bootstrap | Passed through to core (install+join + bootstrap-node platform transport). Fields: user (default admin), private_key, private_key_path, port. Ignored when create_ssh_key = true. Each node’s SSH host key is minted here, installed by cloud-init and pinned through its nodes entry, so there is no host key input and no opt-out. |
ssh_address | string | "public" | no | WHICH ADDRESS PLANE the SSH control channel rides: cluster_ssh_hosts, and inside core the install/join and platform transports. "public" (each node’s public IPv4) or "private" (its cluster-plane address). "private" is never the default: whoever runs tofu has to reach the plane, and re-pointing a live estate’s control channel must be asked for. Changing it on a live estate REPLACES every join node (shc_node.management forces replacement on a joiner, on the RESOLVED address, managementRequiresReplaceIfJoin). "fabric" is refused: the fabric address is allocated at enrollment, after the init/join this channel carries. |
node_groups | map(object) | none | yes | Node pools → one cluster. Per entry: count, server_type, runtime (docker/podman), and optional control_plane (every node of the group joins with --control-plane; three members are three voters), node_names, region, image, nic_name, host_offset, firewall ({public_ports}). Bootstrap node = index 0 of the alphabetically-first key. |
networking | object | {} | no | ONE shared private network: private (default true), ip_range (default 10.10.0.0/16), subnet (set = create mode; unset = link an existing network), zone (default eu-central). Sizing guidance (why the /24 default is right up to the provider’s own ~100-node cap, and what actually forces a change) is Sizing the private network. |
firewall | object | {} | no | GLOBAL firewall posture, layered under each node_groups entry’s own firewall.public_ports (this one’s public_ports is UNIONed into every group; ssh/22 + icmp are always open). inter_node governs the one cluster-sourced firewall and stays global: "plane" (only the cluster-plane ports, sourced from the nodes’ own public IPs: TCP 443, where a joining node enrols, TCP 4001 to 4004 and the mesh UDP ports), "open" (all tcp/udp + ESP, an explicit, deliberately alarming escape hatch) or "none". Leave inter_node UNSET: absence DERIVES the posture from networking you already declared (private = true ⇒ none, public-IP plane ⇒ plane). There is no "auto": it is a hard error telling you to delete the line. inter_node_extra_sources adds peer CIDRs a cross-substrate cluster owns but this module cannot see. Hetzner firewalls filter inbound PUBLIC traffic only, so none of this bites on a private-network plane. |
bootstrap_node_name | string | null | no | The name of the node that holds the genesis role (shc init). Optional: null derives it positionally: first node of the alphabetically-first node_groups key. Name it to state the role instead, which makes a group reshuffle inert; see the core row for the full contract, including that re-pointing it is supported and relabels in place. Shrinking a group by editing its count still churns fewer resources than deleting the group that holds the bootstrap. |
placement_group | bool | true | no | Own an hcloud “spread” placement group (anti-affinity) named cluster_name. |
bootstrap | object | null | no | Forwarded to core unchanged (see the core table). One hcloud-side effect: any bootstrap.fabric but "none", unset included, ALSO opens UDP 4243 (the fabric’s WireGuard listener) node-to-node on the plane firewall, scoped to the cluster’s own node addresses, never 0.0.0.0/0. |
topology | object | null | no | Forwarded to core unchanged. Requires bootstrap != null. |
manage_platform | bool | true | no | true: call core (full front door). false: INFRA-ONLY: build servers/network/firewall, expose nodes, touch no shc_* resource (mixed-cluster split). |
protected | bool | false | no | Delete/termination protection for the estate’s iron. Flip true once live; tofu destroy fails until reverted. (No-op on some clouds.) |
on_destroy | string | null | no | Forwarded to core unchanged, which hands it to every node (see the core table). The estate’s ONE place to state ruling M7’s destroy consent: null refuses the destroy of any node deployment rows still name; "force" pre-consents to orphaning them. Declared identically by every cloud front door: it is part of the common contract, not a per-substrate input. Orthogonal to protected: that one guards the iron, this one guards the stacks running on it. |
license_dns_token | string | null | no | Forwarded to core unchanged (see the core table): the vendor-signed licence token for bootstrap.host. Publish the license_dns_record output with whichever provider owns the zone; the estate then licenses itself from _shc-license.<host>. |
routes | list(object) | [] | no | STATIC RETURN ROUTES every node installs on its LAN NIC: the “router peer on the LAN” shape (pfSense, OPNsense, VyOS). Networks BEHIND that peer can reach a node but never get a reply: the answer has no matching route, follows the DEFAULT route out the PUBLIC NIC and dies: asymmetric, silent, and it looks like a firewall problem for a week. Each entry closes exactly one prefix. Per entry: destination (required CIDR), via (optional nexthop), interface (optional). Leave via UNSET on an L3-routed private fabric (Hetzner private networks): the node derives the fabric gateway from its own LAN route, and naming the router peer instead is rejected without onlink and silently blackholes with it. Empty (the default) emits NOTHING into cloud-init: no files, no units. |
routes_lan | string | null | no | Override the LAN prefix routes hang off: the prefix whose own route on the node yields the interface and, on an L3 fabric, the nexthop. null derives it from networking, which is right whenever the module and the substrate agree on what the node’s LAN route looks like. Set it only when they do not (e.g. attached to an existing network whose DHCP-pushed prefix differs from what this module declares). A wrong value is not silent: shc-node-routes.service fails with “no route for LAN |
* ssh_public_key is required only when create_ssh_key = false.
shc/hetzner outputs
Section titled “shc/hetzner outputs”| Name | Description |
|---|---|
cluster_name | Echoes var.cluster_name. |
bootstrap_node | The shc init node, resolved by NAME via bootstrap_node_name: {name, management, internal, public}, the M10 address containers. |
nodes | Every node across all groups, ordered bootstrap-first: the core nodes input verbatim (concat for mixed clusters). Self-describing entries {name, management, internal, public, runtime, group, index, nic, host_key}, host_key being the pin of the host key this module minted; derive any flat list yourself, e.g. [for n in module.shc.nodes : n.management.ipv4]. The pre-M10 flat projections (node_names / node_public_ipv4s / node_private_ipv4s / node_runtimes / nic_name) are REMOVED (M10/M12). |
cluster_ssh_hosts | Every node in the provider’s ssh.hosts shape ([{host, user, host_key}]), bootstrap first, addressed on the plane ssh_address names, each carrying its node’s host key pin. Address-less nodes are dropped; an ALL-empty projection fails the plan. |
cluster_endpoint | The cluster’s API endpoint, https://<bootstrap.host> through Traefik’s shc-api route. null unless manage_platform = true, bootstrap != null and bootstrap.host is set: the daemon answers its own port only on loopback, its containers’ gateway and the mesh, so no firewall rule or ssh_address plane makes an address on that port an endpoint. The API wants a bearer this module does not hand out, so a provider "shc" block reaches the cluster over ssh (cluster_ssh_hosts) instead. Every cloud module passes it on the same way. |
cluster_ca_pem | Cluster global-root CA PEM. null unless manage_platform = true AND bootstrap != null. |
region | The default location. |
network_id | The cluster network id (or null when private = false). |
firewall_ids | {cluster, groups} firewall ids. |
ssh_public_key | The cluster key’s public half (generated or echoed BYO). |
ssh_private_key | The GENERATED private key (sensitive; null for BYO). |
shc/hetzner usage
Section titled “shc/hetzner usage”module "shc" { source = "../../modules/shc/hetzner"
cluster_name = "cloud" ssh_public_key = var.ssh_public_key ssh = { user = "admin", private_key_path = var.ssh_private_key_path }
node_groups = { control = { count = 3, server_type = "cx33", runtime = "docker", control_plane = true } workers = { count = 2, server_type = "cx43", runtime = "docker", region = "nbg1" } }
networking = { private = true, ip_range = "10.10.0.0/16", subnet = "10.10.1.0/24" }
bootstrap = { package = { version = var.shc_version } vault_password = var.vault_pw host = "cloud.example.com" }
topology = { kind = "lb" dns = { name = "hetzner", type = "hetzner", zones = ["example.com"], credentials = { token = var.hcloud_token } } }}Sizing the private network
Section titled “Sizing the private network”Every front door defaults to ip_range = "10.10.0.0/16" with
subnet = "10.10.1.0/24": a /16 network holding one /24 subnet. (Hetzner is
the exception: subnet is unset by default there, which selects LINK mode
and attaches to an existing network instead of creating one. Set subnet to
get CREATE mode and the same shape as the other clouds.)
Is a /24 too small? Almost certainly not, and the reason is not the address math.
- A /24 is Hetzner’s own recommended subnet size, which is where the default comes from. The other cloud modules inherited it so a multi-cloud estate reads the same.
- Hetzner caps a network at roughly 100 servers. You hit the provider’s node limit at ~100 long before you exhaust ~245 usable node addresses. On Hetzner the /24 is not the binding constraint and widening it buys nothing.
- SHC reserves
.1–.9for gateway and infra addresses: node addresses start above 10. On Hetzner a node’s address is its group’shost_offset(10 unless set) plus the number in its name, somain01is.11. Two groups on one subnet each name their own range, and adding or removing a node moves no other node. The other front doors still give eachnode_groupsentry a slice in ascending group-key order (local.group_offsets), so a group that sorts first renumbers the ones after it.
Sizing against expected node count:
| Nodes you expect | Subnet | Why |
|---|---|---|
| 1–50 (essentially everyone) | /24 (default) | ~245 node addresses after the reserved low range. Nothing to think about. |
| 50–100 | /24 (default) | Still fits. On Hetzner you reach the ~100-server-per-network cap first, so a wider subnet does not raise the ceiling. |
| 100+ on one network | /23 or wider, and check the provider’s per-network server cap | Address space is the easy half. Confirm the substrate actually allows that many nodes in one network before sizing for it. |
| Any size, but the range collides | anything free | Pick by collision, not by count; see below. |
The real reasons to change it are collisions, not capacity. Widen or
move the range when it overlaps something the nodes must reach: an existing
office LAN, a VPN client pool, a peered VPC, or a container address pool.
Hetzner’s DHCP pushes the network’s ip_range as the node’s LAN route,
not the subnet’s. Measured on a live estate, ip route on a node shows the
ip_range prefix via the fabric gateway on the private NIC, not the /24. So
ip_range is the prefix that has to be conflict-free, and it is what
routes hang off by default (override with routes_lan).
Pick it at genesis. The subnet’s CIDR is not an in-place edit: changing
it replaces the subnet resource and detaches every node from the network.
The same is true of networking.zone; see the
network_zone_matches_region check in
terraform/modules/shc/hetzner/main.tf, whose message spells out the
consequence. Renumbering a standing estate is a planned migration, not a
variable tweak.
Cross-substrate variance
Section titled “Cross-substrate variance”Every front door shares these inputs: cluster_name, create_ssh_key,
ssh_public_key, extra_authorized_keys, nic_name, estate, protected,
ssh, node_groups, networking (where a private plane
exists), firewall, bootstrap, topology,
manage_platform, and the same outputs (nodes, bootstrap_node,
cluster_endpoint, cluster_ca_pem, node-list outputs, ssh_*).
Every cloud front door mints each node’s SSH host key in terraform, installs
it through cloud-init (gcp’s startup script, hostinger’s post-install
script) and pins it through the node’s nodes and cluster_ssh_hosts
entries. proxmox cannot: Proxmox’s own cloud-init installs no host key, so
its ssh takes host_key for a template whose cloud-init keeps the key it
was built with, or insecure_ignore_host_key = true, and the plan fails
with neither.
What differs is the infra shaping:
| Cloud | Placement input | Instance size key | Extra infra inputs |
|---|---|---|---|
hetzner | region | server_type | labels, placement_group, networking.zone/subnet |
aws | availability_zone | instance_type | ami/ami_name_filter/ami_owner, root_volume, assign_eips, iam_instance_profile, tags |
gcp | zone | machine_type* | image/image_family/image_project, root_volume, assign_static_ips, service_account, labels |
azure | resource group / region | VM size* | image reference, VNet/subnet |
digitalocean | region | droplet size* | image, assign_reserved_ips, tags |
linode | region | instance type* | image, region-scoped VPC |
scaleway / vultr / exoscale / alibaba / cloudstack / openstack | zone/region | provider-native size | provider-native network + IP assignment |
hostinger | data_center (placement only) | plan: a PURCHASE SKU encoding the machine AND the billing term (hostingercom-vps-kvm1-usd-1m) | template_name/template_id, payment_method_id, accept_monthly_billing. NO network, firewall, volume or LB inputs; the substrate has none |
proxmox | proxmox_node | cores / memory / disk_size | template_name, storage, network_bridge, gateway, nameservers, vmid_base, ssh_user; no cloud-init user-data (the SSH engine installs the .deb) |
* The exact input name for instance sizing is declared inside each
node_groups object per cloud (e.g. server_type, instance_type,
machine_type). Read that module’s variables.tf (or its README) for the
precise per-cloud shape. control_plane is the same optional bool on every front door: it puts the group in the control plane.
Each front door’s README documents its cloud-specific deltas and any
“unverified-live” caveats. The shared cloud-init contract (an admin user
with NOPASSWD sudo, host-firewall disable, extra-NIC DHCP fallback) is
byte-identical across every cloud-init substrate; gcp mirrors it in shell,
and proxmox rides the template image’s default admin user.