> For the complete documentation index, see [llms.txt](https://docs.platform9.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.platform9.com/private-cloud-director/2026.8/virtualized-networking/external-dns-integration.md).

# External DNS Integration

<code class="expression">space.vars.product\_name</code> can integrate with DNS infrastructure that you manage outside the platform. Instead of running the built-in [DNS as a Service (DNSaaS)](/private-cloud-director/2026.8/virtualized-networking/dns-as-a-service-dnsaas.md) (Designate) stack, you can operate <code class="expression">space.vars.product\_name</code> in **External DNS** mode, where your own external or custom DNS servers remain the authoritative source of DNS, and <code class="expression">space.vars.product\_name</code> 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 <code class="expression">space.vars.product\_name</code> 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 <code class="expression">space.vars.product\_name</code> to manage DNS zones and records for your workloads. | The built-in Designate service. See [DNS as a Service (DNSaaS)](/private-cloud-director/2026.8/virtualized-networking/dns-as-a-service-dnsaas.md). |
| **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; <code class="expression">space.vars.product\_name</code> only sets the per-network DHCP search domain.           |

## Prerequisites

* At least one [Virtual Network](/private-cloud-director/2026.8/virtualized-networking/networks-and-ports.md) 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, <code class="expression">space.vars.product\_name</code> 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.

{% hint style="info" %}
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](https://support.platform9.com/). A Cluster Blueprint-based control for enabling External DNS mode directly is planned for a future release.
{% endhint %}

## 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:

{% tabs %}
{% tab title="Bash" %}

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

{% endtab %}
{% endtabs %}

Or set it at network creation time:

{% tabs %}
{% tab title="Bash" %}

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

{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="Bash" %}

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
{% endhint %}

### 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:

{% tabs %}
{% tab title="Bash" %}

```bash
$ cat /etc/resolv.conf

search customer.example.com
nameserver <DNS_SERVER_IP>
```

{% endtab %}
{% endtabs %}

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)](/private-cloud-director/2026.8/virtualized-networking/dns-as-a-service-dnsaas.md) instead if you want <code class="expression">space.vars.product\_name</code> to manage DNS zones and records.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.platform9.com/private-cloud-director/2026.8/virtualized-networking/external-dns-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.