Cluster Name Resolution

While signadot local connect is running, cluster service names resolve to virtual IP addresses that the CLI routes into the cluster. There are two mechanisms for this, selected per connection:

Resolver	How names resolve	Default
EtcHosts	The CLI writes an entry per cluster hostname into /etc/hosts and rewrites the file as the cluster changes.	yes
LocalDNS	The CLI runs a local DNS resolver which is authoritative for the cluster's DNS zones and wires it into your operating system's resolver configuration.	no

/etc/hosts remains the default.

Local DNS

Note

Local DNS requires v1.8.0+ of the Signadot CLI and is supported on macOS and Linux. It is opt-in.

Enable it for a connection in your CLI configuration file:

local:
  connections:
  - cluster: staging
    resolver: LocalDNS

Or per invocation, with the --local-dns flag, which overrides the configuration file for that connection:

# force local DNS for this connection
signadot local connect --cluster=staging --local-dns

# force /etc/hosts, even if the config file selects LocalDNS
signadot local connect --cluster=staging --local-dns=false

With local DNS active, the CLI answers the same name forms a cluster's DNS serves:

curl my-svc.my-ns.svc.cluster.local:8080/
curl my-svc.my-ns.svc:8080/
curl my-svc.my-ns:8080/

Names outside the cluster zones — github.com, your VPN's internal names, and anything else — are forwarded to the resolvers your machine was already using, which the CLI captures before it changes anything.

Local DNS configures the system resolver, so it needs the root privileges that signadot local connect already asks for. It cannot be combined with --unprivileged; that combination fails immediately with an error naming whether the mode came from the flag or from the configuration file.

signadot local disconnect restores your original DNS configuration. If a session exits uncleanly and leaves DNS pointed at a resolver that is no longer running, the next signadot local connect repairs the configuration on startup — in either resolution mode, so a plain reconnect is enough.

Differences from /etc/hosts

• The resolver mirrors what a real cluster serves, so names that the /etc/hosts mechanism emitted but no cluster resolves — notably my-svc.my-ns.svc.cluster — do not resolve under local DNS.
• Bare service names (my-svc, resolved against a current namespace) are not supported in either mode.
• AAAA queries return no data. Cluster names resolve over IPv4 only.

macOS and .local names

macOS reserves the .local domain for multicast DNS (Bonjour), and mDNSResponder applies that handling to any name ending in .local — including my-svc.my-ns.svc.cluster.local — regardless of resolver configuration. The caveats for .local addresses apply under local DNS as they do under /etc/hosts.

The shorter forms avoid this entirely. On macOS the CLI routes my-svc.my-ns and my-svc.my-ns.svc through resolver entries that are not under .local, so those queries never reach the multicast path. Prefer them.

Two consequences specific to this mode on macOS:

• Do not disable mDNSResponder. It is the component that reads the resolver configuration the CLI installs, and the CLI signals it to pick up changes. Disabling it stops cluster name resolution altogether.
• Services in a namespace named after a special-use domain — local, localhost, test, invalid, example, onion or arpa — do not get the bare my-svc.my-ns short form, since claiming that zone machine-wide would shadow a name the operating system reserves. The fully qualified my-svc.my-ns.svc.cluster.local still resolves.

Checking status

signadot local status reports the resolver in place of the /etc/hosts line when local DNS is active:

% signadot local status
signadot local connect has been started ✓
* runtime config: cluster staging, running with root-daemon
✓ Local connection healthy!
    * operator version 0.16.0
    * port-forward listening at ":59933"
    * localnet has been configured
    * 135 names (45 hosts) resolvable via local DNS (127.0.0.54:53)
    * sandboxes watcher is running

The name count exceeds the host count because each host is resolvable under several forms. signadot local status --details additionally reports the resolver mode, the cluster DNS suffixes it owns, and the upstream resolvers it forwards to.

On Linux, if a system DNS manager such as systemd-resolved owns /etc/resolv.conf, signadot local status prints a warning: that manager can revert the CLI's changes on the next network event, which breaks cluster name resolution until you reconnect.

Listing resolvable hosts

signadot local hosts lists the cluster hostnames currently resolvable from your machine and the address each maps to, in either resolution mode.