[iDNS] Clarify CNAME flattening and reference zones (#20891)

* Add conditional rendering for create internal zone

* Clear out unused components from internal-zone-create

* Fix syntax to make conditional property opitional

* Add .yaml file so that iDNS comes up in /products

* Update DNS records link to point to #internal-dns-records

* Create and apply partial for reference-zone-intro

* Add info about CNAME flatenning to iDNS docs

* Add note about wildcard record and reference zones

* Revert "Add .yaml file so that iDNS comes up in /products"

This reverts commit 5dff074.

* Create dedicated pages to reference zones and internal records

* Descride CNAME flattening behavior with reference zones and view

* Add CNAME flattening example

* Re-org and further detail reference zones conditions

* Remove redundant reference-zone-intro partial

* Fix link to get-started and more specific CNAME h2

* Add quotes to labels to fix mermaid diagram

* More generic CNAME flattening explanation and adjust example

* Link to more context around Gateway resolver in iDNS

Author: RebeccaTamachiro

src/content/docs/dns/cname-flattening/index.mdx

@@ -20,6 +20,10 @@ With CNAME flattening, Cloudflare finds the IP address that a CNAME points to. T
 
 For more details on the steps involved in CNAME flattening, review the [CNAME flattening diagram](/dns/cname-flattening/cname-flattening-diagram/) and refer to the [Cloudflare blog post](https://blog.cloudflare.com/introducing-cname-flattening-rfc-compliant-cnames-at-a-domains-root/).
 
+:::note
+For information about CNAME flattening in [Internal DNS](/dns/internal-dns/), refer to [internal DNS records](/dns/internal-dns/internal-zones/internal-dns-records/).
+:::
+
 ## Aspects to keep in mind
 
 * CNAME flattening happens by default in some cases. Refer to [Setup](/dns/cname-flattening/set-up-cname-flattening/) for details.

src/content/docs/dns/internal-dns/dns-views.mdx

@@ -10,7 +10,7 @@ import { Details, Render } from "~/components";
 
 Internal DNS views are logical groupings of [internal DNS zones](/dns/internal-dns/internal-zones/). As explained in the [architecture overview](/dns/internal-dns/#architecture-overview), DNS views are referenced by [Gateway resolver policies](/cloudflare-one/policies/gateway/resolver-policies/) to define how a specific query should be resolved.
 
-Refer to the sections below for details on how to manage your DNS views, or consider the [get started](/dns/internal-dns/#architecture-overview) for a complete workflow.
+Refer to the sections below for details on how to manage your DNS views, or consider the [get started](/dns/internal-dns/get-started/) for a complete workflow.
 
 ## Configuration conditions
 

src/content/docs/dns/internal-dns/get-started.mdx

@@ -47,7 +47,7 @@ Although there are some steps that can be achieved on the dashboard, currently t
 
 ### (Optional) Reference a zone from another zone
 
-1. Use the [Update DNS settings](/api/resources/dns/subresources/settings/methods/edit/) 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](/dns/internal-dns/internal-zones/#reference-zones).
+1. Use the [Update DNS settings](/api/resources/dns/subresources/settings/methods/edit/) 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](/dns/internal-dns/internal-zones/reference-zones/).
 
 <Example>
 <Render file="internal-reference-zone-api"/>

src/content/docs/dns/internal-dns/index.mdx

@@ -76,7 +76,7 @@ flowchart LR
 				end
 ```
 
-Internal DNS zones contain the <GlossaryTooltip term="DNS record" link="/dns/internal-dns/internal-zones/#internal-dns-records">DNS records</ GlossaryTooltip> that should be used to resolve an internal DNS query. Also, if no internal record is found within a matching internal zone, Cloudflare will check if the matching internal zone is [referencing another internal zone](/dns/internal-dns/internal-zones/#reference-zones).
+Internal DNS zones contain the <GlossaryTooltip term="DNS record" link="/dns/internal-dns/internal-zones/internal-dns-records/">DNS records</ GlossaryTooltip> that should be used to resolve an internal DNS query. Also, if no internal record is found within a matching internal zone, Cloudflare will check if the matching internal zone is [referencing another internal zone](/dns/internal-dns/internal-zones/reference-zones/).
 
 <Example>
 

src/content/docs/dns/internal-dns/internal-zones/index.mdx

@@ -7,24 +7,14 @@ sidebar:
     label: Internal zones
 ---
 
-import { Example, Render } from "~/components";
+import { Example, Render, DirectoryListing } from "~/components";
 
-Internal DNS zones are groupings of internal DNS records. While [public DNS records](/dns/manage-dns-records/) contain information about resources that you want to make available to the public Internet, [internal DNS records](#internal-dns-records) allow you to manage resources that should only be available within your private network.
+Internal DNS zones are groupings of internal DNS records. While [public DNS records](/dns/manage-dns-records/) contain information about resources that you want to make available to the public Internet, [internal DNS records](/dns/internal-dns/internal-zones/internal-dns-records/) allow you to manage resources that should only be available within your private network.
 
 Refer to [Manage internal zones](/dns/internal-dns/internal-zones/setup/) for a full list of configuration conditions and step-by-step instructions.
 
 Internal DNS zones do not get assigned Cloudflare nameservers and can only be queried via [Cloudflare Gateway](/cloudflare-one/policies/gateway/resolver-policies/) when linked to a [DNS view](/dns/internal-dns/dns-views/). The Gateway configuration must exist within the same Cloudflare account where the internal zone exists.
 
-## Reference zones
+## Resources
 
-<Render file="reference-zone-intro" />
-
-Refer to [Set up reference zones](/dns/internal-dns/internal-zones/reference-zones/) for step-by-step instructions.
-
-## Internal DNS records
-
-Internal zones can contain the same [DNS record types](/dns/manage-dns-records/reference/dns-record-types/) that Cloudflare supports for public zones.
-
-You can manage internal DNS records in the same way as you would manage public DNS records, with the difference that [proxy status](/dns/proxy-status/) does not apply to internal DNS records.
-
-Refer to [Manage DNS records](/dns/manage-dns-records/how-to/create-dns-records/) or to the [API documentation](/api/resources/dns/subresources/records/) for further guidance.
+<DirectoryListing />

src/content/docs/dns/internal-dns/internal-zones/internal-dns-records.mdx

@@ -0,0 +1,60 @@
+---
+pcx_content_type: concept
+title: Manage internal DNS records
+sidebar:
+  order: 4
+  label: Internal DNS records
+---
+
+import { Details, Example } from "~/components";
+
+Internal zones can contain the same [DNS record types](/dns/manage-dns-records/reference/dns-record-types/) that Cloudflare supports for public zones.
+
+You can manage internal DNS records in the same way as you would manage public DNS records, with the difference that [proxy status](/dns/proxy-status/) does not apply to internal DNS records.
+
+Refer to [Manage DNS records](/dns/manage-dns-records/how-to/create-dns-records/) or to the [API documentation](/api/resources/dns/subresources/records/) for further guidance.
+
+## CNAME flattening in Internal DNS
+
+With CNAME flattening, Cloudflare finds the final target content that a CNAME points to and then returns this content instead of a CNAME record. With Internal DNS, CNAME flattening is applied by default and cannot be turned off.
+
+Cloudflare will try to flatten the CNAME record considering both the specified [DNS view](/dns/internal-dns/dns-views/) and any existing [reference zones](/dns/internal-dns/internal-zones/reference-zones/). If the reference zone then has another CNAME, the record will again be considered from the perspective of the original view.
+
+<Details header="Example">
+
+- Query for the `A` record on `abc.example.local` with view ID 111.
+- Zone 600 references zone 700, which is not linked to any view.
+
+```mermaid
+flowchart LR
+accTitle: Internal DNS zones and CNAME flattening example
+accDescr: Diagram exemplifying Internal DNS zones and containing CNAME and A records
+
+subgraph Internal DNS
+subgraph Zone 700 - net
+A["@ A 192.0.2.10"]
+B["xyz CNAME def.example.local"]
+end
+subgraph View 111 - London
+subgraph Zone 600 - example.local
+X["@ A 192.0.2.1"]
+Y["abc CNAME xyz.net"]
+U["def TXT 15192-51"]
+Z["def A 192.0.2.9"]
+end
+end
+end
+```
+
+After finding the CNAME record that points to `xyz.net`, Cloudflare cannot resolve it within zone 600. However, since this zone is referencing zone 700, this will be considered in the resolution.
+
+The record in zone 700 points to `def.example.local`, which Cloudflare will then try to resolve in the original view. As an `A` record can be found for `def.example.local`, Cloudflare will return the corresponding IP address - in this example, `192.0.2.9`.
+
+</Details>
+
+If it is not possible to flatten the CNAME record, the following will happen:
+
+1. The CNAME record is returned to [Gateway resolver](/dns/internal-dns/#architecture-overview) as-is.
+2. Gateway resolver will process the returned record, depending on the **Fallback through public DNS** configuration:
+    - On: Gateway will try to resolve the query by sending it to Cloudflare's public DNS resolver ([1.1.1.1](/1.1.1.1/)).
+    - Off: Gateway will return the response as-is to the client.

src/content/docs/dns/internal-dns/internal-zones/reference-zones.mdx

@@ -1,15 +1,26 @@
 ---
 pcx_content_type: how-to
-title: Set up reference zones
+title: Reference zones
 sidebar:
   order: 4
 ---
 
 import { Example, Render } from "~/components";
 
-<Render file="reference-zone-intro" />
+During an [internal DNS query resolution](/dns/internal-dns/#architecture-overview), 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.
 
-## Steps
+:::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](/dns/internal-dns/dns-views/) 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](/api/resources/dns/subresources/settings/methods/edit/) endpoint. In `--data`, specify the `internal_dns` object with the parameter `reference_zone_id`.
 

src/content/docs/dns/internal-dns/internal-zones/setup.mdx

@@ -7,7 +7,7 @@ sidebar:
 
 import { Example, Render } from "~/components";
 
-Refer to the following sections to learn how to manage your internal DNS zones.
+Refer to the following sections to learn how to manage your [internal DNS zones](/dns/internal-dns/internal-zones/).
 
 ## Configuration conditions