Skip to content
SHC Docs

SHC Terraform provider

selfhosted-cloud/shc is a custom Terraform / OpenTofu provider that configures a Self-Hosted Cloud cluster through its daemon: bootstrapping nodes, installing apps, wiring DNS, and managing tenants, users, connections, and scoped config. It has 21 resources and 5 data sources.

This page covers declaring the provider, pointing the CLI at the network mirror, the provider configuration block, the two transports, and a reference section for every resource and data source. Commands use tofu; terraform works identically.

Use the short source name. The mirror serves both registry hostnames, and the provider version follows the SHC release version:

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

The provider ships through the network mirror at https://selfhostedcloud.org/terraform/0.1/, which serves static JSON and zips publicly, with no login. Point the CLI at it with a provider_installation block in ~/.terraformrc (Terraform), ~/.tofurc (OpenTofu), or a repo-local file selected with export TF_CLI_CONFIG_FILE="$PWD/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"]
}
}
  • https://selfhostedcloud.org/terraform/0.1/ is the new line’s mirror root, publicly readable.
  • The include/exclude pair scopes the mirror to only the shc provider; without it, tofu init tries the mirror for hcloud/aws/google too and fails. The mirror serves the provider under both registry hostnames, so the short source resolves for either tool.

Integrity. Version documents include zh: SHA-256 checksums for the provider zips. Keep .terraform.lock.hcl to retain the checksums recorded by Terraform / OpenTofu. The network mirror has no signature channel.

The provider block is optional: it pins a day-2 target. When you bootstrap a cluster in the same plan, you can omit it and set a per-resource cluster { ... } block instead, so a cluster created in the same graph is addressable.

provider "shc" {
endpoint = "https://shc.example.com" # or "unix:///run/shc/shc.sock"
# Preferred for real runs: OAuth2 client_credentials (self-minting).
client_id = "terraform"
client_secret = var.shc_client_secret
ca_pem = file("cluster-ca.pem")
}
ArgumentTypeRequiredSensitiveEnv fallbackDescription
endpointstringnonoSHC_ENDPOINTDaemon API endpoint: the estate’s host through Traefik (https://shc.example.com), or unix:///run/shc/shc.sock on a node. shcd’s own :8000 answers only the node, its system ingress and the mesh. Optional when every resource carries its own cluster block.
tokenstringnoyesSHC_TOKENStatic bearer token for TCP endpoints (ignored for unix://). Mutually exclusive with client_id/client_secret.
client_idstringnonoSHC_CLIENT_IDOAuth2 client_credentials client id (mint with shc auth create-service-client). Self-mints + re-grants its bearer. Mutually exclusive with token.
client_secretstringnoyesSHC_CLIENT_SECRETOAuth2 client_credentials secret. Mutually exclusive with token.
token_urlstringnonononeOAuth2 token endpoint; defaults to https://<endpoint-host>/auth/realms/master/protocol/openid-connect/token. Only with client_id/client_secret.
ca_pemstringnonoSHC_CA_PEMPEM bundle to trust for TLS against the cluster’s internal CA (the ca_pem output of the bootstrap node).
insecureboolnonononeSkip TLS certificate verification (bootstrap/testing only; prefer ca_pem).
sshblocknon/anoneDefault SSH transport for every platform resource; see below.
registry_authblocknon/anonePre-authenticate the node container runtime during SSH bootstrap (avoids registry rate limits).

Selects the SSH transport as the default for every platform resource that does not carry its own cluster.ssh override: resources run shc ... CLI verbs over SSH on a cluster node, no bearer token needed.

ArgumentTypeRequiredSensitiveDescription
hostslist(object)yesnoEVERY node the provider may run shc ... on, most-likely-leader first. Tried in order until one connects and is willing to serve the operation. Feed it module.<cluster>.cluster_ssh_hosts.
userstringnonoDefault SSH user for every entry (default root; non-root users need NOPASSWD sudo; every command runs sudo -n).
private_keystringnoyesDefault SSH private key (PEM) for every entry.
portintnonoDefault SSH port for every entry (default 22).
host_keystringnonoDefault known_hosts-format host-key pin for every entry. An entry with no pin of its own and none here fails the plan, and is never dialled, unless insecure_ignore_host_key is true.
insecure_ignore_host_keyboolnonoDial an entry with no host_key, its own or the block’s, with no host key check. An entry with a pin is still checked against it. Nothing is recorded on a first connection.

Each hosts entry is { host, user, private_key, port, host_key }; only host is required; the rest fall back to the block-level defaults above, so the common case is a list of addresses with their pins, which a module’s cluster_ssh_hosts output carries. Per-entry overrides exist for estates whose nodes genuinely differ (mixed images mid-migration, a heterogeneous multi-cloud cluster, one node still keying root).

There is no scalar ssh.host. It existed briefly as single-node sugar for a one-entry list and was removed: one pinned address cannot fail over when a rebuild reassigns public IPs or when the node it names is no longer the raft leader, and both of those cost a live estate an outage on 2026-07-27. A genuinely single-node cluster writes:

ssh = {
hosts = [{ host = "198.51.100.10", host_key = var.node_host_key }]
user = "admin"
private_key = var.ssh_key
}

When no entry can serve an operation, the error names every host with its own reason (auth vs timeout vs refused vs not-leader). Never wrap the list in try(..., "127.0.0.1"), which dials the machine running terraform.

ArgumentTypeRequiredSensitiveDescription
serverstringnonoRegistry hostname (default Docker Hub).
usernamestringnonoRegistry username.
passwordstringnoyesRegistry password or access token (crosses the wire as SSH-session stdin).

Exactly one of:

  • client_id + client_secret (preferred): the provider self-mints its bearer and transparently re-grants it (proactively at ~80% of the token lifespan, and once on a 401), so applies longer than one token lifetime never die 401 partway. Mint the pair with shc auth create-service-client terraform on the cluster.
  • token (static): cannot re-grant mid-run; a long apply outlives its lifespan and fails.
  • ssh: no bearer at all; runs the CLI over SSH on the bootstrap node.
  • A unix:// endpoint needs none (peer-credential auth).

token and the client-credentials pair conflict loudly at configure time. Both have env fallbacks, so a stray environment variable can be the surprise second half of that conflict.

Transports and the per-resource cluster block

Section titled “Transports and the per-resource cluster block”

Every platform resource and every data source (shc_node’s token mint, shc_connection, shc_config, shc_dns_record, shc_stack_ports, shc_user, shc_tenant, shc_deployment, and the shc_mesh, shc_cluster_status, shc_catalog_app, shc_enrollment_token, shc_cloudinit data sources) supports two transports:

  • HTTP API: a bearer token authenticates calls to the daemon (needs endpoint/token, or client_id/client_secret).
  • SSH: when a cluster { ssh { ... } } block is set (or inherited from the provider’s own ssh), the resource runs the equivalent shc <verb> CLI command over SSH on whichever node in hosts answers and can serve the operation, authenticated by its local unix-socket peer credential, no bearer token.

A provider block carrying only an ssh block is a complete configuration: it is what module.<cluster>.cluster_ssh_hosts is for, and the resources and the data sources all read through it with no endpoint anywhere.

Every resource and data source accepts an optional per-resource cluster override block so a cluster created in the same plan is addressable:

resource "shc_config" "platform" {
cluster = {
ssh = { hosts = module.shc.cluster_ssh_hosts, user = "admin", private_key = var.ssh_key }
}
# ...
}

Resource cluster block:

ArgumentTypeRequiredDescription
endpointstringnoDaemon API endpoint. Required unless ssh is set.
tokenstringno (sensitive)Bearer token for TCP endpoints.
ca_pemstringnoPEM bundle to trust for TLS.
insecureboolnoSkip TLS verification (bootstrap/testing only).
sshblocknoRun this resource’s ops over SSH, same fields as the provider ssh block. When both HTTP and ssh are set, ssh wins.

(The cluster block carries a static token only; the client-credentials mode is a provider-block feature. On a data source cluster block, endpoint is Required.)


The cluster’s genesis config: a pure, inputs-only declarative record. It owns no node and does no SSH: every node is an shc_node, and the one with bootstrap = true runs shc init and emits the cluster creds. This resource is the single home for cluster-wide genesis parameters a module wires onto that bootstrap node. It emits nothing load-bearing (only a stable id), which keeps the dependency graph acyclic.

ArgumentTypeRequiredSensitiveDescription
packageblockyesnoCluster-wide SHC package default (version, repository); every shc_node inherits it.
fabricstringnonoGenesis cross-node data plane (shc init --fabric): shc (routed WireGuard on shc0) or none (only where the runtime cannot attach it). Unset omits the flag. The daemon then selects shc where the runtime can attach the fabric. Cluster-scoped and consumed once at genesis.
address_blockstringnonoThe cluster’s address block (shc init --address-block; daemon default 10.64.0.0/16). Every SHC range is carved from it, so it applies in every fabric mode. A /8 to a /16, clear of 172.16.0.0/12. See the address block.
host_domainstringnonoThe genesis domain (shc init --ingress-host) / basePath seed.
modulesmap(block)nonoStructured system-app selection + per-app overrides (see below).
connectionsmap(block)noyes (credentials)Connections shc init makes before the platform stacks install (--connection-file), keyed by name, each shaped like shc_connection (type, tenant, scope, credentials, zones).
storagestringnonoThe volume connection the platform stacks’ durable volumes go on (shc init --storage, written as storage.volumes.provider before they install).
vault_passwordstringnoyesVault password sealing the always-local system vault. Changing it records the new INTENT and warns that this record re-keys nothing: the rotation is performed by the shc_node carrying bootstrap = true that reads this value.
acmeblocknonoNamed ACME providers + the cluster default (see below).
idstringcomputednoStable id: host_domain when set, else "shc-cluster". Never an endpoint.

package block: version (string, required), the shc version every node installs, as a release names it (0.1.2). The node adds the Based apt repository (https://apt.basedlinux.com/deb/based, suite d13) with Based’s signing key and a preference that takes shc alone from it, installs exactly that version and holds it, so no apt upgrade on the node moves it. A change (propagated to nodes) triggers their in-place rolling upgrade. The install is tried up to four times, 15s, 30s and 45s apart, when apt fails on weather: a name that doesn’t resolve yet, a dropped connection, or a 5xx from a repository. A 4xx, a version no source carries or a full disk fails at once. repository (string, optional) is for UNRELEASED builds only: the URL of one more apt repository holding a build Based does not carry, a flat directory with the deb and a Packages file (scripts/apt-flat-repo.sh writes one, file:/var/tmp/shc-apt or http://<build host>/<directory>). It is UNSIGNED: the node trusts whatever that URL serves. ready_timeout / transport_timeout (string, optional), the roll’s two patience budgets, described under shc_node below.

modules block (map keyed by system-app name; the key SET is the install selection: unset installs the daemon’s default set, {} installs only traefik, the edge every join goes through, a populated map installs those apps plus traefik): host (string), base_path (string), vars (map(string)), seeded under modules.<name>.*. Init-time only.

acme block: providers (map keyed by operator label, each with directory, email, eab_kid, eab_hmac(sensitive)), default (string), email (string). A blank directory is Let’s Encrypt production.

resource "shc_cluster" "main" {
package = { version = var.shc_version }
host_domain = "cloud.example.com"
vault_password = var.vault_pw
acme = { providers = { prod = { email = "[email protected]" } }, default = "prod" }
}

A cluster node. The model is symmetric: every node is an shc_node. Exactly one sets bootstrap = true and runs shc init (minting the CA + genesis and emitting the creds); every other runs shc node join. Exactly one bootstrap mechanism applies per node: adopt = true (poll a self-init/self-joined node over HTTP) or an ssh block (install the .deb and run init/join over SSH); adopt wins when both are set.

A rebuilt machine. With the node’s ssh block and cluster.ssh set, the plan warns Rejoining a rebuilt machine and shows node_id and healthy as known after apply. This is an in-place update, not a replacement. The check runs only when the state reads the node unhealthy or its planned host key or management address changed. It requires the cluster to report the name absent or unhealthy, and the machine at the planned management address to answer SSH with no /var/lib/shc/node.id. A failed probe plans no rejoin. Apply checks again, forgets any stale member through surviving members, installs package.version and joins under the same name. An occupancy refusal is retried with --force and a warning listing the affected deployments; quorum refusals still fail. Deployment rows keep naming the node, which runs again what those rows place on it. A bootstrap node also receives its vault auto-unlock credential and keeps its cluster outputs. Record a reinstalled host’s new SSH host key first.

ArgumentTypeRequiredSensitiveDescription
clusterblocknon/aPer-resource cluster/transport override (join reference).
bootstrapboolnonoCreate-time only; NOT an identity and NOT RequiresReplace. true ⇒ run shc init on the apply that creates this node; false (default) ⇒ shc node join. Nothing reads it afterwards, so flipping it on an existing node is an in-place no-op; the plan warns that it changes nothing rather than refusing (rulings M8 + M11: “there should be nothing special about the first init node”). Moving the vault cold-start capability is a separate, explicit verb: shc vault coldstart replant.
force_genesisboolnonoBootstrap-only, create-time only, dangerous. Waives the existing-cluster probe described below. Does not force replacement.
hoststringyesnoNode address (host/IP, or full https://…/unix:// URL). SSH target and bootstrap endpoint base.
packageblocknonoPackage to install before SSH init/join (version, repository, ready_timeout, transport_timeout), as on shc_cluster; ssh-engine only. A change of version does an in-place rolling upgrade.
converge_package_versionboolno (default false)noStanding consent to roll this node onto package.version when its own dpkg reading (installed_version) names another build. Unset, the mismatch is shown and nothing is planned. See The in-place upgrade’s order and health gate below.
sshblocknon/aSelects the SSH engine (install + init/join over SSH). Fields: user, private_key(sensitive), port, host_key, insecure_ignore_host_key, jump. host_key is the node’s known_hosts-format host key, checked on every connection, and is required unless insecure_ignore_host_key = true, which skips every host key check of this node’s connections (a first contact in a lab only). jump = { host, port, user, private_key, host_key } is one host to reach the node through (ProxyJump), for a node the machine running terraform cannot route to: every SSH connection to the node goes through it, from install and init or join through upgrades, in-place repairs and destroy. host is required; port defaults to 22, user to admin, private_key (sensitive) to ssh.private_key. host_key is the jump host’s key, required the same way, and each hop checks its own key. A jump host that does not forward (AllowTcpForwarding no) fails at once, not after the dial deadline. A jump host cannot have a jump host of its own.
adoptboolnonoAdopt a self-initialized/self-joined node: poll it healthy over HTTP, at https://<host_domain> or a management URL spelled with a scheme; a bootstrap node with neither is refused at plan time (X400162ADPHST). Read once, on Create; changing it on an existing node is a plan-time error, because it selects nothing afterwards. The ssh block, not this, is what update-time operations read, and it can be added or removed in place.
namestringyesnoNode name (--name), the membership identity polled for. Forces replacement.
nicstringnonoThe one internal-traffic interface (--nic). Forces replacement.
runtimestringnonoContainer runtime (--runtime). Forces replacement.
public_addressstringnonoPublic ingress address (--public-address); managed DNS reads it. Repaired in place.
locationstringnonoThe node’s location (--location): one name (hel1, us-east-1a, a site like ogden) or an operator’s path of any depth (gorillaservers/ogden/incus01). Optional and computed: unset, the value the node detected (SHC_NODE_LOCATION, then cloud metadata) is read back. A change is repaired in place over ssh (shc node update --location); removing it keeps the recorded value. The daemon’s rule: tokens of lowercase letters, digits, ., _, -, 1 to 63 characters, joined by /, no empty segment, at most 253 characters; a plan refuses anything else with the daemon’s own message.
cloudstringnonoThe cloud the node runs on (--cloud: hetzner, aws, proxmox, gorillaservers), one token of location’s token rule, no / or :. With location it names the node’s built-in location fence, location:<cloud>/<location>, and every level of a location path is a fence too.
control_planeboolnonoWhether the node is in the control plane (--control-plane). true passes --control-plane to shc node join (or shc init), and the cluster’s automatic voter target makes members voters: three members, three voters. The node must be able to vote. A change on an existing node runs shc node update <node> --control-plane=<value> in place; the control plane keeps at least one node. Optional and computed: unset, nothing is sent and the membership is read back. A bootstrap node that can vote is always seeded into the control plane. Removing it keeps the membership the node has.
reservestringnonoWhat the node keeps for work outside SHC (--reserve), as cpu=<cores>,memory=<size>,disk=<size>; placement and admission never use it. A create passes --reserve to shc node join (or shc init). A change runs shc node update <node> --reserve in place with every resource spelled, so a resource the new value leaves out is cleared. Removing it leaves the node’s reserve as it is. Example: reserve = "cpu=1,memory=4Gi,disk=50Gi".
hypervisorstringnonoThe incus connection the host of a node that is a virtual machine is read through (--hypervisor), as <connection> or <connection>/<instance>, where the instance may be <project>/<name>. The node then counts its host’s capacity and what runs there outside SHC. A value the daemon would refuse fails the plan. A create runs shc node update <node> --hypervisor once the node is a member; a change runs it in place, and removing it clears the node’s hypervisor. Refresh and import read it back, so a change made outside terraform shows as drift. Needs the ssh block. Example: hypervisor = shc_connection.ogden_incus.name.
private_ipstringnonoExpected private/plane IP; the SSH node-prepared gate waits for an interface to hold it. Never sent to the daemon: it is a claim the provider PROVES, so changing it RE-PROVES it: the gate re-runs over ssh against the new address and the apply fails if no interface holds it. Needs the ssh block; on an adopt-path node the gate never runs at all.
fabricstringnonoBootstrap-only, genesis-only. shc init --fabric (shc or none). CLUSTER-scoped: recorded once at genesis and read back by every joiner. shc node join has no --fabric, so setting it on a join node is a plan-time error, and so is changing it on any node. No route or CLI verb writes the posture on a live cluster.
address_blockstringnonoBootstrap-only, genesis-only. shc init --address-block (daemon default 10.64.0.0/16). Every SHC range is carved from it, so it applies in every fabric mode. A /8 to a /16, clear of 172.16.0.0/12. Consumed once, at shc init; changing it later renumbers nothing on a live cluster, and shc cluster block add adds room. See the address block.
host_domainstringnonoBootstrap-only. The cluster’s serving domain: the shc init --ingress-host seed, then the replicated cluster.host, and the base of the endpoint (https://<host_domain>). A refresh reads the live host, so after shc cluster host set <host> state and the endpoint follow it and a config naming that host plans no change. A value the cluster doesn’t serve is a plan-time error that names the live host: move a live cluster with shc cluster host set, then plan.
modulesmap(block)nonoBootstrap-only, genesis-only. System-app selection + overrides (same shape as shc_cluster.modules). A change WARNS at plan time: this node re-runs no init, so only the core module’s shc_config.system_app_overrides rows carry the override half to a live cluster, and nothing at all carries the key set (installing/removing an app is shc_deployment).
connectionsmap(block)noyes (credentials)Bootstrap-only, genesis-only. Connections shc init makes before the platform stacks install (same shape as shc_cluster.connections). Each is staged on the node as a 0600 file, passed as --connection-file and removed after the run, so no credential is on a command line. A change WARNS at plan time: the core module’s shc_connection.bootstrap resources are what reach a live cluster.
storagestringnonoBootstrap-only, genesis-only. shc init --storage: the volume connection the platform stacks’ durable volumes go on. A change WARNS at plan time: the core module’s shc_config.storage row is what reaches a live cluster, and only volumes made after it follow it.
vault_passwordstringnoyesBootstrap-only. Seals the system vault. Changing it ROTATES the vault in place (never a replacement); see Rotating the vault password below. Must carry no leading/trailing whitespace.
vault_adopt_drop_inboolnonoBootstrap-only. Defaults to false, and the default is the point. Opts this apply’s rotation into REPLACING the node’s auto-unlock credential when it holds a password that is neither the recorded one nor the new one, the terraform spelling of shc vault rotate --adopt-drop-in. Only meaningful while recovering a stranded node; see Recovering a stranded auto-unlock credential below. Modifies a rotation and never starts one.
acmeblocknonoBootstrap-only, genesis-only. Named ACME providers + default (same shape as shc_cluster.acme). A change WARNS at plan time: genesis lowered only the default provider, and the core module’s shc_config.acme rows are what reach a live cluster.
on_destroystringnonoDestroy-time occupancy consent (ruling M7). The only accepted value is "force"; anything else (including "Force" and "yes") is a plan-time error, so a typo can never quietly mean “refuse at destroy time, weeks from now”. Unset (the default) is the refusal posture: a destroy of a node deployment rows still name HARD-FAILS. Read from state at destroy time, so it must be applied before the destroy. See Destroying an occupied node below.

Exports (computed): node_id, healthy, id (= node name). Bootstrap node only (null on a join node): endpoint, ca_pem, admin_token (sensitive), join_token (sensitive), ready.

endpoint is https://<host_domain>, where Traefik’s shc-api route reaches the daemon, or a management URL spelled with a scheme (a front door) as written, and null when the node has neither: the daemon answers its own port only on loopback, its containers’ gateway and the mesh. It is derived again on every refresh, so a state an older provider wrote (http://<address>:8000) moves without an apply or a replace. The pre-destroy DNS release and the readiness refresh use the same value.

admin_token cannot be freshly minted by either mechanism: shc init produces no HTTP-usable credential. It echoes the provider block’s token (null if none). This is exactly the gap the SSH transport works around: the platform resources run without a token by talking to the bootstrap node’s local admin socket over SSH.

The in-place upgrade’s order and health gate

Section titled “The in-place upgrade’s order and health gate”

A package.version change restarts every node’s daemon once, one node at a time, and the raft leader goes last. The provider reads the leader from shc node ls when the roll starts, not from which resource is the bootstrap node. Terraform updates the bootstrap node first, so when it leads it rolls every peer still on the version it is leaving first, over the cluster’s own ssh hosts, nodes that don’t vote before voters, and then itself. A worker that leads does the same when its turn comes. A node a leader already rolled installs nothing when its own resource updates; it is only gated.

Before any restart every member has to read healthy in shc node ls and shc cluster status has to report quorum healthy. After each restart the node has to read healthy at the new build, quorum has to be healthy, and shc doctor run must show no failure that was not there when the apply began, except a row a restart raises (events.pending-broadcast, health.queue-pressure) while it holds steady or falls inside five minutes. Two checks are let by, because the roll makes them fail itself. A new build carries a new catalogue, so app.package-drift reads the deployments installed from the old one as behind on every node the roll reaches, until shc update moves them. And the roll ends on a new leader, which reads health.control-plane-snapshot failed until it writes its first snapshot ten minutes later. The gate names both in its log line when it passes. A third is let by only while the roll is partway: the leader re-finishes the stored renders once every member runs its build, so app.refinish warns on the leader’s reading while any member, as shc node ls reports it, isn’t on the target yet. The gate names the row and those members in its log line and doesn’t wait on it. Once every member runs the target the row holds the gate like any other. A node that gives shc doctor run no answer at all counts as a failure. The gate polls every 10s for up to ready_timeout.

The gate compares a row only when the reading from before the roll can speak for it. Three kinds of failing row can’t be compared, so they don’t hold the roll. The gate names them in its log line and prints each one with its findings as a warning in the apply’s output, under a summary naming the node:

  • A check the build being left doesn’t have (new in target).
  • A row of an existing check whose every failing finding declares new_in, the release that added that requirement, when that release is newer than the build being left and no newer than the target (new in target).
  • A row that read skipped before the roll, because the check hit its time limit or its node’s build doesn’t have it (unanswered before the roll).

A row leaves the comparison only on a reading from a node on the target build. Once this apply has read a row healthy on the target, a failure holds the roll. A check that declares roll_blocking holds it on the build that adds it, as nodeagent.boot-gate does. Anything the gate can’t read holds too: a new_in that is missing, empty or not a plain major.minor.patch, and a snapshot or rig build on either side of the roll.

After a restart the gate reads shc doctor run from a node already on the new build: one the roll took earlier, then the node it just restarted, and a peer still on the old build only when none of those answers. A node on the old build can fail a check just because it can’t read the new build’s answer. Each gate line names the host the reading came from, with its node and build, for example doctor read from 192.0.2.11 (incus01, build 0.1.23). A failure that only an old-build peer reads holds the gate, and if no node on the new build answers before ready_timeout the apply says so, naming that peer and its build. It doesn’t report the restarted node as failing its gate.

The gate holds on a row that fails or warns. A build since 0.1.38 grades a row by its worst finding (info, warn, fail); one before it printed fail for a warning and warn for an info-only row. The gate reads the worst finding beside the verdict, so a warning holds the roll from either build and an info row never does. An older provider rolling a 0.1.38 build reads its warn rows as passing: roll with a provider at least as new as the target.

The gate compares doctor rows by identity: the check and the node it answers for. A row that read only info when the roll began and fails or warns after the restart still holds the roll, since the target build may rate an old finding higher. Its line names the change with both verdicts, their findings’ severities and both builds, for example incus.root-pool on incus01 (...), raised from warn (info) on 0.1.21 to fail (warning) on 0.1.22 by the target build. A failing row that passed when the roll began says so. Letting a raised severity by takes a decision about that check, not a flag.

The first node that fails the gate stops the roll. The apply errors naming the node and the check that failed (node state, build, quorum or doctor), lists the nodes still on the previous build, and restarts nothing else in that apply. Fix the node and apply again: the roll continues from there, and a node already on the new build is gated, not reinstalled.

A peer the leader rolled writes no state of its own in that apply, so after a roll that stopped its state can still name the version it left. The leader’s error names those peers. Re-applying the version the roll was taking heals them: each reads “already on the target” and is gated.

A node records the new package.version in its own state only once it has passed its gate. The node that failed it keeps the version it had, with its installed_version reading the new build, and the apply warns that its health gate did not pass. So does a node whose daemon, or whose SSH, ran out of its budget after apt returned. The next plan proposes the version again, and applying it installs nothing on that node and gates it again. A failure after a passed gate, such as the membership re-poll, still records the new version.

Backing out is different. Every node’s installed_version is its own dpkg reading, and the provider follows the same rule as app package drift: show by default, take on request. With converge_package_version unset, a node whose reading isn’t package.version (a peer the stopped roll moved, or a deb installed by hand) shows under “Objects have changed outside of Terraform”, the plan warns naming both versions, and nothing is planned for it, because rolling it restarts its daemon. Set converge_package_version = true on the node and the plan rolls it onto package.version, in the same leader-last order and behind the same gate. So reverting package.version after a stopped roll moves the peers back only with the opt-in.

A peer still on the old version that no ssh.hosts entry reaches (a node behind a jump host) can’t be rolled by the leader. The apply warns, naming it, and that node rolls after the leader through its own resource.

The in-place upgrade’s two patience budgets

Section titled “The in-place upgrade’s two patience budgets”

Changing package.version installs that version by apt over SSH and then polls the node until its daemon answers again. That poll has two independent budgets, because two different things can go wrong and only one of them is the daemon’s fault:

AttributeDefaultBounds
ready_timeout10mTime the node spends answering over SSH while its daemon reports not-ready.
transport_timeout20mTime SSH itself spends unreachable: no channel, no shell, no answer.

A node is expected to be busy right after an upgrade: restarting the daemon re-reconciles every container on it, and a node carrying a hundred containers can drive load high enough that sshd cannot fork a shell. Time lost that way is billed to transport_timeout and never to ready_timeout, so a burst of unreachability cannot exhaust the daemon’s patience, and the roll re-dials rather than retrying a connection that already died.

Exhausting transport_timeout reports that the upgrade could not be confirmed: the .deb did install, and the daemon may be perfectly healthy; the check simply never got an answer. Verify on the node with systemctl is-active shc and journalctl -u shc | grep ready, then re-run the apply to continue the roll. Only ready_timeout expiring reports a failed upgrade, because only then did the daemon actually answer and refuse to become ready.

Raise transport_timeout on nodes with many containers; both accept Go duration strings ("45m", "90s").

Changing vault_password on the bootstrap node is an in-place rotation, never a replacement. Tainting the bootstrap node would not re-key anything: it is a re-genesis of the whole cluster (new node id, new raft membership, new cluster CA), and the provider used to prescribe exactly that. It no longer does.

What an apply does, in order:

  1. Pre-flight. The node’s boot-time auto-unlock credential is compared with the password terraform has recorded. If they disagree, somebody rotated out of band and the recorded value is stale, so the apply is refused before anything is touched, rather than sending a password the vault will reject. (vault_adopt_drop_in = true turns this refusal into a warning; see Recovering a stranded auto-unlock credential.)
  2. Rotate. The recorded password is proved to the daemon, which re-encrypts every secret and flips the replicated verifier in one transaction, then re-keys its peers. Peers it could not reach are named in the apply output; they pick the new master up on their next restart.
  3. Record. The new password is written to state the moment the daemon accepts it, before anything else in the apply can fail. A rotation that committed must never leave state naming a credential the vault has retired.
  4. Prove. The node’s auto-unlock credential is read back. If it still holds the old password the apply fails loudly: that node is one shcd restart away from a vault that comes back LOCKED with no auto-recovery, and running containers keep serving until the next deploy, so nothing else would tell you.

Requirements and consequences:

  • The ssh block is required. The rotation runs against the node’s own root-owned daemon socket, which the provider reaches over SSH. An adopt-path cluster rotates out of band with shc vault rotate, and must update the node’s boot-time credential too.
  • A re-apply with an unchanged password rotates nothing. Rotation is not idempotent and is never run speculatively.
  • vault_password must carry no leading or trailing whitespace. shc init trims what it reads, so a padded value would seal the vault under a different string than the node boots with. It is refused at plan time.
  • vault_password must contain no whitespace, line break, quote, backslash or percent sign. The bootstrap node auto-unlocks from a credential file the provider stages (LoadCredential=vault-unlock:). shc vault rotate refuses that same set (X400965VLTDRI) so a rotation does not mint a password a node still on the retired environment form cannot carry. The apply would succeed and the node would come back LOCKED at its first restart, which on a multi-node cluster is the engine-flip restart the first worker join triggers. Refused at plan time. Mint the password with random_password { special = false }, as the examples do. Only the SSH bootstrap path is checked: an adopt = true node never gets a drop-in.
  • Archives taken before a rotation stay sealed under the old password. Their secrets bundle does not follow the vault. Keep the old password until those archives have aged out.

Recovering a stranded auto-unlock credential

Section titled “Recovering a stranded auto-unlock credential”

A node’s auto-unlock credential can end up holding a password that is neither the one terraform recorded nor the one being installed. That node cannot unlock its vault at boot, and it is also the node that most needs to rotate. It happens three ways: it was down while the cluster rotated, an earlier rotation on a pre-v0.0.16 build left it behind, or its password is one the daemon’s own credential reader will not parse back (see the character restriction above), which reads as the same thing.

Both halves of the stack refuse to touch such a credential by default: the provider’s pre-flight, and the daemon’s own guard (X400965VLTDRI), a deliberate v0.0.16 breaking change. Silently overwriting a password nobody can account for is how a hand-repaired node gets quietly clobbered.

vault_adopt_drop_in = true is the opt-in that clears both, alongside a changed vault_password:

resource "shc_node" "boot" {
bootstrap = true
vault_password = var.vault_pw_new
vault_adopt_drop_in = true # recovery only; remove once applied
# ...
}
  • Leave it false unless you are recovering such a node, and unset it afterwards. Left on permanently, it lets a routine terraform apply silently overwrite a credential nobody can account for, exactly what the daemon’s refusal exists to prevent. The password it discards may be the only key to archives taken before the rotation that stranded the node; recover them first.
  • It never weakens the proof of the old password. The daemon still verifies the recorded password by crypto round-trip and refuses a wrong one (X401012VLTINV) whatever this is set to. What the flag waives is only the refusal to overwrite the file.
  • It modifies a rotation; it does not start one. With vault_password unchanged the apply does nothing at all.
  • It is bootstrap-only. A join node has no auto-unlock credential to adopt (the daemon never creates one), so setting it there is a plan-time error rather than a silent no-op.

The equivalent by hand, on the node itself, is shc vault rotate --adopt-drop-in.

A bootstrap node will not genesis a second cluster

Section titled “A bootstrap node will not genesis a second cluster”

Before the SSH engine runs shc init, the provider asks every address in this node’s cluster.ssh.hosts (or, absent that, the provider block’s ssh.hosts) for its cluster membership. If any of them answers as a live cluster and this machine is not itself a member of anything, the apply is refused with X409026SECCLS and nothing is installed.

The shape it closes: terraform state is lost or was never there, tofu apply runs from empty, the substrate hands the seed a fresh machine, and shc init succeeds on it, because a virgin box has no way to know an estate is still running next door. The remaining nodes join the new cluster, the old one is orphaned with all of its data, and terraform reports success. The peer set is what terraform knows and the node does not, which is why the check lives here and not in the daemon.

Genesis needs positive evidence that no cluster is there, so these keep working unchanged:

what the probe seeswhat happens
no host answers with a membershipgenesis: the ordinary first install
only this node answersgenesis: shc init is idempotent on an already-clustered node, so a retried apply resumes
this node and peers answergenesis: same resume; the machine is already a member of the cluster that answered
a peer answers, this node does notrefused X409026SECCLS

The refusal names the responding host, its membership, and every host as probed. To get past it: terraform import the running cluster, declare this machine as a join node instead, destroy the old estate, or set force_genesis = true if a second, independent cluster really is the intention.

Two limits, stated plainly. The check covers the SSH engine only: with adopt = true the node ran shc init from its own cloud-init before the provider ever saw it. And it can only see clusters somebody declared: if every machine in the peer set is new and the survivors are not in it, no signal reaches the provider at all. A peer reached only through a jump host is not in the peer set either, since the peers are dialled directly. Closing that needs a durable cluster id nodes carry, which SHC does not yet mint.

resource "shc_node" "bootstrap" {
bootstrap = true
name = "node-1"
host = "198.51.100.10"
runtime = "docker"
package = { version = var.shc_version }
ssh = { user = "admin", private_key = var.ssh_key, host_key = var.node_1_host_key }
host_domain = "cloud.example.com"
vault_password = var.vault_pw
}

A tofu destroy of an shc_node issues the destroy-time shc node forget. When deployment rows still name that node the daemon refuses with X400017NODDEP, and the provider hard-fails the destroy, carrying the daemon’s refusal (which names the occupying stacks) through verbatim (ruling M7, docs/decisions/2026-08-14-models-rulings.md). The diagnostic also states Nothing was destroyed, because nothing was: shc_node destroys strictly before the substrate resource that deletes its machine (the node depends on its server), so the refusal stops the whole teardown with the containers, volumes and deployment directories still on disk.

There are exactly two ways through, and both are stated by the operator:

what to dowhen
Relocateshc node drain <name>, then destroy. Drain moves every deployment bound to the node, running or stopped. Clear whatever it still leaves with shc uninstall <stack>.Whenever the estate survives the node.
Consentset on_destroy = "force" on the resource and apply it, then destroy.Whole-estate teardown, where the stacks are going too.

With the consent the forget is issued twice: unforced first, so the operator still gets the daemon’s listing, then re-issued with the occupancy override, and the destroy raises exactly one warning naming the stacks it orphaned, plus shc uninstall as the verb that clears the rows. Nothing is evicted, moved or backed up.

Three properties worth stating outright:

  • on_destroy is read from STATE, like aws_s3_bucket.force_destroy. Setting it in config and going straight to tofu destroy does not work: tofu apply first, then destroy.
  • The value space is closed at plan time. Only the exact string "force" consents; "Force", "yes" and "drain" are ValidateConfig errors rather than values that read as absent at destroy time.
  • Only the occupancy refusal is overridden. The quorum-deficit (X409201CLSRMQ) floor is untouched by on_destroy; forcing past those would wedge the cluster the operator is keeping. Unrelated transport failures are likewise not retried. The bootstrap node is not special: its teardown tolerance absorbs transport failures only, never this refusal, and it consents the same way.
  • Another suffrage change is waited out. A whole-cluster teardown forgets its nodes in parallel, and the daemon refuses a forget while another membership change is in flight (X409216CLSSUB). The provider asks again every 5 seconds for up to 5 minutes, with or without on_destroy, and reports the refusal only if it still stands then.

A whole-estate teardown does not set this per resource by hand: every terraform/modules/shc/<cloud> front door and modules/core carry a single on_destroy variable down to every node (see the module library).

There is no implicit path. The pre-M7 provider warned and forced by itself; that behaviour is removed, not deprecated.

An SHC tenant and its realm. An optional vault_connection routes that tenant’s app secrets to an external vault-capable connection; omit it for the local vault (system-tier secrets always stay local).

ArgumentTypeRequiredDescription
clusterblocknoPer-resource cluster/transport override.
namestringyesTenant name. Forces replacement.
vault_connectionstringnoName of a vault-capable shc_connection backing this tenant’s secrets; omit for local vault.

Exports: active (bool), provisioning_warning (string), id (= name).

resource "shc_tenant" "acme" {
name = "acme"
}

An SSO user in a tenant’s Keycloak realm plus a managed (non-authoritative) set of role grants and of realm groups. Requires the system Keycloak (user_management capability).

ArgumentTypeRequiredSensitiveDescription
clusterblocknon/aPer-resource cluster/transport override.
usernamestringyesnoUsername in the tenant realm (Keycloak lowercases it). Forces replacement.
namestringyesnoThe person’s full name, as shc user create takes it: the last word is Keycloak’s lastName and the words before it its firstName, so it needs two words or more. Keycloak refuses the password grant to a user missing either name. A change runs shc user rename in place: the user keeps its Keycloak id, credentials, roles and groups. Read back from Keycloak, so a name changed there plans a rename back.
tenantstringyesnoTenant whose realm owns the user; an estate has no default tenant. Forces replacement.
emailstringyesnoUser email, required because Keycloak 26 refuses password sign-in without one with “Account is not fully set up”. A change forces replacement because SHC has no email update verb.
passwordstringnoyesThe user’s password; write-only. A change runs shc user reset-password in place. Unset, the user is created without a password and state holds none: the person sets their own with shc user reset-password <username> -t <tenant> on a node. Taking a set password out of the configuration leaves the live one as it is.
grantsset(string)nonoRoles to grant: a realm’s access roles (tenant:manage, tenant:operate, tenant:read, tenant:use, tenant:deny, audit:read, events:read), platform:manage on master, and a deployment’s stack:<name>, alone or with :use, :read, :operate, :manage or :deny. Any of these but platform:manage can be qualified as <tenant>/<role> for a tenant auth.trusted_realms maps the realm to, e.g. public/tenant:manage. An entry the realm does not grant fails the apply with the daemon’s X400933USRROL, which names the entry and the roles that exist. Only listed roles are managed. Read back from the roles mapped on the user (shc user ls’s direct_roles), so a listed role revoked out of band plans a grant again, even while a group still carries it. Left out, the user’s roles are left as they are; grants = [] revokes the ones it manages.
groupsset(string)nonoGroups of the tenant’s realm the user is a member of, by name. Only listed groups are joined and left; a membership made elsewhere, the realm’s default group among them, is left alone. A group that does not exist fails the apply, and the error names it, so refer to an shc_user_group’s name.
on_destroystringnonoDestroy-time consent to remove the last manager of a tenant or the last platform admin, as shc_node’s on_destroy is for an occupied node. Unset, the daemon’s refusal (X409930USRLMG, X409931USRLPA) fails the destroy and nothing is removed. "force" re-issues the delete with --force-last-admin and the destroy warns. Read from state: apply it before the destroy. The only accepted value is "force".

Exports: id (= <username>/<tenant>, also the import id). An import id with no tenant is refused.

Import adopts the user’s direct roles as grants, so a configuration that lists them, or states no grants, plans no changes; a stated grants that does not list one plans its revoke. groups and password are not imported: a configured one plans an in-place update. email is read, and a configured one that differs plans a replacement. Import takes the user’s live names as name.

resource "shc_user" "alice" {
username = "alice"
name = "Alice Liddell"
tenant = shc_tenant.acme.name
password = var.alice_pw
grants = ["tenant", "stack:gitea:operate"]
}

A group of a tenant’s Keycloak realm. It holds users, put there with shc_user’s groups. Over the LDAP face it is cn=<name>,ou=groups,ou=<tenant>,<base DN>, and a member’s entry names it in memberOf.

Three names are SHC’s own in every tenant realm, and this resource neither makes, adopts nor removes them; the apply is refused. shc-app-access is the group every new user joins, and its role mappings are the realm’s default access. shc-admins and shc-users are seeded by the Keycloak image with the realm roles tenant:manage and tenant. A user is put in one of the three with shc_user’s groups, like any other group. SHC reads no meaning into any other name: what such a group stands for is decided by whatever reads it.

A group can carry roles, mapped in Keycloak. Putting a user in one that does is a grant, so it goes through the gate a grant of each role goes through. Taking a user out of it, or destroying it, is refused when that would leave the tenant with no manager (X409930USRLMG for a user; a group’s refusal names everyone who holds tenant:manage only through it). Grant tenant:manage to a user directly first.

ArgumentTypeRequiredDescription
clusterblocknoPer-resource cluster/transport override.
namestringyesThe group’s name: lowercase letters, digits, ., _ and -, starting with a letter or digit, at most 64 characters. Lowercase only, because a DN compares case-blind: Admins and admins would be one group to a memberOf filter and two to Keycloak. A group made in Keycloak with capitals is not one SHC states. Forces replacement, and the members leave with the old group.
tenantstringyesTenant whose realm holds the group; an estate has no default tenant. Forces replacement.

Exports: id (= <name>/<tenant>, also the import id). An import id with no tenant is refused.

A group that is already there is adopted. One removed by hand is dropped on refresh and made again on the next apply; its members are put back by the shc_user resources that list it. Destroy removes the group.

resource "shc_user_group" "gateway_admins" {
tenant = shc_tenant.acme.name
name = "gateway-admins"
}
resource "shc_user" "alice" {
tenant = shc_tenant.acme.name
username = "alice"
name = "Alice Liddell"
groups = [shc_user_group.gateway_admins.name]
}

A service client: a confidential client in the cluster’s master realm with only the client_credentials grant, for automation such as the shc-cluster CI template (cicd templates/shc-cluster.yml). Every token it mints is platform root. The cluster shows its secret once, at create or at a rotation, and the resource keeps it in state as a sensitive value: the state is then a secret store, as it already is for vault_password.

ArgumentTypeRequiredDescription
clusterblocknoPer-resource cluster/transport override.
namestringyesThe client id: lowercase letters, digits, ., _ and -, starting with a letter or digit, at most 64 characters. The platform’s own clients are refused. Forces replacement.
token_lifespannumberno (default 3600)Access-token lifespan in seconds, 60 to 86400. Forces replacement.
rotate_triggerstringnoAny string. A change regenerates the secret in place; the old one stops working at once.

Exports: client_id, client_secret (sensitive), id (= name).

Create refuses a name that already exists on the cluster: its secret cannot be read back, and adopting it would mean rotating a secret this resource did not make. Remove such a client with shc auth delete-service-client <name>. A client removed by hand is dropped on refresh and made again on the next apply. Import is refused for the same reason create refuses an existing name. Destroy removes the client.

The outputs the shc-cluster template’s before_script reads:

resource "shc_service_client" "deploy" {
name = "deploy"
}
output "shc_endpoint" {
value = "https://${var.cluster_host}"
}
output "shc_client_id" {
value = shc_service_client.deploy.client_id
}
output "shc_client_secret" {
value = shc_service_client.deploy.client_secret
sensitive = true
}
# Empty when the cluster host carries a publicly trusted certificate: the
# template then uses the system CA bundle.
output "shc_ca_pem" {
value = module.core.cluster_ca_pem != null ? module.core.cluster_ca_pem : ""
}

A standalone OIDC client in a tenant realm, for an external application or identity broker. It requires platform:manage. The master realm, reserved platform clients and clients owned by a deployment are refused.

ArgumentTypeRequiredDescription
clusterobjectnoSame per-resource connection override as shc_service_client, including SSH.
tenantstringyesTenant realm. Forces replacement.
client_idstringyesClient identifier within the tenant. Forces replacement.
redirect_urisset(string)yesAllowed callback URIs. Must contain at least one element.
web_originsset(string)no (default [])Allowed browser origins. Omitting it clears existing origins on apply.
authenticationstringyesclient-secret or client-jwt. Forces replacement; the API refuses an in-place change with X409956OIDAUT.
jwks_urlstringfor client-jwtAbsolute HTTPS JWKS URL without userinfo or a fragment. Must be unset for client-secret.
signing_algstringfor client-jwtRS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384 or ES512. Must be unset for client-secret.
standard_flow_onlyboolno (default true)Only true is accepted. Refresh reads the live value. An extra flow or grant produces a false -> true update, and apply repairs it with PUT.

Exports id, exactly <tenant>/<client_id>, and client_secret (sensitive). The secret comes only from the create response of a client-secret client and stays in state across refreshes and updates. It is null for client-jwt and after import. No API returns it again; that is deliberate. Protect the state as a credential store.

Create uses a strict POST. If the client exists, import it instead. Import reads the live configuration for either authentication mode, so matching HCL plans no changes without retrieving a credential. Changes to redirects, origins or JWT settings use PUT. Destroy uses DELETE.

Refresh removes state only for X404951OIDNOF (missing client) or X404916AUTRLM (missing realm). Ownership refusals, unavailable Keycloak and malformed replies return errors and retain state. Delete tolerates those same two absence codes; every other refusal fails the operation.

Over SSH the resource runs shc auth create-oidc-client, get-oidc-client, update-oidc-client and delete-oidc-client with the client id, -t <tenant> and -o json. An empty origins set sends --web-origin=. Response output is never included in an error because creation can return a secret.

resource "shc_oidc_client" "promanager_corp" {
tenant = "corp"
client_id = "promanager-corp"
authentication = "client-jwt"
redirect_uris = [
"https://auth.corp.promanager.vip/realms/corp/broker/bitspur/endpoint",
]
jwks_url = "https://auth.corp.promanager.vip/realms/corp/protocol/openid-connect/certs"
signing_alg = "RS256"
}
import {
to = shc_oidc_client.promanager_corp
id = "corp/promanager-corp"
}

The import block requires an existing client. Omit it to create a new one. See the runnable example.

An external OIDC identity provider in master or a tenant realm. Requires platform:manage and the sso entitlement. On master it links existing users only, because every master identity is platform root.

ArgumentTypeRequiredDescription
clusterobjectnoSame per-resource connection override as shc_oidc_client, including SSH.
tenantstringyesMaster or a tenant realm. Forces replacement.
aliasstringyesProvider alias within the realm. Forces replacement.
display_namestringno (default "")Login screen label. Omitting it clears the label on apply.
issuerstringyesAbsolute HTTPS OpenID issuer URL without userinfo, a query or a fragment.
client_idstringyesClient identifier registered at the external issuer.
authenticationstringyesclient-jwt or client-secret. Changes update the provider in place.
signing_algstringfor client-jwtRS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384 or ES512. Must be unset for client-secret.
client_secret_refstringfor client-secretA ref+vault:// reference, not a secret value. Must be unset for client-jwt. The reference is not sensitive; the secret never reaches Terraform.
sync_modestringno (default import)import, legacy or force.
first_loginstringno (default link-only)link-only or create. Master refuses create.
enabledboolno (default true)Only true is accepted. Refresh reads the live value; a provider disabled in Keycloak or by its federation guard plans false -> true, and apply re-enables it.

Exports id, exactly <tenant>/<alias>. Create uses a strict POST. An existing provider returns X409963IDPEXS with an instruction to import it. Import reads every managed field, including client_secret_ref, so matching HCL plans no changes for either authentication mode. Updates send every managed field through PUT; destroy uses DELETE.

Refresh stores authentication = "other" and first_login = "custom" when Keycloak reports hand-edited settings. The plan shows the change back to the declared configuration, and apply repairs it. Refresh removes state only for X404957IDPNOF (missing provider) or X404916AUTRLM (missing realm). X503958IDPKCN (Keycloak unavailable) warns and retains state. Gate refusals and malformed responses return errors and retain state. Delete treats only those two absence codes as success.

SSH runs shc -o json auth {create,get,update,delete}-identity-provider <alias> -t <tenant>. Writes always send --authentication client-jwt=<alg> or --authentication client-secret=<ref>, plus all managed settings. An empty label sends --display-name=. Response output stays out of diagnostics.

resource "shc_identity_provider" "bitspur" {
tenant = "master"
alias = "bitspur"
display_name = "bitspur"
issuer = "https://auth.corp.bitspur.com/realms/corp"
client_id = "promanager-master"
authentication = "client-jwt"
signing_alg = "RS256"
first_login = "link-only"
}
# Uncomment to adopt a provider made by hand.
# import {
# to = shc_identity_provider.bitspur
# id = "master/bitspur"
# }

See the runnable example.

An LDAP bind for a consumer SHC does not run: a firewall, a NAS, a host’s SSSD. It is the identity that consumer binds to the system Keycloak’s LDAP face as. The cluster makes it with the ldap socket’s own jobs, the ones an installed app’s ldap plug runs, so the bind reads its own tenant’s users and groups and is refused anything of another tenant.

ArgumentTypeRequiredDescription
clusterblocknoPer-resource cluster/transport override.
namestringyesThe consumer’s name: lowercase letters, digits, ., _ and -, starting with a letter or digit, at most 64 characters. It is the cn of the bind DN. Forces replacement.
tenantstringyesTenant whose users and groups the bind reads. master is refused: its accounts are the platform’s own and its realm has no lockout, so a consumer’s login page in front of it would guess at them unthrottled. Forces replacement.
rotate_triggerstringnoAny string. A change regenerates the bind’s secret in place and puts the new password in state; the old one is then refused for a new bind.

Exports: dn (cn=<name>,ou=services,ou=<tenant>,<base DN>), password (sensitive), base_dn, users_dn (ou=people,ou=<tenant>,<base DN>), groups_dn (ou=groups,ou=<tenant>,<base DN>), id (= <name>/<tenant>).

Three things have to be true first. The LDAP face is on (modules.keycloak.vars.enableLdap: true). A new bind is an ldap edge, which the sso entitlement covers, as it does for an app’s ldap plug. And the consumer can reach port 636: on a cluster whose fabric is shc that is an shc_stack_ports on the system Keycloak, as below.

Port 636 has to be reachable from the consumers’ network and from nowhere else. shc_stack_ports publishes it on every node, and SHC puts no source filter in front of it. Whoever can reach it can try passwords against any user of any realm by binding, with no consumer in between. Master’s users are among them, and master has no lockout. Limit the port to the consumers’ addresses at the hosts’ firewall or at the edge before it is published.

The cluster shows a bind’s password when the bind is made and when its secret is rotated, and does not read it back, as with a service client. So create refuses a name that is already there: its password cannot be read, and adopting it would mean rotating a secret a consumer is using. Remove such a bind with shc auth delete-ldap-bind <name> -t <tenant>, or state it under another name. Import is refused for the same reason. A bind removed by hand is dropped on refresh and made again, with a new password, on the next apply. A client of the realm that is not an LDAP bind is never taken over, and a bind that an installed app holds through its own ldap plug is that app’s: the cluster refuses to make, rotate or remove it here.

If the secret was regenerated outside this resource, with shc auth create-ldap-bind <name> -t <tenant> --rotate-secret or in Keycloak, the password in state no longer binds and the plan is still empty: the cluster cannot tell the two apart. Change rotate_trigger, or taint the resource, to put a password that binds back in state.

Destroy removes the bind. A new bind with its password is refused from then on: at the first attempt, within a second, each of the three times it was measured on the shipped image. A connection that was already bound is not cut. It stays bound and keeps reading until it closes, and one read on for the hundred seconds it was watched, so restart or reconfigure the consumer to end it.

A user binds with their own password, which Keycloak checks as a password grant. An account with a one-time code, with a pending required action, or with no email cannot bind: for the last Keycloak answers that the account is not fully set up. Repeated wrong passwords lock the account for a while, as they do on the realm’s own login page: SHC turns on Keycloak’s brute force detection with a temporary lockout for every realm but master, unless the estate sets keycloak.brute_force_detection to false. How many and how long are Keycloak’s defaults, which SHC does not write: on 26.7, thirty wrong passwords in a row, or two inside a second, lock the account for a minute. The bind’s own password is a client secret and is not locked out.

The lockout has a cost. Anyone who knows a username can keep that account locked by sending two wrong passwords a minute at any login page in front of the realm, the consumer’s included. An estate that would rather be guessed at than locked out turns the key off; it is then off on every tenant realm.

Any user of the realm with a password can bind as themselves. A consumer keeps the rest out by searching with a group filter, as in the example below. The LDAP face keeps its index of a realm for 30 seconds, so a user put in a group or taken out of it shows there up to 30 seconds later. That index is not what ends a removed bind: see above.

The face also answers the LDAP Password Modify operation. It changes a user’s password for whoever names the user and gives that user’s current password, on a connection that is bound as anyone or as nobody, and for no one else. A bind gains nothing by it: without the user’s current password it is refused, and it cannot change its own secret that way. A wrong current password counts toward the lockout like a wrong bind.

A gateway that logs its admins in against the realm

Section titled “A gateway that logs its admins in against the realm”
resource "shc_config" "platform" {
yaml = <<-EOT
modules:
keycloak:
vars:
enableLdap: true
EOT
}
# LDAPS on every node. Nothing here limits who reaches it: the hosts'
# firewall or the edge must already allow 636 from the gateway alone.
resource "shc_stack_ports" "keycloak" {
depends_on = [shc_config.platform]
tenant = "master"
stack = "keycloak"
ports = { "636" = { service = "keycloak" } }
}
resource "shc_user_group" "gateway_admins" {
tenant = shc_tenant.acme.name
name = "gateway-admins"
}
resource "shc_user" "alice" {
tenant = shc_tenant.acme.name
username = "alice"
name = "Alice Liddell"
groups = [shc_user_group.gateway_admins.name]
}
resource "shc_ldap_bind" "gateway" {
depends_on = [shc_stack_ports.keycloak]
tenant = shc_tenant.acme.name
name = "gateway"
}
output "ldap" {
value = {
url = "ldaps://${var.cluster_host}:636"
bind_dn = shc_ldap_bind.gateway.dn
base_dn = shc_ldap_bind.gateway.base_dn
users_dn = shc_ldap_bind.gateway.users_dn
admins = "(memberOf=cn=${shc_user_group.gateway_admins.name},${shc_ldap_bind.gateway.groups_dn})"
}
}
output "ldap_bind_password" {
value = shc_ldap_bind.gateway.password
sensitive = true
}

The gateway is given the URL, the bind DN and its password, users_dn as the place to look a login up by uid, and the admins filter so that only a member of the group gets in. Alice has an email, without which she could not bind, and no password yet. She sets one on a node:

Terminal window
shc user reset-password alice -t acme

The same without Terraform:

Terminal window
shc user group add gateway-admins -t acme
shc user create alice "Alice Liddell" [email protected] -t acme
shc user join alice gateway-admins -t acme
shc auth create-ldap-bind gateway -t acme

A typed connection to an external backend (route53, hetzner, cloudflare, pfsense, s3, aws, gcp, …). Its type declares which capability providers it lights up; creating it escrows the credentials to the vault and probes each capability, exposed as computed booleans.

ArgumentTypeRequiredSensitiveDescription
clusterblocknon/aPer-resource cluster/transport override.
namestringyesnoConnection name. Forces replacement.
typestringyesnoConnection type (e.g. route53, hetzner, cloudflare, pfsense, s3, aws, gcp).
tenantstringno (default master)noOwning tenant. Forces replacement.
credentialsmap(string)noyesCredential fields per type (write-only). An endpoint key is passed as the backend endpoint rather than a secret.
zoneslist(string)nonoFor DNS connections: the zones this connection manages.

Exports (capability booleans + probed zones): dns, local_dns, proxy, ca_signer, restic, volume, dns_zones (list), id (= tenant/name).

resource "shc_connection" "dns" {
name = "cloudflare"
type = "cloudflare"
credentials = { token = var.cf_token }
zones = ["example.com"]
}

Authorises a connection to mint a capability’s scoped sub-credential for a grantee tenant (shc connection grant). A deployment binding is refused without a matching grant (X403910CONGRT).

ArgumentTypeRequiredDescription
clusterblocknoPer-resource cluster/transport override.
connection_namestringyesThe connection being shared (bare connection is a reserved root name). Forces replacement.
capabilitystringyesCapability the grantee may mint (e.g. aws-iam, s3-bucket). Forces replacement.
granteestringyesTenant authorised to mint. Forces replacement.
tenantstringno (default master)The connection’s owning tenant. Forces replacement.
boundary_policystringno, except on HELD capabilitiesPermissions boundary as inline JSON; the one in-place mutable attribute (re-apply re-scopes). Required for s3 and llm; see below.

Exports: id (= tenant/connection/capability/grantee).

resource "shc_connection_grant" "aws_iam" {
connection_name = shc_connection.aws.name
capability = "aws-iam"
grantee = shc_tenant.acme.name
boundary_policy = file("./boundary.json")
}

The s3 and llm capabilities are holds: with no scope in play they serve the connection’s OWN credential to the grantee, which on a real estate meant a tenant app receiving the account root object-store key. So on those two, boundary_policy is required and speaks a scope document rather than a backend policy: a grant without one is refused with X403922CONUNS.

# Mint a credential restricted to named buckets (where the endpoint's backend
# can mint one: Exoscale SOS today).
resource "shc_connection_grant" "acme_s3" {
connection_name = shc_connection.exos3.name
capability = "s3"
grantee = shc_tenant.acme.name
boundary_policy = jsonencode({ buckets = ["acme-data"] })
}
# Or state in writing that the connection's own credential is what the grantee
# gets: the honest option for a backend that cannot narrow a credential.
resource "shc_connection_grant" "acme_s3_unscoped" {
connection_name = shc_connection.hz_s3.name
capability = "s3"
grantee = shc_tenant.acme.name
boundary_policy = jsonencode({ unscoped = true })
}

A remote SHC app repository (git or https). Repos are remote-only so any node can materialize apps on demand; a file:// URL is rejected at plan time.

ArgumentTypeRequiredSensitiveDescription
clusterblocknon/aPer-resource cluster/transport override.
namestringyesnoRepository name. Forces replacement.
urlstringyesnoRemote repo URL (https://… or git+…). Forces replacement.
tokenstringnoyesAccess token for a private repo (write-only). Forces replacement.
tenantstringnonoOwning tenant. Forces replacement.
environmentstringnonoOwning environment. Forces replacement.
priorityintno (computed)noResolution priority (higher wins).
sync_intervalstringnonoAuto-sync interval (Go duration, e.g. 1h); omit to disable.

Exports: app_count (int), synced_at, created_at, updated_at (RFC3339 strings), id (= name).

resource "shc_repo" "shc" {
name = "shc"
url = "https://selfhostedcloud.org/apps/0.1/index.yaml"
}

A repo is its tenant, environment and name together, and two tenants may each hold one of the same name. Read, update and delete name all three: an unset tenant or environment is the system scope. Import with terraform import shc_repo.shc shc for a system repo, terraform import shc_repo.apps acme/apps, or terraform import shc_repo.apps acme/prod/apps.

One installed app instance (install / update), the canonical way to deploy an app declaratively. App source is structured: repo (a repo name; absent = default catalog) plus the bare app name (no positional repo/app). Schema version 4 (hosts became routes).

ArgumentTypeRequiredDescription
clusterblocknoPer-resource cluster/transport override.
tenantstringyesOwning tenant; an estate has no default tenant. Forces replacement.
repostringnoCatalog repo name to resolve app from; absent = default resolution. Forces replacement.
appstringyesBare catalog app name (never slash-qualified). Forces replacement.
stackstringno (computed)Stack name; defaults to the app base name. Forces replacement.
environmentstringno (default default)Environment. Forces replacement.
varsmap(string)noApp variables; sent in full each apply.
addonstringnoAdd-on to apply: the name of an addons/<name>.addon.yaml in the app that declares no vapp:.
storagestringnoStorage provider for volumes; install-time only. Forces replacement.
acme_providerstringnoNamed ACME provider issuing public certs; blank = cluster default. Changeable in place: the daemon re-issues under the new CA without a recreate.
runtimestringnoTarget runtime: docker, podman, incus, or apple; install-time only. Forces replacement.
scalemap(int)noPer-service replica counts.
publicboolno (default false)--public: expose to the internet.
gatedboolno (default false)--gated: put Keycloak SSO in front.
integratemap(block)noProvider bindings keyed by plug (see below).
connectionsmap(block)noConnection bindings keyed by the app’s declared binding name (see below).
portsmap(block)noL4 port mappings keyed by "external[/udp]" (see below).
routesmap(block)noL7 HTTP routes keyed by "hostname[/path]" (see below).
nodestringno (computed)Install-time placement pin; not changeable in place.
ttlstringnoLease duration (Go duration, e.g. 72h); re-applying the same value renews. Refused on protected environments.
wait_healthyboolno (default true)Block Create/Update on deployment health.
protectedboolno (default false)Destroy guard (X409001DEPROT): refuses uninstall/destroy only; the deployment can still be moved and drained (ruling P9).
on_destroystringnoDestroy-time consent to uninstall without a safety backup, as shc_node’s on_destroy is for an occupied node. Unset, a destroy whose safety backup failed or left no usable archive is refused by the daemon (X409012DEPNOB, X409007DEPNOA), the destroy fails and nothing is removed. "force" re-issues the uninstall with --no-backup and the destroy warns: no archive is taken and the deployment’s block volumes are kept. Setting or clearing it sends the daemon nothing, so it restarts nothing. Read from state: apply it before the destroy. It never lifts protected. The only accepted value is "force".
refresh_app_packageboolno (default false)Standing consent to TAKE app-package drift. See “App package drift” below.

Nested value shapes:

  • ports (key "external[/udp]"): service (string), container (int), connection (string: proxy-capable connection for LB exposure; absent = node publish).
  • routes (key "hostname[/path]"): service (string), port (int). There is no target; the daemon infers the DNS endpoint.
  • integrate (key = plug name): stack XOR connection, plus optional environment (only with stack).
  • connections (key = the app’s declared binding name): connection (string, required), which needs a matching shc_connection_grant.

Exports: status, healthy (bool), node, lease_expires_at (RFC3339; empty when ttl unset), id (= tenant/environment/stack), groups (group name to its members, each with n, location and services; empty when the app has no {% members %} block), plus the app-package drift trio below.

Import with terraform import shc_deployment.gitlab corp/prod/gitlab. app backfills from the first read (the daemon echoes app_name), the same way shc_vdeployment backfills vapp, so the plan after an import is never a REPLACEMENT. It used to be: app and repo are both RequiresReplace, neither was filled, and null → value on such an attribute plans a replace, so importing a live stack planned to uninstall it. repo is the one attribute no transport reports at all, so it is adopted from config rather than refreshed and only a change between two RECORDED repos replaces. vars/routes/ports/integrate/connections/addon/ storage/runtime stay config-only exactly like shc_vdeployment’s, so the first plan after an import is an in-place UPDATE, not a no-op, and that update re-renders the stack, discarding any out-of-band hand edit to its deployed compose.yaml.

status is a ROLLUP that converges out-of-band on a leader cron, so it lags the containers it describes. The same status response also carries services[], stamped from a live engine probe on the answering node. The wait settles on EITHER: the rollup reaching running/complete, or every observed service reading running-and-not-unhealthy with its replicas scheduled. The second signal only ever brings a positive verdict FORWARD: a service still running its healthcheck, an exited one-shot, a deployment with only some replicas ready or a service slice nothing has probed all keep the wait polling, so a deployment that is not settled can never be talked into healthy by it. healthy (bool) follows the same pair, so the signal that ends the wait is the signal recorded in state.

Each poll read is bounded independently (60s). Exceeding that bound is reported as a slow read, not as a failed deployment, and the poll retries; healthy is never inferred from a read that did not answer. A timeout is always pronounced on a read issued at or after the deadline, and its message names how many reads ran long; a wait that gives up because the daemon’s status aggregate is slow says so, instead of blaming the app.

A release can change how an app is PACKAGED (a memory limit, a compose fragment, a var default) without changing the app’s upstream version. Nothing re-renders a running deployment when that happens, so before these attributes existed the provider held no fact that had moved and tofu plan correctly reported “No changes” through a release that had repackaged every app.

ExportMeaning
app_digestContent identity (apppkg-v1:<sha256>) of the app this deployment was last RENDERED from. Empty = none recorded; never “current”.
app_package_availableIdentity the catalogue would render for it RIGHT NOW, resolved with the same repo and version pin an update would use. Empty = the catalogue could not be resolved.
app_package_driftcurrent, stale, or unknown. Three values: unknown means one or both identities could not be established and is deliberately NOT folded into current.

Default posture: SHOW, do not take. With refresh_app_package unset (or false), a catalogue change surfaces during REFRESH and the plan stays empty:

Note: Objects have changed outside of Terraform
# shc_deployment.affine has changed
~ resource "shc_deployment" "affine" {
~ app_package_available = "apppkg-v1:1f0c…" -> "apppkg-v1:9b73…"
~ app_package_drift = "current" -> "stale"
# (17 unchanged attributes hidden)
}
No changes. Your infrastructure matches the configuration.

Take it per deployment with shc update <stack> (which re-renders and RESTARTS the stack), or estate-wide by setting refresh_app_package = true, which turns a stale verdict into a planned in-place update:

# shc_deployment.affine will be updated in-place
~ resource "shc_deployment" "affine" {
~ app_digest = "apppkg-v1:1f0c…" -> (known after apply)
# (17 unchanged attributes hidden)
}
Plan: 0 to add, 1 to change, 0 to destroy.

Only stale plans an action. An unknown verdict never does: re-rendering every deployment because a registry was unreachable would be acting on the absence of information.

Fleet-wide, shc doctor run reports the same thing as app.package-drift, listing stale and unestablished deployments separately and always naming how many it examined. shc update --check <stack> explains one deployment’s verdict without changing anything.

resource "shc_deployment" "gitea" {
tenant = shc_tenant.acme.name
repo = shc_repo.shc.name
app = "gitea"
public = true
routes = { "git.example.com" = { service = "web", port = 3000 } }
ports = { "22" = { service = "web", container = 22 } }
}

A deployment with ttl set never converges to an empty plan: every apply re-stamps the lease (like GitLab’s auto_stop_in). That is by design. vars/ports/routes/integrate are authoritative-from-config: the provider sends the full desired sets plus explicit removals each apply, but removing a connections key is a documented no-op until connection-detach lands.

One installed vApp instance (a vdeployment) inside an already-deployed host stack: postgres/database, keycloak/realm, nextcloud/plugin, s3/bucket and friends. Every name attribute is bare: the provider composes the CLI’s <parent>/<vapp> and <host>/<instance> slash tokens itself, so no attribute ever carries a / (the same structured-surface posture as shc_deployment’s bare app + repo split). The lifecycle is create / read / delete only; a vdeployment has no in-place update, so every attribute forces replacement (uninstall + reinstall of the instance).

The create gate asserts the host stack exists (deployed), never that it is healthy: a stopped host fails the install with the integration job’s real error rather than a synthetic pre-check. Reference the host’s shc_deployment so terraform orders the two resources.

Served over both transports, like every other platform resource. Over SSH the create is shc install <parent>/<vapp> --into <host> --instance <instance>, the delete is shc uninstall <host>/<instance>, and the status read is shc ls, which folds the vdeployment registry rows into its listing, one per instance, named <host>/<instance> and carrying the instance’s own queued → installing → running (or failed, with its error_message) lifecycle. That is the same row the HTTP path’s shc.stack.status answers from, so wait_healthy is equally row-backed on either transport. (Earlier releases refused SSH here on the mistaken premise that the row-backed read had no SSH equivalent, which made a vApp instance undeclarable on an SSH-only estate.)

ArgumentTypeRequiredDescription
clusterblocknoPer-resource cluster/transport override. Both transports, same precedence as every other resource.
tenantstringyesThe HOST’s tenant; an estate has no default tenant. Forces replacement.
environmentstringno (default default)The HOST’s environment.
host_stackstringyesName of the deployed host stack (e.g. shc_deployment.pg.stack). Bare name.
vappstringyesThe vApp template name as the host’s app declares it (database, realm, plugin, bucket). Bare name; the parent app half of the wire token is read from the host itself.
instancestringyesInstance name, unique per host. Bare name.
addonstringnoAdd-on to apply: an addons/<name>.addon.yaml in the host’s app that declares vapp: <this vapp>.
addon_versionstringnoVersion key inside the add-on’s versions: map (omit = the add-on’s default).
varsmap(string)novApp variables (vvars), applied over the add-on’s resolved vars.
integratemap(block)noIntegrations keyed by consumer plug (same shape as shc_deployment.integrate).
wait_healthyboolno (default true)Wait for the instance’s registry row to reach running; failed fails the apply with the row’s error.

Exports: id (= tenant/host_stack/environment/instance, the import id format), status (the row’s resolve-half lifecycle: queued → installing → running, or failed), host_app (the host stack’s app name, the parent half of <parent>/<vapp>, read from the host, never configured).

resource "shc_deployment" "pg" {
tenant = shc_tenant.acme.name
app = "postgres"
stack = "pg-main"
}
resource "shc_vdeployment" "appdb" {
tenant = shc_tenant.acme.name
host_stack = shc_deployment.pg.stack
vapp = "database"
instance = "appdb"
vars = { database = "appdb" }
}

A vdeployment is deployment-shaped, not deployment-stored: it has no containers, no placement and no service health of its own: status is its install lifecycle, and there is deliberately no healthy export. Import with terraform import shc_vdeployment.appdb default/pg-main/default/appdb; vapp, host_app and status backfill from the first read, while addon/vars/integrate are config-only exactly like shc_deployment’s desired sets.

Manages only the L4 port mappings on an already-existing stack (never installs or uninstalls). The named stack must already exist (e.g. the system Traefik stack every cluster ships at init). This is how the core module’s “lb” topology attaches a connection-backed LB exposure to the system Traefik declaratively.

ArgumentTypeRequiredDescription
clusterblocknoPer-resource cluster/transport override.
tenantstringyesOwning tenant; an estate has no default tenant. Forces replacement.
environmentstringno (default default)Environment. Forces replacement.
stackstringyesThe existing stack to attach mappings to. Forces replacement.
portsmap(block)noPort mappings keyed by "external[/udp]" (same shape as shc_deployment.ports); dropping a key issues --expose '<outside>!', and a trailing ! marks a removal (53+udp! for UDP, 80@conn! for a load balancer).

Exports: id (= tenant/environment/stack).

resource "shc_stack_ports" "traefik" {
tenant = "master"
stack = "traefik"
ports = {
"80" = { connection = shc_connection.edge.name }
"443" = { connection = shc_connection.edge.name }
}
}

The estate’s entitlement, as a node in the graph, so a multi-node apply can order shc_node.workers after it. clustering is Pro-and-up and the trial grants Hobby (one node, ruled 2026-08-16), so a from-empty multi-node estate must be entitled before its first join or every join is refused X403029LICENT.

Most estates do not need this resource. An internet-facing estate licenses itself with shc license activate and no arguments: the broker proves domain control by calling back to the estate’s own domain, and nothing has to be declared. Declare shc_license only for an estate that cannot answer such a callback: a private-network or CI estate on a reserved .test name, or an airgapped one.

Set exactly one of registration_code or token; the provider refuses both or neither at plan time.

ArgumentTypeRequiredDescription
clusterblocknoPer-resource cluster/transport override.
registration_codestring (sensitive)one-ofEnrollment code issued by the vendor. The cluster registers itself with the broker and pulls its entitlements. Forces replacement.
tokenstring (sensitive)one-ofA vendor-signed licence file body (shclic.v1…), for a genuinely airgapped estate. Forces replacement.
brokerstringnoOverride the broker for THIS registration only. Renewals always go to the vendor compiled into the binary. Forces replacement.
nodesnumbernoCluster size to entitle; omit to take the broker’s cap.

Exports: id (the held licence id, or estate), state (keyed/trial/degraded/unlicensed/dev), type, expires_at, watermarked, registration (the durable cluster identity: an identifier, not a credential).

Credential handling. registration_code is marked sensitive and is delivered to the node over stdin, never argv, so it appears neither in ps on the node nor in the provider’s own error output. Like every sensitive terraform value it does land in terraform state: keep state encrypted, and prefer a code scoped tightly enough that state exposure is survivable.

Destroy is a no-op. Removing the resource drops it from state and leaves the estate licensed. shc license delink is deliberately not wired to Delete: a terraform destroy that stripped a paying estate’s entitlement (or that raced a partial teardown into a lock) is a foot-gun with no upside, and the licence is a fact terraform asserted, not a resource it created.

resource "shc_license" "estate" {
registration_code = var.enroll_code # sensitive
nodes = 3
}
resource "shc_node" "workers" {
# ...
depends_on = [shc_license.estate]
}

modules/core wires this for you: set bootstrap.license and the module places shc_license.estate between shc_node.bootstrap and shc_node.workers.

Scoped SHC configuration keys: cluster-wide (no tenant) or at a tenant’s scope. Home of role defaults like dns.provider / backup.provider and dns.public_address. Accepts exactly one of two mutually exclusive forms: single-key (key + value) or a nested yaml document flattened to dotted paths. Schema version 1.

ArgumentTypeRequiredDescription
clusterblocknoPer-resource cluster/transport override.
keystringnoConfig key path (e.g. dns.provider); single-key form, set with value. Forces replacement. Mutually exclusive with yaml.
valuestringnoValue for the single-key form (stored verbatim as string). Required alongside key.
yamlstringnoNested YAML document flattened to dotted paths; every leaf must be scalar. Mutually exclusive with key/value.
tenantstringnoTenant to scope key(s) to; omit for cluster-wide (global) scope. Forces replacement.

Exports: id (= scope/tenant/key, or scope/tenant/* for the yaml form).

resource "shc_config" "platform" {
yaml = <<-EOF
dns:
provider: cloudflare
public_address: ${local.bootstrap_ip}
acme:
EOF
}

A managed DNS record for a host (/api/dns/record). The daemon auto-classifies target (IPv4 → A, IPv6 → AAAA, else CNAME). No tenant attribute; this surface is platform-level.

ArgumentTypeRequiredDescription
clusterblocknoPer-resource cluster/transport override.
hostnamestringyesThe record’s hostname (identity key). Forces replacement.
targetstringyesRecord target: IPv4 (A), IPv6 (AAAA), or hostname (CNAME). Upserts in place.
ttlintno (computed)Record TTL in seconds; omit for the provider default.
proxiedboolno (default false)Serve through the provider proxy (e.g. Cloudflare orange-cloud).
dns_providerstringnoDNS provider (shc_connection name) override, named dns_provider, not provider (reserved). Forces replacement.

Exports: type (A/AAAA/CNAME), zone_id, record_id, id (= hostname).

resource "shc_dns_record" "status" {
hostname = "status.example.com"
target = module.shc.bootstrap_node.public.ipv4
dns_provider = shc_connection.dns.name
}

Each data source reads over whichever transport the provider block configures, the same way a resource does: the ssh block when there is one (the equivalent shc verb over SSH), the HTTP API otherwise. The data-source cluster override block carries the HTTP fields only (endpoint, token, ca_pem, insecure); the SSH transport is selected on the provider block.

Reads the cluster’s mesh0 status (shc cluster mesh status). This data source reports node membership without changing the mesh.

ArgumentTypeRequiredDescription
clusterobjectnoHTTP connection override (endpoint, token, ca_pem, insecure), as on the other data sources.

Exports: nodes (computed list of {node_id, node_name, mesh_address, installed, running, error}), id (constant mesh).

data "shc_mesh" "main" {}
output "mesh_nodes" {
value = data.shc_mesh.main.nodes
}

Reports the cluster’s membership and quorum status (shc cluster status). Input: the optional cluster override block only.

Exports (computed): cluster_name, total_nodes, healthy_nodes, degraded_nodes, unreachable_nodes, voters, required_voters, leader_id, leader_name, quorum_healthy, background_work_node, expected_voters, raft_voters, voter_deficit, id.

data "shc_cluster_status" "this" {}
output "quorum" { value = data.shc_cluster_status.this.quorum_healthy }

Looks up one app in the cluster’s resolved catalog. name is the bare app name; the optional repo names the repo it must resolve from (slash-qualified names are rejected).

ArgumentTypeRequiredDescription
clusterblocknoCluster override.
namestringyesThe bare catalog app name.
repostringnoRepo name the app must resolve from; absent = default resolution.

Exports: version, category, description, homepage, icon, source, tags (list), parent_app, vapp (bool), repo_id, repo_name, id.

On the SSH transport the lookup is shc show <name> [--repo <repo>], whose catalog row carries no repo_id and no source, so those two read null there. Every other export is the same on both transports.

Mints a short-lived LAN enrollment token: the credential shc node join consumes. Minted fresh on every read, sensitive, consume within the same apply.

ArgumentTypeRequiredDescription
clusterblocknoCluster override.
ttlstringnoRequested lifetime (Go duration, e.g. 15m); omit for the daemon default.

Exports: token (sensitive), expires_at, id.

Renders cloud-init user_data that self-bootstraps an SHC node: installs the .deb, then runs shc init (role cluster) or shc node join <token> (role node). The render is client-side (the daemon has no render route); feed the output to a compute resource’s user_data (the adopt bootstrap path).

ArgumentTypeRequiredSensitiveDescription
clusterblocknon/aCluster override.
rolestringyesnocluster (bootstrap via shc init) or node (join via shc node join).
packageblocknonoPackage to install (version required, repository optional), as on shc_cluster.
nicstringnonoInternal-traffic interface (--nic).
runtimestringnonoContainer runtime (--runtime).
namestringnonoNode name (--name).
fabricstringnonorole cluster only: shc init --fabric (shc or none). Setting it with role node is refused. shc node join has no --fabric, so the flag would be dropped. Validated identically to shc_node.fabric, at plan time.
address_blockstringnonorole cluster only: --address-block (daemon default 10.64.0.0/16). See the address block.
host_domainstringnonorole cluster only: the shc init --ingress-host seed.
public_addressstringnonoNode’s public ingress address (--public-address).
locationstringnonoNode location (--location), both roles: one name or a path like gorillaservers/ogden/incus01, same rule as shc_node.
cloudstringnonoNode cloud (--cloud), both roles.
modulesmap(block)nonorole cluster only: system-app selection + overrides.
vault_passwordstringnoyesrole cluster only: embedded verbatim in the output, so use an encrypted state backend.
tokenstringnoyesrole node only: enrollment token to join with. Omitted = mint fresh on every read.
ttlstringnonorole node only: TTL when minting a token.

Exports: rendered (sensitive: the cloud-init user_data), token_expires_at, id (= <role>-cloudinit).

data "shc_cloudinit" "bootstrap" {
role = "cluster"
package = { version = var.shc_version }
host_domain = "cloud.example.com"
vault_password = var.vault_pw
}
# feed data.shc_cloudinit.bootstrap.rendered to the instance's user_data

Daemon errors carry an X<HTTP><SEQ><MNEMONIC> code (see the error code reference). The provider surfaces the code verbatim and leading in diagnostic detail, so operators can grep by code.

Two codes are minted by the provider itself and are therefore absent from the daemon’s reference: the daemon cannot raise them, because they turn on knowledge only the IaC layer has:

coderaised bymeaning
X409026SECCLSshc_node (bootstrap, SSH engine)a cluster already answers on a configured host and this node is not part of it, and shc init here would build a second cluster
X400162ADPHSTshc_node (bootstrap, adopt = true), at planthe node has neither host_domain nor a management URL with a scheme, so nothing off the node reaches the daemon’s API to poll