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 Pages tarball URL (the version lives IN the URL — go-getter archive fetch, no version argument), or by a local relative path when developing in-tree:

module "shc" {
  source = "https://<PAGES-URL>/modules/shc-hetzner-0.3.0.tgz"  # published
  # source = "../../modules/shc/hetzner"                        # in-tree
  # ...
}

• The core module
• The shc/<cloud> front doors

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

bootstrap object:

topology object:

module "core" {
  source = "../../modules/core"

  nodes = [
    { name = "n1", public_ipv4 = "198.51.100.10", private_ip = null, runtime = "compose", group = "control", index = 0, nic = "eth0" },
    { name = "n2", public_ipv4 = "198.51.100.11", private_ip = null, runtime = "compose", group = "control", index = 1, nic = "eth0" },
  ]

  ssh = { user = "admin", private_key_path = "~/.ssh/id_ed25519" }

  bootstrap = {
    package        = { deb_url = "https://.../shc_..._linux_amd64.deb" }
    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 Nebula lighthouse — 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.

* ssh_public_key is required only when create_ssh_key = false.

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 = "compose" }
    workers = { count = 2, server_type = "cx43", runtime = "swarm", region = "nbg1" }
  }

  networking = { private = true, ip_range = "10.10.0.0/16", subnet = "10.10.1.0/24" }

  bootstrap = {
    package        = { deb_url = var.deb_url }
    vault_password = var.vault_pw
    host           = "cloud.example.com"
    acme           = { providers = { prod = { email = "ops@example.com" } }, default = "prod" }
  }

  topology = {
    kind = "lb"
    dns  = { name = "hetzner", type = "hetzner", zones = ["example.com"], credentials = { token = var.hcloud_token } }
  }
}

Every front door shares these inputs: cluster_name, create_ssh_key, ssh_public_key, extra_authorized_keys, nic_name, estate, protected, install_nebula, ssh, node_groups, networking (where a private plane exists), firewall, nebula_version, bootstrap, topology, manage_platform — and the same outputs (nodes, bootstrap_node, cluster_endpoint, cluster_ca_pem, node-list outputs, ssh_*).

What differs is the infra shaping:

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

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.