Skip to content
SHC Docs

The cluster entrypoint (dns.public_address)

dns.public_address names where traffic enters a non-internet cluster. It is not advisory and it is not a hint: on a LAN topology the value is copied verbatim into every managed DNS record SHC creates for an HTTP --expose. Get it wrong and every record is syntactically valid, the certificate issues, the route works from the node itself, and no client can reach anything.

Four placements, four different answers. Pick yours before reading the rest.

Where Traefik sitsWhat to do with dns.public_address
On the bootstrap node, LAN-only clusterLeave the default. It is already the bootstrap node’s IP.
Behind a router/firewall that fronts the cluster (pfSense, OPNsense, any NAT edge)Set it to the appliance’s IP. The default is wrong and fails silently.
Internet-exposedIgnore it. The key is never read; DNS follows the system Traefik’s placement.
Behind a load balancer the system Traefik’s web ports ride (--expose 80@<connection>=traefik:80: a pfSense SHC drives, a cloud LB)Leave it unset. DNS takes the address that connection publishes.

A scoped config key, resolved through the full cascade (deployment > stack > environment > tenant > global), holding an IP or a hostname. Record type is auto-classified from the value: IPv4 → A, IPv6 → AAAA, name → CNAME. There is no forced-type syntax.

Terminal window
shc config set dns.public_address 10.10.1.1
shc config get dns.public_address

Reader: DefaultNodePublicAddress in modules/app/dns_target.go (ce), which does the cascade lookup and returns "" when unset. The key name is pinned end to end by the provider’s shc_config acceptance test (terraform/provider/internal/provider/config_resource_test.go:165 asserts dns.public_address round-trips through a shc_config YAML document), so a rename reds that test rather than silently re-scoping the estate.

It sits on rung 2 of the DNS target ladder, after dns.lan_address. ResolveDNSTargets in dns_target.go is the ladder. app.example.com=lb.example.com is refused (X400995HSTTGT) and is not a rung.

  1. an operator-fixed proxy endpoint threaded by a recover replay
  2. non-internet only: dns.lan_address, then dns.public_address
  3. the system Traefik’s web endpoint, its LB VIP, else the placed node’s own public_address
  4. exposure: internet with nothing public: defer, X200980DNSDEF

Note dns.lan_address outranks it. That key is the per-deployment publication knob, so a narrower private value overrides the estate-wide entrypoint; see dns.lan_address.


Nothing to do. The Terraform front doors already seed the key with the bootstrap node’s address: the cloud example roots set

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

and the core module writes it from topology.public_address on a lan topology (terraform/modules/core/main.tf:549, resource shc_config.lan_public_address). Traffic enters at the node, records point at the node, done.

Re-check it after anything that moves the edge: a node rotation, a Traefik replacement, adding a load balancer. The key does not follow Traefik around; it is a declared value.

Case 2: behind a pfSense (the one that bites)

Section titled “Case 2: behind a pfSense (the one that bites)”

The cluster’s nodes sit on a private network. A pfSense (or OPNsense, or a VyOS box) holds the LAN gateway and is the only thing clients can dial. This is the case where the default is actively harmful.

Set it to the appliance’s address:

Terminal window
shc config set dns.public_address 10.10.1.1 # the pfSense LAN address

Why it matters more here than anywhere else: SHC writes this string into every record it creates. Left at a node IP, each shc install --expose … produces a record pointing at an address that only exists on the far side of the firewall. Nothing fails. The install is green, the route is real, the certificate is valid, and the hostname resolves, to somewhere the client cannot get to. There is no error to grep for, because from the platform’s point of view nothing went wrong.

The related trap is the return path. If networks behind the appliance (an office LAN over WireGuard, a VPN client pool) need to reach a node, the node’s reply has no matching route and leaves by the default route out the public NIC: asymmetric, silent, and it reads as a firewall problem for a week. Close each prefix with the routes input on the cloud module rather than debugging it live.

If different client populations reach the cluster on different planes (a pfSense LAN and a NetBird overlay, say), do not try to encode that here. dns.public_address takes one address. Carve the per-deployment cases with dns.lan_address, which is scoped and ranks above it.

Leave it alone. Internet exposure never reads this key; the old fallback that did was removed. Public endpoints are inferred instead: the system Traefik’s web-connection VIP when it has one, otherwise the placed node’s own public_address (a node-row field, not this config key).

A private or loopback address in that node field is treated as absent: internet DNS fails closed rather than publishing RFC1918. The symptom is a deferred registration carrying X200980DNSDEF, and the repair is the node row, not config:

Terminal window
shc node update <node> --public-address 203.0.113.10

Setting dns.public_address in an attempt to fix an internet deployment does nothing at all.

Here the front is not just in the path, SHC drives it: the system Traefik’s web ports ride a connection’s load balancer (--expose 80@pfsense=traefik:80), and that connection publishes the address clients dial. A pfSense HAProxy SHC programs is the usual one. It holds the public address, so no node row carries it.

Leave the key unset. Internet DNS takes the connection’s published address, and so does a non-internet HTTP host when the key is unset, so a value equal to the front changes no HTTP record. What it does change is a non-internet plain L4 hostname (--expose 5432 with no @connection): the key outranks the nodes that listen, so that record points at the front, and a front that forwards only 80 and 443 answers nothing there.

shc doctor run --category app says which one you have. app.dns-estate-agreement reads a key equal to the connection’s address as info and names the unset; a key that neither a node row nor the connection carries is still the failed-brake warning.

Terminal window
shc config unset dns.public_address --scope global

If the estate is applied from Terraform, drop the key from the shc_config document as well, or the next apply puts it back.


shc doctor run --category dns carries dns.no-provider-for-host, which compares every host the estate intends to publish against every zone a provider could publish through. It answers “why is there no record”, which is the other half of “why is the record wrong”. A host with no owning connection is invisible to the ownership census by construction; see After shc init.

If something outside the cluster publishes some of these hosts, such as the service that provisioned it, name their zone in dns.externally_published_zones (comma- or space-separated, global scope) and the check leaves them alone. It still warns about every other host.