Skip to content
SHC Docs

Getting started with Terraform / OpenTofu

A task-oriented quickstart: install the shc provider from the network mirror, pick an example, set credentials, and tofu init / plan / apply a cluster. Commands use tofu (OpenTofu); terraform works identically.

See also The shc provider and The module library for the full reference.

  • OpenTofu ≥ 1.6 (or Terraform ≥ 1.6). The provider and modules declare required_version = ">= 1.6.0".
  • A cloud account for your chosen substrate (Hetzner, AWS, etc.), with a credential the cloud’s own Terraform provider reads (usually an environment variable such as HCLOUD_TOKEN, AWS_PROFILE, GOOGLE_CREDENTIALS).
  • The SHC version each node installs by apt from the Based repository (bootstrap.package.version, such as 0.1.2).
  • An SSH key the provider uses to install and bootstrap each node (or let the module mint one with create_ssh_key = true).

Install the shc provider from the network mirror at https://selfhostedcloud.org/terraform/0.1/. It serves static JSON and zips publicly, with no login. Write a CLI config file (many examples ship one as registry.tfrc):

registry.tfrc
provider_installation {
network_mirror {
url = "https://selfhostedcloud.org/terraform/0.1/"
include = ["registry.terraform.io/selfhosted-cloud/shc",
"registry.opentofu.org/selfhosted-cloud/shc"]
}
direct {
exclude = ["registry.terraform.io/selfhosted-cloud/shc",
"registry.opentofu.org/selfhosted-cloud/shc"]
}
}

Then point the CLI at it for the session:

Terminal window
export TF_CLI_CONFIG_FILE="$PWD/registry.tfrc"

Notes:

  • The include/exclude pair scopes the mirror to only the shc provider so your cloud providers (hcloud, aws, google, …) still install direct from the public registry.
  • The mirror serves the provider under BOTH registry.terraform.io and registry.opentofu.org, so the short source selfhosted-cloud/shc resolves for either tool.
  • Prefer a persistent config? Put the same provider_installation block in ~/.terraformrc (Terraform) or ~/.tofurc (OpenTofu) instead of the TF_CLI_CONFIG_FILE export.

Your root’s required_providers uses the short source name and the SHC release version:

terraform {
required_providers {
shc = {
source = "selfhosted-cloud/shc"
version = "~> 0.1"
}
}
}

See The provider → Installing from the network mirror for details on the mirror and archive checksums.

Copy the example that matches your substrate from terraform/examples/ (see the Examples table for the full list). For a first cluster, a <cloud>-shc root (a single module "shc" call) is the simplest:

Terminal window
cp -r terraform/examples/hetzner-shc my-cluster
cd my-cluster

Most examples ship a terraform.tfvars.example. Copy it and fill it in:

Terminal window
cp terraform.tfvars.example terraform.tfvars
$EDITOR terraform.tfvars # cluster_name, shc_version, vault_pw, shc_host, dns_zone, ...

Two credential sets are involved:

  • The cloud provider: export the environment variable the cloud’s provider reads, e.g. export HCLOUD_TOKEN=... (Hetzner), export AWS_PROFILE=... (AWS). Keep it out of .tfvars and state.
  • SHC bootstrap: bootstrap.vault_password seals the cluster’s system vault (required); the ssh block (key material or a private_key_path) is how the provider reaches each node. Changing the password later rotates the live vault in place (provider reference, Rotating the vault password). Some examples mint the SSH key and a random vault password in-config (tls_private_key + random_password).

Sensitive material lands in state. The vault password, SSH private key, and any connection credentials are written to Terraform state (the provider marks them sensitive, but they are still there). Use an encrypted state backend.

vault_password is the genesis SEED, not a live mirror of the master. This provider does not rotate the vault; the daemon does. Rotate with shc vault rotate on a node of the cluster, then set vault_password to the new value so state and reality agree; otherwise tofu output -raw vault_password keeps returning a password that no longer opens the vault, and that output is the documented cold-start recovery for a locked vault. Never taint or replace the bootstrap node to change it: that re-runs cluster genesis (new node id, new raft membership, new cluster CA) and is not a password change.

Terminal window
tofu init # installs the shc provider from the mirror + the cloud provider
tofu plan # review: infra + bootstrap (shc_cluster/shc_node) + topology
tofu apply

One apply provisions all three layers with no out-of-band steps:

  1. Infra: instances, network, firewalls (plain cloud resources).
  2. Bootstrap: the provider installs the .deb and runs shc init on node 1 and shc node join on the rest, over its SSH transport (no bearer token needed; see below).
  3. Topology / platform: DNS, ACME, LB attach, mesh, and any app deployments the root declares.

When it finishes, read the outputs:

Terminal window
tofu output # cluster_endpoint, node names/IPs, etc.
tofu output -raw ssh_private_key # if the module minted the key

That output is the only copy of the node login credential, and a node replacement mints a new one. Before you rely on a key file on disk, read Reaching estate nodes over SSH: it covers retrieving the key from state, why a checked-out copy goes stale without warning, and the converge that can lock you out of a healthy estate.

6. How the provisioned nodes relate to shc init / shc node join

Section titled “6. How the provisioned nodes relate to shc init / shc node join”

The module maps directly onto the CLI bootstrap verbs: every node is an shc_node, and exactly one has bootstrap = true:

TerraformCLI equivalentOn which node
shc_node with bootstrap = trueshc initnodes[0] (the first node of the alphabetically-first node_groups key)
every other shc_nodeshc node joineach remaining node
data.shc_mesh (optional data source, declared separately)shc cluster mesh statusreads cluster-wide mesh0 status

The provider runs those verbs over an SSH transport: it installs the .deb and runs shc ... ON the bootstrap node, which authenticates for free against its own local admin socket (peer-credential auth). No bearer token, no admin_token, no hand-run driver.sh. (An alternative adopt path lets a node self-init from cloud-init user_data rendered by data.shc_cloudinit, with Terraform polling it healthy over HTTP; see The provider.)

After apply, drive the live cluster with the CLI as usual: SSH to the bootstrap node and run shc status, shc install <app>, shc node ls, etc., or manage more resources declaratively by adding shc_deployment, shc_connection, and shc_config blocks to the same root.

  • Upgrade the cluster by changing bootstrap.package.version: the provider installs that version on each node by apt and re-checks health one node at a time (raft quorum stays intact).
  • Add apps with shc_deployment (see The provider → shc_deployment).
  • Destroy with tofu destroy. If the substrate module was applied with protected = true, flip it to false and apply once first; protected resources refuse destruction.
  • tofu init can’t find the provider: the mirror isn’t reachable. curl https://selfhostedcloud.org/terraform/0.1/registry.terraform.io/selfhosted-cloud/shc/index.json should return JSON naming the release you pin.
  • Missing vault_password: bootstrap.vault_password is required; the SSH bootstrap engine hard-errors when it is empty.
  • X400998SSHSUD: the SSH user lacks passwordless sudo. The modules’ default admin user has NOPASSWD sudo; a custom non-root user needs the same, or use user = "root". This one is provider-minted (terraform/provider/internal/provider/ssh_engine.go), so it is deliberately absent from the daemon’s error reference.
  • Diagnostics with an X… code: most are daemon error codes that the provider surfaces verbatim so you can grep them. The provider mints only three of its own (the two X400998SSH… transport refusals and the second-cluster genesis refusal, which that page names and explains), and each is documented where it is raised rather than in the generated daemon reference.