Skip to main content

Set up private and split DNS

Inspect 1.36

Workloads often need to resolve private hostnames—such as on-premises databases or VPC resources—without exposing internal records on the public internet. Because Syself Autopilot manages and reconciles CoreDNS automatically, you configure private name resolution by pointing the cluster's upstream resolver (dnsServers) to your internal name servers and leveraging cluster-internal Services. This guide explains how upstream forwarding works, how to configure private zones, and critical constraints around control-plane DNS.

Resolve private names through the cluster's upstream

CoreDNS resolves cluster-internal queries (.cluster.local) directly and forwards all non-cluster traffic to the node's upstream resolver. You configure this upstream resolver cluster-wide using the dnsServers topology variable on the Cluster object:

cluster.yamlyaml
		spec:
  topology:
    variables:
      - name: dnsServers
        value: ["10.100.0.53"]

Because CoreDNS is platform-managed, custom per-zone stub domains (such as a conditional forward block for a single internal zone) cannot be configured directly in the Corefile. Instead, all non-cluster DNS traffic routes through the servers configured in dnsServers.

Point dnsServers at a DNS resolver that can serve both internal and external zones such as an on-premises nameserver reached over your . This resolver must answer queries for your private domains directly and recursively forward all other requests to the public internet.

Internal-only Services

In-cluster communication remains private by default. Standard ClusterIP Services allocate a virtual IP reachable exclusively within the cluster network, while headless Services (clusterIP: None) resolve directly to ready pod IPs for predictable per-pod DNS identities. Neither type provisions an external load balancer or publishes public DNS records—making them ideal for internal databases, caches, and inter-service APIs.

The API endpoint must resolve publicly

The cluster's API endpoint name is where split DNS matters most. That name must resolve to the control-plane load balancer from Syself's side, not only from your own machine, because the controllers that manage your cluster connect through the same name.

Warning

Never give the API endpoint a name that only you can resolve, an /etc/hosts entry, or a split-horizon view that answers differently inside your own network. If the name does not resolve to the load balancer from the management side, the cluster never finishes provisioning and the control plane remains unavailable. Publish a real, public A record for the endpoint name. See for the endpoint DNS setup.

Restricting who may reach the API is a separate concern from resolving its name; that is the allowlist's responsibility, not DNS's. See .

Where to go next

Rotate and renew certificates

How cert-manager renews certificates before they expire, and how to force, monitor, and recover a rotation.

Configure a Hetzner load balancer

Tune the control-plane load balancer with topology variables and per-Service load balancers with annotations, including the full annotation reference.