External DNS Integration

Private Cloud Director can integrate with DNS infrastructure that you manage outside the platform. Instead of running the built-in DNS as a Service (DNSaaS) (Designate) stack, you can operate Private Cloud Director in External DNS mode, where your own external or custom DNS servers remain the authoritative source of DNS, and Private Cloud Director simply hands each virtual machine the correct DNS search domain for that DNS namespace.

This is achieved by overriding DHCP Option 15 (domain_name, the search entry in a VM's /etc/resolv.conf) on a per-network basis. Each virtual network can advertise its own search domain to the VMs attached to it, so VMs resolve short hostnames against the DNS domain that matches your external DNS provider, no Designate zones, records, or pools required.

DNS Modes

A Private Cloud Director region operates in exactly one of the following DNS modes. The two modes are mutually exclusive and are validated at startup, the network service will not start if both are enabled at the same time.

Mode	Use when	DNS is provided by
DNS as a Service (Designate)	You want Private Cloud Director to manage DNS zones and records for your workloads.	The built-in Designate service. See DNS as a Service (DNSaaS).
External DNS	You already run your own DNS (for example a corporate or region-local DNS server) and want VMs to use it.	Your external/custom DNS servers; Private Cloud Director only sets the per-network DHCP search domain.

Prerequisites

• At least one Virtual Network whose VMs use DHCP for their network configuration.
• External DNS servers reachable from the VM networks (typically advertised to VMs as DNS name servers on the subnet).
• External DNS mode enabled for the region (see below). Designate/DNSaaS integration must be disabled in this mode.

Enabling External DNS Mode

External DNS mode is enabled at the region level. When enabled, Private Cloud Director exposes a per-network DNS domain attribute (pf9_dhcp_domain) that overrides the DHCP search domain handed to VMs, and the Designate DNS integration is turned off.

External DNS mode and DNS as a Service (Designate) cannot be active simultaneously. Switching modes is a region-level change and requires a restart of the network service to take effect. If you need this mode enabled on an existing region, contact the Platform9 Support Team. A Cluster Blueprint-based control for enabling External DNS mode directly is planned for a future release.

Setting a Per-Network DNS Search Domain

Once External DNS mode is enabled, set the DNS search domain on any virtual network using the pf9_dhcp_domain property. VMs attached to that network receive this value as their DHCP search domain.

Set the domain on an existing network:

Bash

openstack network set --extra-property name=pf9_dhcp_domain,value=customer.example.com. <NETWORK_UUID>

Or set it at network creation time:

Bash

openstack network create --extra-property name=pf9_dhcp_domain,value=customer.example.com. <NETWORK_NAME>

To clear the per-network domain and fall back to the region's default domain, set the value to an empty string:

Bash

openstack network set --extra-property name=pf9_dhcp_domain,value="" <NETWORK_UUID>

A dedicated --pf9-dhcp-domain CLI flag for openstack network create/set is planned for a future release. Until then, set the domain using the --extra-property syntax shown above.

Domain Selection Priority

The DNS search domain advertised to a VM is resolved in the following order:

1. The network's pf9_dhcp_domain, if set.
2. The region's default DNS domain, if no per-network value is set.

Verifying

New VMs receive the search domain automatically when they obtain a DHCP lease. On a Linux VM attached to the network, confirm the search line in the resolver configuration:

Bash

$ cat /etc/resolv.conf

search customer.example.com
nameserver <DNS_SERVER_IP>

Short-name lookups (for example ping host1) are then completed against customer.example.com using your external DNS servers.

Behavior and Limitations

• Existing VMs continue to use their current search domain until their DHCP client refreshes the lease (at renewal, or on an interface restart or reboot); the timing depends on the network's DHCP lease duration and the guest OS. To apply a change immediately, trigger a DHCP refresh on the VM using the method appropriate to its OS (for example, sudo dhclient -r && sudo dhclient on dhclient-based Linux, or ipconfig /renew on Windows), or reboot it.
• IPv4 only. The search domain is delivered via IPv4 DHCP Option 15. DHCPv6 has no equivalent domain-search option and is unaffected.
• Manual per-port DHCP options take precedence. If a port has a domain set through manual extra_dhcp_opts, that value overrides the network's pf9_dhcp_domain for VMs on that port.
• Mutually exclusive with DNS as a Service. External DNS mode disables the Designate integration for the region. Use DNS as a Service (DNSaaS) instead if you want Private Cloud Director to manage DNS zones and records.