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.
- Declaring the provider
- Installing from the network mirror
- Provider configuration
- Transports and the per-resource
clusterblock - Resources:
shc_cluster·shc_node·shc_tenant·shc_user·shc_user_group·shc_service_client·shc_oidc_client·shc_identity_provider·shc_ldap_bind·shc_connection·shc_connection_grant·shc_repo·shc_deployment·shc_stack_ports·shc_license·shc_config·shc_dns_record - Data sources:
shc_mesh·shc_cluster_status·shc_catalog_app·shc_enrollment_token·shc_cloudinit
Declaring the provider
Section titled “Declaring the provider”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" } }}Installing from the network mirror
Section titled “Installing from the network mirror”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/excludepair scopes the mirror to only the shc provider; without it,tofu inittries 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.
Provider configuration
Section titled “Provider configuration”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")}| Argument | Type | Required | Sensitive | Env fallback | Description |
|---|---|---|---|---|---|
endpoint | string | no | no | SHC_ENDPOINT | Daemon 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. |
token | string | no | yes | SHC_TOKEN | Static bearer token for TCP endpoints (ignored for unix://). Mutually exclusive with client_id/client_secret. |
client_id | string | no | no | SHC_CLIENT_ID | OAuth2 client_credentials client id (mint with shc auth create-service-client). Self-mints + re-grants its bearer. Mutually exclusive with token. |
client_secret | string | no | yes | SHC_CLIENT_SECRET | OAuth2 client_credentials secret. Mutually exclusive with token. |
token_url | string | no | no | none | OAuth2 token endpoint; defaults to https://<endpoint-host>/auth/realms/master/protocol/openid-connect/token. Only with client_id/client_secret. |
ca_pem | string | no | no | SHC_CA_PEM | PEM bundle to trust for TLS against the cluster’s internal CA (the ca_pem output of the bootstrap node). |
insecure | bool | no | no | none | Skip TLS certificate verification (bootstrap/testing only; prefer ca_pem). |
ssh | block | no | n/a | none | Default SSH transport for every platform resource; see below. |
registry_auth | block | no | n/a | none | Pre-authenticate the node container runtime during SSH bootstrap (avoids registry rate limits). |
ssh block (provider default transport)
Section titled “ssh block (provider default transport)”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.
| Argument | Type | Required | Sensitive | Description |
|---|---|---|---|---|
hosts | list(object) | yes | no | EVERY 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. |
user | string | no | no | Default SSH user for every entry (default root; non-root users need NOPASSWD sudo; every command runs sudo -n). |
private_key | string | no | yes | Default SSH private key (PEM) for every entry. |
port | int | no | no | Default SSH port for every entry (default 22). |
host_key | string | no | no | Default 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_key | bool | no | no | Dial 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.
registry_auth block
Section titled “registry_auth block”| Argument | Type | Required | Sensitive | Description |
|---|---|---|---|---|
server | string | no | no | Registry hostname (default Docker Hub). |
username | string | no | no | Registry username. |
password | string | no | yes | Registry password or access token (crosses the wire as SSH-session stdin). |
Authentication modes
Section titled “Authentication modes”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 die401partway. Mint the pair withshc auth create-service-client terraformon 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, orclient_id/client_secret). - SSH: when a
cluster { ssh { ... } }block is set (or inherited from the provider’s ownssh), the resource runs the equivalentshc <verb>CLI command over SSH on whichever node inhostsanswers 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:
| Argument | Type | Required | Description |
|---|---|---|---|
endpoint | string | no | Daemon API endpoint. Required unless ssh is set. |
token | string | no (sensitive) | Bearer token for TCP endpoints. |
ca_pem | string | no | PEM bundle to trust for TLS. |
insecure | bool | no | Skip TLS verification (bootstrap/testing only). |
ssh | block | no | Run 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.)
Resources
Section titled “Resources”Cluster and node lifecycle
Section titled “Cluster and node lifecycle”shc_cluster
Section titled “shc_cluster”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.
| Argument | Type | Required | Sensitive | Description |
|---|---|---|---|---|
package | block | yes | no | Cluster-wide SHC package default (version, repository); every shc_node inherits it. |
fabric | string | no | no | Genesis 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_block | string | no | no | The 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_domain | string | no | no | The genesis domain (shc init --ingress-host) / basePath seed. |
modules | map(block) | no | no | Structured system-app selection + per-app overrides (see below). |
connections | map(block) | no | yes (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). |
storage | string | no | no | The volume connection the platform stacks’ durable volumes go on (shc init --storage, written as storage.volumes.provider before they install). |
vault_password | string | no | yes | Vault 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. |
acme | block | no | no | Named ACME providers + the cluster default (see below). |
id | string | computed | no | Stable 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}shc_node
Section titled “shc_node”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.
| Argument | Type | Required | Sensitive | Description |
|---|---|---|---|---|
cluster | block | no | n/a | Per-resource cluster/transport override (join reference). |
bootstrap | bool | no | no | Create-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_genesis | bool | no | no | Bootstrap-only, create-time only, dangerous. Waives the existing-cluster probe described below. Does not force replacement. |
host | string | yes | no | Node address (host/IP, or full https://…/unix:// URL). SSH target and bootstrap endpoint base. |
package | block | no | no | Package 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_version | bool | no (default false) | no | Standing 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. |
ssh | block | no | n/a | Selects 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. |
adopt | bool | no | no | Adopt 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. |
name | string | yes | no | Node name (--name), the membership identity polled for. Forces replacement. |
nic | string | no | no | The one internal-traffic interface (--nic). Forces replacement. |
runtime | string | no | no | Container runtime (--runtime). Forces replacement. |
public_address | string | no | no | Public ingress address (--public-address); managed DNS reads it. Repaired in place. |
location | string | no | no | The 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. |
cloud | string | no | no | The 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_plane | bool | no | no | Whether 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. |
reserve | string | no | no | What 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". |
hypervisor | string | no | no | The 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_ip | string | no | no | Expected 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. |
fabric | string | no | no | Bootstrap-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_block | string | no | no | Bootstrap-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_domain | string | no | no | Bootstrap-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. |
modules | map(block) | no | no | Bootstrap-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). |
connections | map(block) | no | yes (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. |
storage | string | no | no | Bootstrap-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_password | string | no | yes | Bootstrap-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_in | bool | no | no | Bootstrap-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. |
acme | block | no | no | Bootstrap-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_destroy | string | no | no | Destroy-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_tokencannot be freshly minted by either mechanism:shc initproduces 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
skippedbefore 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:
| Attribute | Default | Bounds |
|---|---|---|
ready_timeout | 10m | Time the node spends answering over SSH while its daemon reports not-ready. |
transport_timeout | 20m | Time 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").
Rotating the vault password
Section titled “Rotating the vault password”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:
- 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 = trueturns this refusal into a warning; see Recovering a stranded auto-unlock credential.) - 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.
- 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.
- 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
shcdrestart 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
sshblock 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 withshc 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_passwordmust carry no leading or trailing whitespace.shc inittrims 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_passwordmust 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 rotaterefuses 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 withrandom_password { special = false }, as the examples do. Only the SSH bootstrap path is checked: anadopt = truenode 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
falseunless you are recovering such a node, and unset it afterwards. Left on permanently, it lets a routineterraform applysilently 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_passwordunchanged 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 sees | what happens |
|---|---|
| no host answers with a membership | genesis: the ordinary first install |
| only this node answers | genesis: shc init is idempotent on an already-clustered node, so a retried apply resumes |
| this node and peers answer | genesis: same resume; the machine is already a member of the cluster that answered |
| a peer answers, this node does not | refused 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}Destroying an occupied node (on_destroy)
Section titled “Destroying an occupied node (on_destroy)”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 do | when | |
|---|---|---|
| Relocate | shc 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. |
| Consent | set 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_destroyis read from STATE, likeaws_s3_bucket.force_destroy. Setting it in config and going straight totofu destroydoes not work:tofu applyfirst, then destroy.- The value space is closed at plan time. Only the exact string
"force"consents;"Force","yes"and"drain"areValidateConfigerrors rather than values that read as absent at destroy time. - Only the occupancy refusal is overridden. The quorum-deficit
(
X409201CLSRMQ) floor is untouched byon_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 withouton_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.
Tenancy and access
Section titled “Tenancy and access”shc_tenant
Section titled “shc_tenant”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).
| Argument | Type | Required | Description |
|---|---|---|---|
cluster | block | no | Per-resource cluster/transport override. |
name | string | yes | Tenant name. Forces replacement. |
vault_connection | string | no | Name 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"}shc_user
Section titled “shc_user”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).
| Argument | Type | Required | Sensitive | Description |
|---|---|---|---|---|
cluster | block | no | n/a | Per-resource cluster/transport override. |
username | string | yes | no | Username in the tenant realm (Keycloak lowercases it). Forces replacement. |
name | string | yes | no | The 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. |
tenant | string | yes | no | Tenant whose realm owns the user; an estate has no default tenant. Forces replacement. |
email | string | yes | no | User 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. |
password | string | no | yes | The 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. |
grants | set(string) | no | no | Roles 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. |
groups | set(string) | no | no | Groups 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_destroy | string | no | no | Destroy-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"]}shc_user_group
Section titled “shc_user_group”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.
| Argument | Type | Required | Description |
|---|---|---|---|
cluster | block | no | Per-resource cluster/transport override. |
name | string | yes | The 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. |
tenant | string | yes | Tenant 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]}shc_service_client
Section titled “shc_service_client”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.
| Argument | Type | Required | Description |
|---|---|---|---|
cluster | block | no | Per-resource cluster/transport override. |
name | string | yes | The 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_lifespan | number | no (default 3600) | Access-token lifespan in seconds, 60 to 86400. Forces replacement. |
rotate_trigger | string | no | Any 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 : ""}shc_oidc_client
Section titled “shc_oidc_client”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.
| Argument | Type | Required | Description |
|---|---|---|---|
cluster | object | no | Same per-resource connection override as shc_service_client, including SSH. |
tenant | string | yes | Tenant realm. Forces replacement. |
client_id | string | yes | Client identifier within the tenant. Forces replacement. |
redirect_uris | set(string) | yes | Allowed callback URIs. Must contain at least one element. |
web_origins | set(string) | no (default []) | Allowed browser origins. Omitting it clears existing origins on apply. |
authentication | string | yes | client-secret or client-jwt. Forces replacement; the API refuses an in-place change with X409956OIDAUT. |
jwks_url | string | for client-jwt | Absolute HTTPS JWKS URL without userinfo or a fragment. Must be unset for client-secret. |
signing_alg | string | for client-jwt | RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384 or ES512. Must be unset for client-secret. |
standard_flow_only | bool | no (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.
shc_identity_provider
Section titled “shc_identity_provider”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.
| Argument | Type | Required | Description |
|---|---|---|---|
cluster | object | no | Same per-resource connection override as shc_oidc_client, including SSH. |
tenant | string | yes | Master or a tenant realm. Forces replacement. |
alias | string | yes | Provider alias within the realm. Forces replacement. |
display_name | string | no (default "") | Login screen label. Omitting it clears the label on apply. |
issuer | string | yes | Absolute HTTPS OpenID issuer URL without userinfo, a query or a fragment. |
client_id | string | yes | Client identifier registered at the external issuer. |
authentication | string | yes | client-jwt or client-secret. Changes update the provider in place. |
signing_alg | string | for client-jwt | RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384 or ES512. Must be unset for client-secret. |
client_secret_ref | string | for client-secret | A ref+vault:// reference, not a secret value. Must be unset for client-jwt. The reference is not sensitive; the secret never reaches Terraform. |
sync_mode | string | no (default import) | import, legacy or force. |
first_login | string | no (default link-only) | link-only or create. Master refuses create. |
enabled | bool | no (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.
shc_ldap_bind
Section titled “shc_ldap_bind”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.
| Argument | Type | Required | Description |
|---|---|---|---|
cluster | block | no | Per-resource cluster/transport override. |
name | string | yes | The 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. |
tenant | string | yes | Tenant 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_trigger | string | no | Any 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:
shc user reset-password alice -t acmeThe same without Terraform:
shc user group add gateway-admins -t acmeshc user join alice gateway-admins -t acmeshc auth create-ldap-bind gateway -t acmeConnections and grants
Section titled “Connections and grants”shc_connection
Section titled “shc_connection”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.
| Argument | Type | Required | Sensitive | Description |
|---|---|---|---|---|
cluster | block | no | n/a | Per-resource cluster/transport override. |
name | string | yes | no | Connection name. Forces replacement. |
type | string | yes | no | Connection type (e.g. route53, hetzner, cloudflare, pfsense, s3, aws, gcp). |
tenant | string | no (default master) | no | Owning tenant. Forces replacement. |
credentials | map(string) | no | yes | Credential fields per type (write-only). An endpoint key is passed as the backend endpoint rather than a secret. |
zones | list(string) | no | no | For 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"]}shc_connection_grant
Section titled “shc_connection_grant”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).
| Argument | Type | Required | Description |
|---|---|---|---|
cluster | block | no | Per-resource cluster/transport override. |
connection_name | string | yes | The connection being shared (bare connection is a reserved root name). Forces replacement. |
capability | string | yes | Capability the grantee may mint (e.g. aws-iam, s3-bucket). Forces replacement. |
grantee | string | yes | Tenant authorised to mint. Forces replacement. |
tenant | string | no (default master) | The connection’s owning tenant. Forces replacement. |
boundary_policy | string | no, except on HELD capabilities | Permissions 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")}HELD capabilities need an explicit scope
Section titled “HELD capabilities need an explicit scope”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 })}Apps and repositories
Section titled “Apps and repositories”shc_repo
Section titled “shc_repo”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.
| Argument | Type | Required | Sensitive | Description |
|---|---|---|---|---|
cluster | block | no | n/a | Per-resource cluster/transport override. |
name | string | yes | no | Repository name. Forces replacement. |
url | string | yes | no | Remote repo URL (https://… or git+…). Forces replacement. |
token | string | no | yes | Access token for a private repo (write-only). Forces replacement. |
tenant | string | no | no | Owning tenant. Forces replacement. |
environment | string | no | no | Owning environment. Forces replacement. |
priority | int | no (computed) | no | Resolution priority (higher wins). |
sync_interval | string | no | no | Auto-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.
shc_deployment
Section titled “shc_deployment”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).
| Argument | Type | Required | Description |
|---|---|---|---|
cluster | block | no | Per-resource cluster/transport override. |
tenant | string | yes | Owning tenant; an estate has no default tenant. Forces replacement. |
repo | string | no | Catalog repo name to resolve app from; absent = default resolution. Forces replacement. |
app | string | yes | Bare catalog app name (never slash-qualified). Forces replacement. |
stack | string | no (computed) | Stack name; defaults to the app base name. Forces replacement. |
environment | string | no (default default) | Environment. Forces replacement. |
vars | map(string) | no | App variables; sent in full each apply. |
addon | string | no | Add-on to apply: the name of an addons/<name>.addon.yaml in the app that declares no vapp:. |
storage | string | no | Storage provider for volumes; install-time only. Forces replacement. |
acme_provider | string | no | Named ACME provider issuing public certs; blank = cluster default. Changeable in place: the daemon re-issues under the new CA without a recreate. |
runtime | string | no | Target runtime: docker, podman, incus, or apple; install-time only. Forces replacement. |
scale | map(int) | no | Per-service replica counts. |
public | bool | no (default false) | --public: expose to the internet. |
gated | bool | no (default false) | --gated: put Keycloak SSO in front. |
integrate | map(block) | no | Provider bindings keyed by plug (see below). |
connections | map(block) | no | Connection bindings keyed by the app’s declared binding name (see below). |
ports | map(block) | no | L4 port mappings keyed by "external[/udp]" (see below). |
routes | map(block) | no | L7 HTTP routes keyed by "hostname[/path]" (see below). |
node | string | no (computed) | Install-time placement pin; not changeable in place. |
ttl | string | no | Lease duration (Go duration, e.g. 72h); re-applying the same value renews. Refused on protected environments. |
wait_healthy | bool | no (default true) | Block Create/Update on deployment health. |
protected | bool | no (default false) | Destroy guard (X409001DEPROT): refuses uninstall/destroy only; the deployment can still be moved and drained (ruling P9). |
on_destroy | string | no | Destroy-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_package | bool | no (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 notarget; the daemon infers the DNS endpoint.integrate(key = plug name):stackXORconnection, plus optionalenvironment(only withstack).connections(key = the app’s declared binding name):connection(string, required), which needs a matchingshc_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.appbackfills from the first read (the daemon echoesapp_name), the same wayshc_vdeploymentbackfillsvapp, so the plan after an import is never a REPLACEMENT. It used to be:appandrepoare both RequiresReplace, neither was filled, and null → value on such an attribute plans a replace, so importing a live stack planned to uninstall it.repois 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/runtimestay config-only exactly likeshc_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 deployedcompose.yaml.
What wait_healthy actually watches
Section titled “What wait_healthy actually watches”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.
App package drift
Section titled “App package drift”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.
| Export | Meaning |
|---|---|
app_digest | Content identity (apppkg-v1:<sha256>) of the app this deployment was last RENDERED from. Empty = none recorded; never “current”. |
app_package_available | Identity 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_drift | current, 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
ttlset never converges to an empty plan: every apply re-stamps the lease (like GitLab’sauto_stop_in). That is by design.vars/ports/routes/integrateare authoritative-from-config: the provider sends the full desired sets plus explicit removals each apply, but removing aconnectionskey is a documented no-op until connection-detach lands.
shc_vdeployment
Section titled “shc_vdeployment”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.)
| Argument | Type | Required | Description |
|---|---|---|---|
cluster | block | no | Per-resource cluster/transport override. Both transports, same precedence as every other resource. |
tenant | string | yes | The HOST’s tenant; an estate has no default tenant. Forces replacement. |
environment | string | no (default default) | The HOST’s environment. |
host_stack | string | yes | Name of the deployed host stack (e.g. shc_deployment.pg.stack). Bare name. |
vapp | string | yes | The 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. |
instance | string | yes | Instance name, unique per host. Bare name. |
addon | string | no | Add-on to apply: an addons/<name>.addon.yaml in the host’s app that declares vapp: <this vapp>. |
addon_version | string | no | Version key inside the add-on’s versions: map (omit = the add-on’s default). |
vars | map(string) | no | vApp variables (vvars), applied over the add-on’s resolved vars. |
integrate | map(block) | no | Integrations keyed by consumer plug (same shape as shc_deployment.integrate). |
wait_healthy | bool | no (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:
statusis its install lifecycle, and there is deliberately nohealthyexport. Import withterraform import shc_vdeployment.appdb default/pg-main/default/appdb;vapp,host_appandstatusbackfill from the first read, whileaddon/vars/integrateare config-only exactly likeshc_deployment’s desired sets.
shc_stack_ports
Section titled “shc_stack_ports”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.
| Argument | Type | Required | Description |
|---|---|---|---|
cluster | block | no | Per-resource cluster/transport override. |
tenant | string | yes | Owning tenant; an estate has no default tenant. Forces replacement. |
environment | string | no (default default) | Environment. Forces replacement. |
stack | string | yes | The existing stack to attach mappings to. Forces replacement. |
ports | map(block) | no | Port 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 } }}shc_license
Section titled “shc_license”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 activateand no arguments: the broker proves domain control by calling back to the estate’s own domain, and nothing has to be declared. Declareshc_licenseonly for an estate that cannot answer such a callback: a private-network or CI estate on a reserved.testname, or an airgapped one.
Set exactly one of registration_code or token; the provider refuses
both or neither at plan time.
| Argument | Type | Required | Description |
|---|---|---|---|
cluster | block | no | Per-resource cluster/transport override. |
registration_code | string (sensitive) | one-of | Enrollment code issued by the vendor. The cluster registers itself with the broker and pulls its entitlements. Forces replacement. |
token | string (sensitive) | one-of | A vendor-signed licence file body (shclic.v1…), for a genuinely airgapped estate. Forces replacement. |
broker | string | no | Override the broker for THIS registration only. Renewals always go to the vendor compiled into the binary. Forces replacement. |
nodes | number | no | Cluster 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.
Config and DNS
Section titled “Config and DNS”shc_config
Section titled “shc_config”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.
| Argument | Type | Required | Description |
|---|---|---|---|
cluster | block | no | Per-resource cluster/transport override. |
key | string | no | Config key path (e.g. dns.provider); single-key form, set with value. Forces replacement. Mutually exclusive with yaml. |
value | string | no | Value for the single-key form (stored verbatim as string). Required alongside key. |
yaml | string | no | Nested YAML document flattened to dotted paths; every leaf must be scalar. Mutually exclusive with key/value. |
tenant | string | no | Tenant 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: email: [email protected] EOF}shc_dns_record
Section titled “shc_dns_record”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.
| Argument | Type | Required | Description |
|---|---|---|---|
cluster | block | no | Per-resource cluster/transport override. |
hostname | string | yes | The record’s hostname (identity key). Forces replacement. |
target | string | yes | Record target: IPv4 (A), IPv6 (AAAA), or hostname (CNAME). Upserts in place. |
ttl | int | no (computed) | Record TTL in seconds; omit for the provider default. |
proxied | bool | no (default false) | Serve through the provider proxy (e.g. Cloudflare orange-cloud). |
dns_provider | string | no | DNS 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}Data sources
Section titled “Data sources”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.
shc_mesh
Section titled “shc_mesh”Reads the cluster’s mesh0 status (shc cluster mesh status). This data
source reports node membership without changing the mesh.
| Argument | Type | Required | Description |
|---|---|---|---|
cluster | object | no | HTTP 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}shc_cluster_status
Section titled “shc_cluster_status”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 }shc_catalog_app
Section titled “shc_catalog_app”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).
| Argument | Type | Required | Description |
|---|---|---|---|
cluster | block | no | Cluster override. |
name | string | yes | The bare catalog app name. |
repo | string | no | Repo 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.
shc_enrollment_token
Section titled “shc_enrollment_token”Mints a short-lived LAN enrollment token: the credential shc node join
consumes. Minted fresh on every read, sensitive, consume within the same
apply.
| Argument | Type | Required | Description |
|---|---|---|---|
cluster | block | no | Cluster override. |
ttl | string | no | Requested lifetime (Go duration, e.g. 15m); omit for the daemon default. |
Exports: token (sensitive), expires_at, id.
shc_cloudinit
Section titled “shc_cloudinit”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).
| Argument | Type | Required | Sensitive | Description |
|---|---|---|---|---|
cluster | block | no | n/a | Cluster override. |
role | string | yes | no | cluster (bootstrap via shc init) or node (join via shc node join). |
package | block | no | no | Package to install (version required, repository optional), as on shc_cluster. |
nic | string | no | no | Internal-traffic interface (--nic). |
runtime | string | no | no | Container runtime (--runtime). |
name | string | no | no | Node name (--name). |
fabric | string | no | no | role 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_block | string | no | no | role cluster only: --address-block (daemon default 10.64.0.0/16). See the address block. |
host_domain | string | no | no | role cluster only: the shc init --ingress-host seed. |
public_address | string | no | no | Node’s public ingress address (--public-address). |
location | string | no | no | Node location (--location), both roles: one name or a path like gorillaservers/ogden/incus01, same rule as shc_node. |
cloud | string | no | no | Node cloud (--cloud), both roles. |
modules | map(block) | no | no | role cluster only: system-app selection + overrides. |
vault_password | string | no | yes | role cluster only: embedded verbatim in the output, so use an encrypted state backend. |
token | string | no | yes | role node only: enrollment token to join with. Omitted = mint fresh on every read. |
ttl | string | no | no | role 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_dataCoded errors
Section titled “Coded errors”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:
| code | raised by | meaning |
|---|---|---|
X409026SECCLS | shc_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 |
X400162ADPHST | shc_node (bootstrap, adopt = true), at plan | the node has neither host_domain nor a management URL with a scheme, so nothing off the node reaches the daemon’s API to poll |