Skip to content
SHC Docs

DNS through the provider

A DNS zone reaches the cluster as a connection. This page uses Cloudflare: you need a zone there and an API token that can edit its DNS. Two more values go in your login shell before you continue: TF_VAR_cloudflare_token holds the token and TF_VAR_dns_zone holds the zone name. Add them to ~/.profile as page 00 added the first two, and read it into the shell you have open.

work
$ . ~/.profile
$ test -n "$TF_VAR_cloudflare_token"
$ test -n "$TF_VAR_dns_zone"

Write dns.tf. A file may declare variables beside resources, so the two new variables live here. The connection carries the token into the cluster’s vault, and depends on module.shc as page 04’s resources do. The config row makes that connection the cluster’s default DNS provider. The record points tf.<zone> at home01’s public address. Both name the connection, so a destroy removes them, then the connection, before any node leaves.

The license-dns module computes the TXT record an estate licenses itself from. It creates nothing: the record belongs at your DNS provider, outside the reach of the daemon it licenses. With no token it still answers what the record would be called.

~/learn/cluster/dns.tf
variable "dns_zone" {
description = "A zone the Cloudflare token can edit."
type = string
}
variable "cloudflare_token" {
description = "A Cloudflare API token with DNS edit permission on the zone."
type = string
sensitive = true
}
resource "shc_connection" "dns" {
name = "cloudflare"
type = "cloudflare"
zones = [var.dns_zone]
credentials = {
token = var.cloudflare_token
}
depends_on = [module.shc]
}
resource "shc_config" "dns_provider" {
key = "dns.provider"
value = shc_connection.dns.name
}
resource "shc_dns_record" "tf" {
hostname = "tf.${var.dns_zone}"
target = module.shc.bootstrap_node.public.ipv4
dns_provider = shc_connection.dns.name
}
module "license_record" {
source = "../shc/terraform/modules/license-dns"
domain = "tf.${var.dns_zone}"
token = null
ttl = 300
}
output "dns_zones" {
value = shc_connection.dns.dns_zones
}
output "tf_record_type" {
value = shc_dns_record.tf.type
}
output "license_record_name" {
value = module.license_record.record_name
}
output "license_record_enabled" {
value = module.license_record.enabled
}

A new module needs init once more.

work
$ tofu -chdir=learn/cluster fmt
$ tofu -chdir=learn/cluster init
...
OpenTofu has been successfully initialized!
...
$ tofu -chdir=learn/cluster plan
...
# shc_config.dns_provider will be created
...
# shc_connection.dns will be created
...
# shc_dns_record.tf will be created
...
Plan: 3 to add, 0 to change, 0 to destroy.
...
$ tofu -chdir=learn/cluster apply -auto-approve
...
Apply complete! Resources: 3 added, 0 changed, 0 destroyed.
...
$ tofu -chdir=learn/cluster output dns_zones
...
$ tofu -chdir=learn/cluster output tf_record_type
"A"
$ tofu -chdir=learn/cluster output license_record_name
...
$ tofu -chdir=learn/cluster output license_record_enabled
false

The record is live in your zone. Resolve it from work and reach the published port through the name from a node.

work
$ dig +short tf.$TF_VAR_dns_zone
...
work
$ ssh -F learn/cluster/ssh/config home01 curl -s http://tf.$TF_VAR_dns_zone:18080/
Hostname: 71ab3f84c1c1
...
GET / HTTP/1.1
...
$ ssh -F learn/cluster/ssh/config home01 sudo shc connection ls
...
$ ssh -F learn/cluster/ssh/config home01 sudo shc config get dns.provider
cloudflare

When you hold a licence token minted for DNS, put it in token and set the same value as license_dns_token on module "shc": the module installs it before the joins, and the license-dns outputs give you the TXT record to publish, whole or in 255-byte chunks. The estate then reads its licence from its own zone and keeps renewing without another apply. ttl is the record’s time to live in seconds; 300 is the module’s default, short so a renewal published today is read today.

A connection the master tenant owns can be lent to another tenant for one capability with shc_connection_grant: the grantee’s deployments then mint a scoped sub-credential from it instead of seeing the token. The DNS connection on this page serves the cluster, not a tenant, so there is nothing to grant here; an object store or an IAM-capable cloud connection is what gets granted, and the s3 capability needs a boundary document.

shown, not applied: the cluster holds no connection with a capability a tenant mints against
resource "shc_connection_grant" "lab_s3" {
connection_name = "hetzner-s3"
capability = "s3"
grantee = shc_tenant.lab.name
boundary_policy = jsonencode({ buckets = ["lab-data"] })
}

Next: Upgrade.