Skip to content
SHC Docs

Deployments through the provider

Everything so far went through the module. The shc provider also has resources of its own for what runs on the cluster: repositories, deployments, vapp instances, tenants, users, connections and config. They talk to the cluster over SSH with the key the module minted, trying every node in cluster_ssh_hosts until one answers.

Write deployments.tf. The provider block carries the transport. The repository is the public app catalogue. db is the shipped Postgres with one variable set, appdb is a database vapp inside it, and hello is the catalogue’s whoami, with port 18080 published on every node. They live in the prod tenant, which this file creates: a new cluster has only master, SHC’s own tenant, and its first tenant needs no licence. The user is an SSO user in prod, granted tenant:manage, the canonical role SHC provisions on the tenant realm’s shc-access client. She is the tenant’s only manager, so the cluster refuses to remove her unless told to; she takes the same on_destroy as the nodes, which page 07 sets. The two data sources read the cluster and the catalogue without changing anything.

Every resource that names no other one says depends_on = [module.shc]. A destroy runs in the reverse order of what depends on what, and the provider block reading the module’s outputs does not put anything after the nodes, so this line is what takes the deployments, the vapp and the user off the cluster before any node leaves it. appdb and hello reach the module through db and the repository they name.

~/learn/cluster/deployments.tf
provider "shc" {
ssh = {
hosts = module.shc.cluster_ssh_hosts
user = "admin"
private_key = module.shc.ssh_private_key
}
}
resource "shc_repo" "shc" {
name = "shc"
url = "https://selfhostedcloud.org/apps/0.1/index.yaml"
depends_on = [module.shc]
}
resource "shc_tenant" "prod" {
name = "prod"
depends_on = [module.shc]
}
resource "shc_deployment" "db" {
tenant = shc_tenant.prod.name
environment = "prod"
app = "postgres"
stack = "db"
vars = {
"postgres.database" = "learn"
}
depends_on = [module.shc]
}
resource "shc_vdeployment" "appdb" {
tenant = shc_tenant.prod.name
environment = "prod"
host_stack = shc_deployment.db.stack
vapp = "database"
instance = "appdb"
}
resource "shc_deployment" "hello" {
tenant = shc_tenant.prod.name
environment = "prod"
repo = shc_repo.shc.name
app = "whoami"
stack = "hello"
ports = {
"18080" = {
service = "whoami"
container = 80
}
}
}
resource "shc_user" "alice" {
tenant = shc_tenant.prod.name
username = "alice"
name = "Alice Liddell"
password = "P@ssw0rd"
grants = ["tenant:manage"]
on_destroy = var.on_destroy
depends_on = [module.shc]
}
data "shc_cluster_status" "this" {}
data "shc_catalog_app" "whoami" {
name = "whoami"
repo = shc_repo.shc.name
depends_on = [shc_repo.shc]
}
output "quorum_healthy" {
value = data.shc_cluster_status.this.quorum_healthy
}
output "whoami_version" {
value = data.shc_catalog_app.whoami.version
}
output "hello_node" {
value = shc_deployment.hello.node
}
work
$ tofu -chdir=learn/cluster fmt
$ tofu -chdir=learn/cluster plan
...
# shc_deployment.db will be created
...
# shc_deployment.hello will be created
...
# shc_repo.shc will be created
...
# shc_user.alice will be created
...
# shc_vdeployment.appdb will be created
...
Plan: 5 to add, 0 to change, 0 to destroy.
...
$ tofu -chdir=learn/cluster apply -auto-approve
...
Apply complete! Resources: 5 added, 0 changed, 0 destroyed.
...
$ tofu -chdir=learn/cluster output quorum_healthy
true
$ tofu -chdir=learn/cluster output whoami_version
"1.12+1"

The cluster shows the same thing the CLI would.

work
$ ssh -F learn/cluster/ssh/config home01 sudo shc ls
STACK TENANT ENV APP STATUS NODES
...
db/appdb prod prod postgres/database running -

db and hello are in the rows above db/appdb, each running on the node the scheduler chose.

work
$ ssh -F learn/cluster/ssh/config home01 curl -s http://localhost:18080/
Hostname: 28ca18b57b87
IP: 127.0.0.1
IP: ::1
IP: 10.64.2.2
IP: 10.128.33.4
RemoteAddr: 10.128.16.1:35319
GET / HTTP/1.1
Host: localhost:18080
User-Agent: curl/8.14.1
Accept: */*
$ ssh -F learn/cluster/ssh/config home01 sudo shc user ls -t prod
...

Change a deployment the same way you grew the cluster: edit, plan, apply. Give hello two replicas and db a different initial database name. Replace the two resources in deployments.tf; everything else in the file stays.

~/learn/cluster/deployments.tf
provider "shc" {
ssh = {
hosts = module.shc.cluster_ssh_hosts
user = "admin"
private_key = module.shc.ssh_private_key
}
}
resource "shc_repo" "shc" {
name = "shc"
url = "https://selfhostedcloud.org/apps/0.1/index.yaml"
depends_on = [module.shc]
}
resource "shc_tenant" "prod" {
name = "prod"
depends_on = [module.shc]
}
resource "shc_deployment" "db" {
tenant = shc_tenant.prod.name
environment = "prod"
app = "postgres"
stack = "db"
vars = {
"postgres.database" = "lab"
}
depends_on = [module.shc]
}
resource "shc_vdeployment" "appdb" {
tenant = shc_tenant.prod.name
environment = "prod"
host_stack = shc_deployment.db.stack
vapp = "database"
instance = "appdb"
}
resource "shc_deployment" "hello" {
tenant = shc_tenant.prod.name
environment = "prod"
repo = shc_repo.shc.name
app = "whoami"
stack = "hello"
scale = {
whoami = 2
}
ports = {
"18080" = {
service = "whoami"
container = 80
}
}
}
resource "shc_user" "alice" {
tenant = shc_tenant.prod.name
username = "alice"
name = "Alice Liddell"
password = "P@ssw0rd"
grants = ["tenant:manage"]
on_destroy = var.on_destroy
depends_on = [module.shc]
}
data "shc_cluster_status" "this" {}
data "shc_catalog_app" "whoami" {
name = "whoami"
repo = shc_repo.shc.name
depends_on = [shc_repo.shc]
}
output "quorum_healthy" {
value = data.shc_cluster_status.this.quorum_healthy
}
output "whoami_version" {
value = data.shc_catalog_app.whoami.version
}
output "hello_node" {
value = shc_deployment.hello.node
}
work
$ tofu -chdir=learn/cluster plan
...
# shc_deployment.db will be updated in-place
...
# shc_deployment.hello will be updated in-place
...
Plan: 0 to add, 2 to change, 0 to destroy.
...
$ tofu -chdir=learn/cluster apply -auto-approve
...
Apply complete! Resources: 0 added, 2 changed, 0 destroyed.
...
work
$ ssh -F learn/cluster/ssh/config home01 sudo shc ls -s hello
...

Both changes were in-place updates: a variable and a scale are things the daemon changes on a running deployment, so Terraform never replaced it. An attribute that cannot change in place, like app or stack, plans a replacement instead, and the plan says so before you apply.

Three more resources and one read, in a file of their own. A tenant is a realm of its own with its own users and deployments. A constraint at cluster scope says where every deployment may run, as a selector over node labels. A backup schedule with scope = "stack" backs db up every night, and reaches the module through db as the other two do through their own depends_on. The shc_mesh data source reads the state of mesh0, the WireGuard plane between nodes that share no private network; this cluster has one, so no node runs it.

shown, not applied: this cluster's licence does not include tenancy and it has no backup repository
resource "shc_tenant" "lab" {
name = "lab"
depends_on = [module.shc]
}
resource "shc_backup_schedule" "db" {
scope = "stack"
tenant = "prod"
stack = shc_deployment.db.stack
cron = "0 3 * * *"
}
output "tenant_active" {
value = shc_tenant.lab.active
}

A tenant of your own needs a licence that includes tenancy, and a schedule needs a repository to write to: without one SHC refuses the schedule rather than keep a timer whose every fire would be skipped. Set backup.repo and backup.password for the scope first, as the backup ladder does. The two resources above are shown for the shape; the rest of this file is typed.

~/learn/cluster/more.tf
resource "shc_constraint" "cluster" {
scope = "cluster"
where = "cloud=hetzner"
reason = "every deployment stays on the Hetzner nodes"
depends_on = [module.shc]
}
data "shc_mesh" "this" {}
output "constraint_set_by" {
value = shc_constraint.cluster.set_by
}
output "mesh_nodes" {
value = data.shc_mesh.this.nodes
}
work
$ tofu -chdir=learn/cluster fmt
$ tofu -chdir=learn/cluster plan
...
# shc_constraint.cluster will be created
...
Plan: 1 to add, 0 to change, 0 to destroy.
...
$ tofu -chdir=learn/cluster apply -auto-approve
...
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
...
$ tofu -chdir=learn/cluster output constraint_set_by
...
$ tofu -chdir=learn/cluster output mesh_nodes
...
work
$ ssh -F learn/cluster/ssh/config home01 sudo shc tenant ls
...
$ ssh -F learn/cluster/ssh/config home01 sudo shc constraint ls
...
$ ssh -F learn/cluster/ssh/config home01 sudo shc backup schedule ls
...

Three resources of the provider stay off this cluster. shc_stack_ports manages only the port mappings of a deployment that already exists, which is how the module’s lb topology attaches a load balancer to the system traefik deployment; page 10 shows that topology. shc_enrollment_token and shc_cloudinit are the adopt path: a machine the module did not create gets a cloud-init document that installs shc by apt at that version and joins with a short-lived token, and the module’s own cloud-init is built the same way.

shown, not applied: the module already attaches the load balancer and joins every machine it creates
resource "shc_stack_ports" "traefik" {
tenant = "master"
stack = "traefik"
ports = {
"80" = { connection = "hetzner" }
"443" = { connection = "hetzner" }
}
}
data "shc_enrollment_token" "join" {
ttl = "15m"
}
data "shc_cloudinit" "worker" {
role = "node"
package = { version = var.shc_version }
token = data.shc_enrollment_token.join.token
cloud = "hetzner"
}

Next: DNS through the provider.