Reference zones

During an internal DNS query resolution, if no internal record is found within a matching internal zone, Cloudflare will check if the matching internal zone is referencing another internal zone. Successive references can be followed with a maximum of five references in a chain.

Note

A wildcard record (*.example.local) in the matching internal zone will take precedence over an exact match in a referenced zone.

Configuration conditions

• Each internal zone can only reference one other zone.
• The same zone can be referenced by multiple internal zones.
• Public zones cannot be used as reference zones.
• Reference zones do not have to be linked to the same DNS view as the zone referencing them. They may also not be linked to any view at all.

Set up

To set up a reference zone, use the Update DNS settings endpoint. In --data, specify the internal_dns object with the parameter reference_zone_id.

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

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"
    }
  }'

A third zone (C) could also point to zone B as a reference, but zone A cannot add another zone as a reference while also having zone B configured as its reference zone.