Skip to content
Cloudflare Docs

Get started

Follow this guide to get started with Internal DNS.

Although there are some steps that can be achieved on the dashboard, currently the whole process can only be completed via API.

Before you begin

API token configuration

Permissions

  • Account - DNS Views - Edit
  • Zone - DNS - Edit
  • Account - Account Settings - Edit
  • Zone - DNS Settings - Edit
  • Zone - Zone - Edit

Account Resources

  • Include - (Your account)

Zone Resources

  • Include - All zones

1. Set up your internal DNS zone

  1. Use the Create Zone endpoint to create an internal zone. Specify your account ID and set the type to internal.

Internal zone configuration conditions
  • Internal zones can contain the same DNS record types that Cloudflare supports for public zones.
  • An internal zone can have the same name as a public zone in the same account.
  • Each internal zone can be linked to multiple views.
  • There can be several internal zones with the same name in one account. However, two internal zones with the same name cannot be linked to the same view.
  • Internal zones are not subject to any top-level domain (TLD) restrictions. This means that an internal zone can be created if its TLD is not registered publicly (for example, xyz.local), if it is created on the TLD itself (local), or even if on the root (.).
  1. Add DNS records to your internal zone using your preferred option:
  1. Repeat this process for each internal zone you wish to add.

(Optional) Reference a zone from another zone

  1. Use the Update DNS settings endpoint to add a reference from an internal zone to another internal zone. In --data, specify the internal_dns object with the parameter reference_zone_id. For details, refer to reference zones.

In the following example, internal zone A (ID 8a904aeb565c42cfa207d98f6edea2f3) is referencing internal zone B (ID 8e64c6fb4b514f3faf64de81efc11e51).

Terminal window
curl --request PATCH \
https://api.cloudflare.com/client/v4/zones/8a904aeb565c42cfa207d98f6edea2f3/dns_settings \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
    "internal_dns": {
        "reference_zone_id": "8e64c6fb4b514f3faf64de81efc11e51"
    }
  }'

Since the resolver policy will require a DNS view, you must have at least one view to be able to route requests to internal zones.

  1. Use the Create Internal DNS View endpoint. For each view you create, list all the internal zones that should be grouped under that view.

DNS view configuration conditions
  • DNS views can be empty, with no internal zones linked to them.
  • A DNS view cannot contain public DNS zones 1.
  • Each internal DNS zone name must be unique within a given DNS view.
  • Each DNS view name must be unique within a given Cloudflare account.

Footnotes

  1. DNS zones that contain public DNS records and are accessible by public resolvers. ↩

3. Configure Gateway policies

Besides selecting an internal DNS view when setting up your resolver policies, you can also enable the fallback through public DNS option.

  1. In Zero Trust ↗, go to Gateway > Resolver policies.
  2. Select Add a policy and enter a name and description.
  3. Create an expression for the traffic you wish to route. For guidance about selectors, operators, and values, refer to Gateway.
  4. Select Use DNS view. In the dropdown, choose the view that queries matching the expression should be sent to.
  5. (Optional) Adjust the option to fallback through public DNS according to your use case.
  • Off: Gateway DNS resolver returns the response as-is to the client.
  • On: In case the response from the internal zone is REFUSED, NXDOMAIN, or a response with a CNAME type, Gateway DNS resolver sends the query to Cloudflare 1.1.1.1 public resolver and tries to resolve the query via public DNS.
  1. Select Create policy to confirm.