Skip to content
SHC Docs

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 every shc_* resource. No cloud provider in required_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 the nodes list, and calls core. hostinger is 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
# ...
}

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.

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 .backup sibling 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.

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/alibabashc/awsshc/azure
shc/cloudstackshc/digitaloceanshc/exoscale
shc/gcpshc/hetznershc/hostinger
shc/linodeshc/openstackshc/proxmox
shc/scalewayshc/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.

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.


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).

LayerGateWhat it creates
bootstrapbootstrap != nullthe 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.)
topologytopology != 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.

NameTypeDefaultRequiredDescription
nodeslist(object)noneyesEvery 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.
sshobjectnullwith bootstrapThe 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_addressstring"public"noWHICH 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.
bootstrapobjectnullnoBootstrap config (see below). null skips the bootstrap layer (nodes provisioned but no shc_* resource touched).
topologyobjectnullnoPlatform/topology config, dispatched by kind (see below). Requires bootstrap != null.
bootstrap_node_namestringnullnoThe 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_destroystringnullnoThe 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_tokenstringnullnoThe 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:

FieldTypeDefaultDescription
packageobject {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_passwordstringnone (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).
fabricstring""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_blockstring""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.
hoststring""The public domain seed (shc init --ingress-host), NOT an address.
acmeobjectnoneNamed ACME providers + a cluster default: providers (map of {directory, email, eab_kid, eab_hmac}), default, email. Blank directory = Let’s Encrypt production.
modulesmap(object)noneSystem-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).
connectionsmap(object)noneConnections 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.
storagestring""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:

FieldTypeDefaultDescription
kindstringnone (required)"lan", "wan", or "lb".
dnsobjectnone{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_addressstring""Cluster public entrypoint address (lan/lb DNS).
lb_portsmap(object)noneFor “lb”: extra LB port attaches, keyed by "external[/udp]", value {container?, service?} (service default traefik).
volume_providerobjectnoneFor “lb”: {provider, config?}, the block-volume storage provider config.
volume_secretsmap(string){}For “lb”: secret keys for the volume provider.
NameDescription
cluster_endpointThe daemon API endpoint. null unless bootstrap != null.
cluster_ca_pemThe 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. core never 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.


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.

NameTypeDefaultRequiredDescription
cluster_namestringnoneyesCluster name; every node is "<role><NN>.<cluster_name>"; also prefixes and labels every hcloud resource.
regionstring"fsn1"noDefault Hetzner location. Per-group override: node_groups.<key>.region.
generationstringnullnoBLUE/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_namesboolfalsenoMake 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.
imagestring"debian-13"noDefault OS image (keep a Debian image). Per-group override available.
create_ssh_keyboolfalsenoMint 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_keystringnullno*SSH public key. create_ssh_key = false: required (BYO). create_ssh_key = true: optional break-glass key.
extra_authorized_keyslist(string)[]noExtra public keys appended to the admin user via cloud-init. Create-time on hcloud_server: changing later REPLACES servers.
nic_namestringnullnoOverride the auto-derived plane NIC hint (private ? "enp7s0" : "eth0"). Per-group override available.
labelsmap(string){}noExtra labels merged onto every hcloud resource.
estatestringnullnoOrg-estate marker stamped as estate=<name> on every resource.
sshobjectnullwith bootstrapPassed 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_addressstring"public"noWHICH 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_groupsmap(object)noneyesNode 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.
networkingobject{}noONE 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.
firewallobject{}noGLOBAL 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_namestringnullnoThe 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_groupbooltruenoOwn an hcloud “spread” placement group (anti-affinity) named cluster_name.
bootstrapobjectnullnoForwarded 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.
topologyobjectnullnoForwarded to core unchanged. Requires bootstrap != null.
manage_platformbooltruenotrue: call core (full front door). false: INFRA-ONLY: build servers/network/firewall, expose nodes, touch no shc_* resource (mixed-cluster split).
protectedboolfalsenoDelete/termination protection for the estate’s iron. Flip true once live; tofu destroy fails until reverted. (No-op on some clouds.)
on_destroystringnullnoForwarded 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_tokenstringnullnoForwarded 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>.
routeslist(object)[]noSTATIC 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_lanstringnullnoOverride 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.

NameDescription
cluster_nameEchoes var.cluster_name.
bootstrap_nodeThe shc init node, resolved by NAME via bootstrap_node_name: {name, management, internal, public}, the M10 address containers.
nodesEvery 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_hostsEvery 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_endpointThe 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_pemCluster global-root CA PEM. null unless manage_platform = true AND bootstrap != null.
regionThe default location.
network_idThe cluster network id (or null when private = false).
firewall_ids{cluster, groups} firewall ids.
ssh_public_keyThe cluster key’s public half (generated or echoed BYO).
ssh_private_keyThe GENERATED private key (sensitive; null for BYO).
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"
acme = { providers = { prod = { email = "[email protected]" } }, default = "prod" }
}
topology = {
kind = "lb"
dns = { name = "hetzner", type = "hetzner", zones = ["example.com"], credentials = { token = var.hcloud_token } }
}
}

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–.9 for gateway and infra addresses: node addresses start above 10. On Hetzner a node’s address is its group’s host_offset (10 unless set) plus the number in its name, so main01 is .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 each node_groups entry 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 expectSubnetWhy
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 capAddress 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 collidesanything freePick 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.

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:

CloudPlacement inputInstance size keyExtra infra inputs
hetznerregionserver_typelabels, placement_group, networking.zone/subnet
awsavailability_zoneinstance_typeami/ami_name_filter/ami_owner, root_volume, assign_eips, iam_instance_profile, tags
gcpzonemachine_type*image/image_family/image_project, root_volume, assign_static_ips, service_account, labels
azureresource group / regionVM size*image reference, VNet/subnet
digitaloceanregiondroplet size*image, assign_reserved_ips, tags
linoderegioninstance type*image, region-scoped VPC
scaleway / vultr / exoscale / alibaba / cloudstack / openstackzone/regionprovider-native sizeprovider-native network + IP assignment
hostingerdata_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
proxmoxproxmox_nodecores / memory / disk_sizetemplate_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.