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 sits | What to do with dns.public_address |
|---|---|
| On the bootstrap node, LAN-only cluster | Leave 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-exposed | Ignore 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. |
What the key actually is
Section titled “What the key actually is”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.
shc config set dns.public_address 10.10.1.1shc config get dns.public_addressReader: 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.
- an operator-fixed proxy endpoint threaded by a recover replay
- non-internet only:
dns.lan_address, thendns.public_address - the system Traefik’s web endpoint, its LB VIP, else the placed node’s own
public_address exposure: internetwith 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.
Case 1: Traefik on the bootstrap node
Section titled “Case 1: Traefik on the bootstrap node”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:
shc config set dns.public_address 10.10.1.1 # the pfSense LAN addressWhy 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.
Case 3: internet-exposed
Section titled “Case 3: internet-exposed”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:
shc node update <node> --public-address 203.0.113.10Setting dns.public_address in an attempt to fix an internet deployment
does nothing at all.
Case 4: behind a load balancer connection
Section titled “Case 4: behind a load balancer connection”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.
shc config unset dns.public_address --scope globalIf the estate is applied from Terraform, drop the key from the
shc_config document as well, or the next apply puts it back.
Diagnosing it
Section titled “Diagnosing it”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.
See also
Section titled “See also”dnsconfig keys: the full key table,dns.lan_address, TTL and proxying- DNS providers and automatic HTTPS
- DNS provider sync: the per-provider credential and Traefik env contract