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 ~12 resources and 4 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 cluster block
• Resources — shc_cluster · shc_node · shc_mesh · shc_tenant · shc_user · shc_connection · shc_connection_grant · shc_repo · shc_deployment · shc_stack_ports · shc_config · shc_dns_record
• Data sources — shc_cluster_status · shc_catalog_app · shc_enrollment_token · shc_cloudinit

Name the provider with its explicit source host (it matches the provider’s Address, and OpenTofu users need it spelled out since their default registry host differs):

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

The provider is not on the public Terraform / OpenTofu registry. It is published to a GitLab Pages provider network mirror (static JSON + zips over HTTPS). 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://<PAGES-URL>/"
    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"]
  }
}

• <PAGES-URL> is the project’s GitLab Pages root (e.g. https://<your-group>-<project>.gitlab.io/). Confirm it under Deploy → Pages; the mirror must be publicly readable.
• The include/exclude pair scopes the mirror to only the shc provider — without it, tofu init tries the mirror for hcloud/aws/google too and fails. The mirror serves the provider under both registry hostnames, so the short source resolves for either tool.

Dev-only per-commit channel. For iterating against an in-flight main commit (not a release), the mirror also serves a per-commit-sha provider type shc-<8charsha>, whose single version is always 0.0.0:

shc = { source = "selfhosted-cloud/shc-a1b2c3d4", version = "0.0.0" }

These pins are ephemeral — a sha ages out of the snapshot retention window and its mirror directory disappears, bricking tofu init. Use a real release pin for anything durable. This channel needs a broader include (registry.terraform.io/selfhosted-cloud/*).

Integrity. The mirror omits the protocol-optional hashes field, so tofu/terraform compute the h1: hash on first install and record it in your .terraform.lock.hcl — trust-on-first-use, with tamper detection from then on via the lock file. (Network mirrors have no signature channel at all; only the public registries serve signatures.)

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://node-1:8000"        # 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")
}

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.

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 bare list of addresses. 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" }]
  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.

Exactly one of:

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

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

The platform resources (shc_node’s token mint, shc_connection, shc_config, shc_mesh, shc_dns_record, shc_stack_ports, shc_user, shc_tenant, shc_deployment, …) each support two transports:

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

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:

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

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

package block: deb_url (string, required) — URL of the .deb to install; version (string, optional) — a change (propagated to nodes) triggers their in-place rolling upgrade.

modules block (map keyed by system-app name; the key SET is the install selection — unset installs the daemon’s default set, {} installs none, a populated map installs exactly those apps): host (string), base_path (string), vars (map(string)) — seeded under system.apps.<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        = { deb_url = var.deb_url }
  host_domain    = "cloud.example.com"
  vault_password = var.vault_pw
  acme           = { providers = { prod = { email = "ops@example.com" } }, default = "prod" }
}

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

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.

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

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

The cluster-wide Nebula overlay toggle (shc cluster mesh enable/disable). A singleton per cluster (id = "mesh") — one resource covers the whole cluster’s membership, re-synced on every apply (enable is additive + idempotent over current membership, so it is safe to depends_on after every shc_node join). Removing the resource disables the mesh.

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

resource "shc_mesh" "main" {
  enabled    = true
  depends_on = [shc_node.workers]
}

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

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

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

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

Exports: id (= <username>/<tenant>).

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

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.

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

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

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

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")
}

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.

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

resource "shc_repo" "shc" {
  name = "shc"
  url  = "https://<PAGES-URL>/apps/index.yaml"
}

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

Nested value shapes:

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

Exports: status, healthy (bool), node, lease_expires_at (RFC3339; empty when ttl unset), id (= tenant/environment/stack).

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

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

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.

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

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

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.

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: ops@example.com
  EOF
}

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

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
}

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

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

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

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

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

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

Exports: token (sensitive), expires_at, id.

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

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

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

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