Skip to content
SHC Docs

A zone SHC writes

site.learn.test answers on every node, but nothing resolves the name. A DNS provider fixes that: SHC writes a record for every routed hostname into a zone the provider owns. Cloudflare, Route53, Hetzner and the other public providers are set up the same way. This page uses a PowerDNS you run on the cluster, so the whole thing stays on these two machines.

PowerDNS is two files: a compose file, and the same API key in a file of its own, so SHC reads it from the file and it never sits on a command line of yours. The last flag turns off the cache of zones PowerDNS serves from, which it refreshes every five minutes, so a zone you make after it starts answers without the wait.

~/learn/pdns/compose.yaml
services:
pdns:
image: powerdns/pdns-auth-49:4.9.4
command:
- --api=yes
- --api-key=P@ssw0rd
- --webserver=yes
- --webserver-address=0.0.0.0
- --webserver-allow-from=0.0.0.0/0
- --webserver-port=8081
- --zone-cache-refresh-interval=0
expose:
- "53"
- "53/udp"
- "8081"
~/learn/pdns/api-key
P@ssw0rd

DNS is UDP first. +udp publishes a port over UDP; without it a port is TCP. SHC keeps 53 for the resolver its daemon runs on every node, so publish 1053 for both, and 18053 for the API.

home01
$ shc install ~/learn/pdns -s dns --expose 1053+udp=pdns:53 --expose 1053=pdns:53 --expose 18053=pdns:8081
installing deployment "dns"
[dns] Healthy 1/1
✔ pdns healthy
✔ installed deployment "dns"
exposure: lan
$ shc status -s dns
...
Published ports
...
...

Three published lines, one per port and protocol. Make the zone once PowerDNS answers:

home01
$ shc exec -s dns -S pdns -- pdnsutil create-zone learn.test ns1.learn.test
Also adding one NS record
Creating empty zone 'learn.test'

Now give SHC the provider, as a connection. A connection carries its own credentials and the zones it owns, and can be granted to other tenants. --type is the provider, powerdns-local being PowerDNS with zones you declare; --purpose private says the zone answers only clients on your own networks; --zone names a zone it may write; --endpoint is the API, published on 18053 on every node; --cred takes a coordinate inline, and a secret only as key=-, read from the file --value-file names, so it is never on the command line:

home01
$ shc connection connect learn-dns --type powerdns-local --purpose private --zone learn.test --endpoint http://127.0.0.1:18053 --cred server_id=localhost --cred api_key=- --value-file ~/learn/pdns/api-key
✔ connected connection "learn-dns", providers learn-dns.dns
$ shc connection ls
NAME TYPE TENANT SCOPE DNS PURPOSE LOCATION
learn-dns powerdns-local prod tenant private learn.test private -
$ shc connection show learn-dns
...

--scope is the tier a connection is written to, tenant by default, and --tenant its owner. shc connection zones changes the zones it owns, a trailing ! taking one away, and shc connection rm removes it with its providers. A connection whose cloud also brings a load balancer takes --location, so its edge fronts one location’s nodes only:

explained, not walked: learn.test stays the one zone and the connection stays for the next pages, so none of these changes anything here
$ shc connection connect learn-dns --type powerdns-local --purpose private --zone learn.test --endpoint http://127.0.0.1:18053 --scope tenant --tenant prod --cred server_id=localhost --cred api_key=- --value-file ~/learn/pdns/api-key
$ shc connection ls --tenant prod
$ shc connection show learn-dns --tenant prod
$ shc connection zones learn-dns --zone lab.test --tenant prod
$ shc connection zones learn-dns --zone 'lab.test!' --tenant prod
$ shc connection rm learn-dns --tenant prod --yes
$ shc connection connect hz --type hetzner --purpose public --zone example.com --location learn/far --cred token=- --cred region=fsn1

A provider can also be plain config, dns.provider naming the default and dns.providers.<name>.* carrying its endpoint, zones and, in the yaml file only, its key. That is the file-config form; a connection is consulted first and the config form only when no connection owns the provider:

explained, not walked: the connection owns learn.test, and a second provider for the same zone would be a second writer of the same records
$ shc config set dns.providers.powerdns-local.endpoint http://127.0.0.1:18053
$ shc config set dns.providers.powerdns-local.zones learn.test
$ shc config set dns.provider powerdns-local

Now redeploy site. --dns-provider names the provider that writes its records:

home01
$ shc update site --dns-provider learn-dns
updating deployment "site"
[site] Healthy 1/1
✔ nginx healthy
source: /root/learn/nginx, replayed from the deployment's persisted source (path)
site: no change: nothing was updated; the re-render read the same app package, apppkg-v1:7753cc3b9cfd1d7365d699a8c416e585449bbbf8dde5839cc4c7e2ad9d264a08 from /root/learn/nginx, and produced the compose the deployment already had
$ shc dns ls
NAME TYPE VALUE ZONE CONNECTION TENANT DEPLOYMENT
site.learn.test A 65.21.55.73 learn.test learn-dns prod prod/prod/site
site.learn.test A 91.99.211.3 learn.test learn-dns prod prod/prod/site

Two records, one per node, because the route is LAN-only and every node listens for it. The same flag is on shc install. A second route on the nginx app:

home01
$ shc install ~/learn/nginx -s www --expose www.learn.test --dns-provider learn-dns
installing deployment "www"
[www] Healthy 1/1
✔ nginx healthy
✔ installed deployment "www"
exposure: lan
$ shc dns ls
...

The records point at the nodes, because nothing names another address for them. dns.lan_address and dns.public_address are the config keys that would, and dns.proxied sets Cloudflare’s proxy flag on a record:

explained, not walked: these two machines have one address each and no Cloudflare, so these would publish an address nothing answers
$ shc config set dns.lan_address 10.0.0.10
$ shc config set dns.public_address edge.learn.test
$ shc config set dns.proxied true

Ask the PowerDNS you run:

home01
$ apt-get install -y bind9-dnsutils
...
$ dig +short @127.0.0.1 -p 1053 site.learn.test
65.21.55.73
91.99.211.3
$ dig +short @127.0.0.1 -p 1053 _shc-owner.site.learn.test TXT
"heritage=shc,shc/owner=shc-44008470"
$ shc config get dns.owner_id
shc-44008470

Every record SHC writes has a companion TXT record naming this cluster as its owner, the dns.owner_id that shc init minted. SHC updates and removes only records that carry it, so two clusters can share one zone.

dns.ttl sets the time to live SHC writes; it is scoped, so one deployment can differ from the estate:

home01
$ shc config set dns.ttl 60
...
$ shc update site
updating deployment "site"
[site] Healthy 1/1
✔ nginx healthy
source: /root/learn/nginx, replayed from the deployment's persisted source (path)
site: no change: nothing was updated; the re-render read the same app package, apppkg-v1:7753cc3b9cfd1d7365d699a8c416e585449bbbf8dde5839cc4c7e2ad9d264a08 from /root/learn/nginx, and produced the compose the deployment already had
$ dig +noall +answer @127.0.0.1 -p 1053 site.learn.test
site.learn.test. 60 IN A 65.21.55.73
site.learn.test. 60 IN A 91.99.211.3

The nodes resolve routed hostnames without any of this. Each node’s daemon answers DNS itself, on the node’s mesh address, and knows every route. Ask far01’s directly:

far01
$ dig +short @10.192.0.2 site.learn.test
...

Keep dns, www and the connection. The next page reads the names from inside containers.

Next: The fabric and its policy.