Skip to content

Commit 154edfb

Browse files
RebeccaTamachiroRebeccaTamachiro
authored
[DNS] Internal DNS initial docs (#20066)
* Create placeholder folder and pages * Adjust order and add Overview markdown components * Add Gateway and Magic WAN as related products * Add Beta callout and sidebar badge * Redefine folder structure and file names for consistency * Slight text review and add intro overview paragraph * Add placeholder sections to views and internal zones * Group how-tos and add get-started and analytics * Add siplified overview diagram * Add explanatory paragraphs for architecture overview * Add mermaid with view and internal zones examples * Remove mermaid with view and internal zones examples * Replace Features section and add Get Started placeholders * Revise intro and fill in get-started requirements * Fill in get-started steps for internal zones * Fill in get-started steps to create views * Create partial for beta callout and fill in Gateway steps * Text review and link out to connectivity from get-started * Rename setup to how-to and fill in iZone conditions * Fill in create and reference steps in internal-zones * Add links to other API operations from internal-zones.mdx * Fill in views config conditions and deletion callouts * Add beta label to h1 and adjust meta title * Get-started and internal-zones overall review * Adjust dns-views outline and fill in setup instructions and links * Move connectivity out of how-to and adjust links and order * Minor text reviews * Delete dedicated connectivity page placeholder * Move dns-views and internal-zones a level higher on the nav * Add paragraph linking out to Gateway analytics * Move conditions into partials and replace in get-started * Add example reference zone API call * Move ref zone API call into partial and replace * Fix broken links and point from get-started to dedicated pages * Add info on GraphQL schemas and dedicated log fields * Add intro paragraph about connectivity and cross-product * Separate Gateway and resolver policies to reflect plan difference * More details on reference zones logic and conditions * First pass following PM review: adjust wording * Expand architecture overview with detailed examples * Comment detail on connectivity and fill in gap re views * Add missing view condition: unique name within account * Add reference to Logpush filters and edit analytics intro * Improve zone labeling * Replace NXDOMAIN by SERVFAIL in response when view is deleted * Dedicated section to Connectivity and more details on fallback * Re-org internal-zones as folder with concept and how-to pages * Review hyperlinks based on new folder org and pages * Add dedicated page to connection options and complete list * Adjust references to connectivity from get-started * Overall text review
1 parent 3eb9b67 commit 154edfb

File tree

12 files changed

+434
-0
lines changed

12 files changed

+434
-0
lines changed

‎src/content/docs/dns/internal-dns/analytics.mdx‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Analytics and logs
4+
sidebar:
5+
order: 10
6+
---
7+
8+
Internal DNS leverages [Gateway analytics](/cloudflare-one/insights/analytics/gateway/). Below you can find information about specific fields and different methods you can use to access this data.
9+
10+
## GraphQL
11+
12+
For detailed metrics, use the [GraphQL API](/analytics/graphql-api/). Refer to the GraphQL Analytics API documentation for guidance on how to [get started](/analytics/graphql-api/getting-started/).
13+
14+
The [fields](/analytics/graphql-api/getting-started/querying-basics/) added to cover Internal DNS are the following:
15+
16+
- `InternalDNSFallbackStrategy`: The fallback strategy applied to the internal DNS response. Empty if no fallback strategy was applied.
17+
- `InternalDNSRCode`: The response code sent back by the internal DNS service.
18+
- `InternalDNSViewID`: The view identifier that was sent to the internal DNS service.
19+
- `InternalDNSZoneID`: The internal zone identifier returned by the internal DNS service.
20+
21+
## Logs
22+
23+
Leverage Logpush jobs for [Gateway DNS](/logs/reference/log-fields/account/gateway_dns/#internaldnsfallbackstrategy). For help setting up Logpush, refer to [Get started with Logs](/logs/get-started/).
24+
25+
You can also set up [Logpush filters](/logs/reference/filters/) to only push logs related to a specific [internal zone](/dns/internal-dns/internal-zones/) or [view](/dns/internal-dns/dns-views/) ID.

‎src/content/docs/dns/internal-dns/connectivity.mdx‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Connect to Gateway resolver
3+
pcx_content_type: reference
4+
sidebar:
5+
order: 8
6+
label: Connectivity
7+
---
8+
9+
To connect to Cloudflare Gateway resolver - which is [required to reach private resources in Internal DNS](/dns/internal-dns/#architecture-overview) - you can use the following options:
10+
11+
- DNS endpoints supported with [DNS locations](/cloudflare-one/connections/connect-devices/agentless/dns/locations/)
12+
- DNS over UDP/TCP port 53 (IPv4 or IPv6)
13+
- DNS over TLS
14+
- DNS over HTTPS
15+
- [Proxy Auto-Configuration (PAC) files](/cloudflare-one/connections/connect-devices/agentless/pac-files/)
16+
- [WARP device client](/cloudflare-one/connections/connect-devices/warp/)
17+
- [Clientless browser isolation](/cloudflare-one/policies/browser-isolation/setup/clientless-browser-isolation/#filter-dns-queries)
18+
- [Magic WAN](/magic-wan/zero-trust/cloudflare-gateway/)

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

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Manage DNS views
4+
sidebar:
5+
order: 3
6+
label: Views
7+
---
8+
9+
import { Details, Render } from "~/components";
10+
11+
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.
12+
13+
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.
14+
15+
## Configuration conditions
16+
17+
When setting up DNS views, observe the following conditions:
18+
19+
<Render file="internal-dns-view-conditions" />
20+
21+
## Create a view
22+
23+
Use the [Create Internal DNS View](/api/resources/dns/subresources/settings/subresources/views/methods/create/) endpoint. For each view you create, list all the internal zones that should be grouped under that view.
24+
25+
## Delete a view
26+
27+
Use the [Delete Internal DNS View](/api/resources/dns/subresources/settings/subresources/views/methods/delete/) endpoint.
28+
29+
DNS views can be deleted even if they still have internal zones linked to them. The internal DNS zones will continue to exist but will be unlinked once the view is deleted.
30+
31+
It is also possible to delete a DNS view that is being referenced by a Gateway resolver policy. In this case, queries matching the policy will return SERVFAIL.
32+
33+
## Other actions
34+
35+
- [Update a DNS view](/api/resources/dns/subresources/settings/subresources/views/methods/edit/) (`PATCH`)
36+
- [Get view details](/api/resources/dns/subresources/settings/subresources/views/methods/get/) (`GET`)
37+
- [List DNS views](/api/resources/dns/subresources/settings/subresources/views/methods/list/) (`GET`)

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

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: Get started
3+
pcx_content_type: get-started
4+
sidebar:
5+
order: 2
6+
---
7+
8+
import { TabItem, Tabs, Details, Example, Render } from "~/components";
9+
10+
Follow this guide to get started with Internal DNS.
11+
12+
Although there are some steps that can be achieved on the dashboard, currently the whole process can only be completed via API.
13+
14+
## Before you begin
15+
16+
<Render file="internal-dns-beta-note" />
17+
18+
- Make sure you have an Enterprise account with access to [Gateway resolver policies](/cloudflare-one/policies/gateway/resolver-policies/) and [Internal DNS](/dns/internal-dns/).
19+
- Consider the different ways in which you can [connect to Gateway resolver](/dns/internal-dns/connectivity/).
20+
- If you are not familiar with how to use Cloudflare API, refer to [Fundamentals](/fundamentals/api/get-started/).
21+
- If you will be using an API token for authentication, make sure you have the following permissions:
22+
23+
<Details header="API token configuration">
24+
<Example>
25+
**Permissions**
26+
- *Account* - *DNS Views* - *Edit*
27+
- *Zone* - *DNS* - *Edit*
28+
- *Account* - *Account Settings* - *Edit*
29+
- *Zone* - *DNS Settings* - *Edit*
30+
- *Zone* - *Zone* - *Edit*
31+
32+
**Account Resources**
33+
- *Include* - *(Your account)*
34+
35+
**Zone Resources**
36+
- *Include* - *All zones*
37+
38+
</ Example>
39+
</ Details>
40+
41+
42+
## 1. Set up your internal DNS zone
43+
44+
1. Use the [Create Zone](/api/resources/zones/) endpoint to create an [internal zone](/dns/internal-dns/internal-zones/). Specify your account ID and set the `type` to `internal`.
45+
46+
<Details header="Internal zone configuration conditions">
47+
<Render file="internal-zones-conditions" />
48+
</Details>
49+
50+
2. Add DNS records to your internal zone using your preferred option:
51+
- [Import](/api/resources/dns/subresources/records/methods/import/) a formatted BIND file. Refer to the [DNS records how-to](/dns/manage-dns-records/how-to/import-and-export/) for guidance.
52+
- Use other API endpoints, such as [`/batch`](/api/resources/dns/subresources/records/methods/batch/), to manage DNS records. Refer to [Batch record changes](/dns/manage-dns-records/how-to/batch-record-changes/#use-the-api) for details.
53+
3. Repeat this process for each internal zone you wish to add.
54+
55+
### (Optional) Reference a zone from another zone
56+
57+
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).
58+
59+
<Example>
60+
<Render file="internal-reference-zone-api"/>
61+
</ Example>
62+
63+
## 2. Link your internal zone to a view
64+
65+
Since the resolver policy will require a [DNS view](/dns/internal-dns/dns-views/), you must have at least one view to be able to route requests to internal zones.
66+
67+
1. Use the [Create Internal DNS View](/api/resources/dns/subresources/settings/subresources/views/methods/create/) endpoint. For each view you create, list all the internal zones that should be grouped under that view.
68+
69+
<Details header="DNS view configuration conditions">
70+
<Render file="internal-dns-view-conditions" />
71+
</Details>
72+
73+
## 3. Configure Gateway policies
74+
75+
:::note
76+
The Gateway configuration must exist within the same Cloudflare account where the internal zone exists.
77+
:::
78+
79+
Besides selecting an internal DNS view when setting up your resolver policies, you can also enable the **fallback through public DNS** option.
80+
81+
<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">
82+
83+
1. In [Zero Trust](https://one.dash.cloudflare.com/), go to **Gateway** > **Resolver policies**.
84+
2. Select **Add a policy** and enter a name and description.
85+
3. Create an expression for the traffic you wish to route. For guidance about selectors, operators, and values, refer to [Gateway](/cloudflare-one/policies/gateway/resolver-policies/#selectors).
86+
4. Select **Use DNS view**. In the dropdown, choose the view that queries matching the expression should be sent to.
87+
5. (Optional) Adjust the option to **fallback through public DNS** according to your use case.
88+
- Off: Gateway DNS resolver returns the response as-is to the client.
89+
- 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.
90+
6. Select **Create policy** to confirm.
91+
92+
</TabItem> <TabItem label="API">
93+
94+
Use the API endpoints under [Zero Trust > Gateway > Rules](/api/resources/zero_trust/subresources/gateway/subresources/rules/) to set up resolver policies. For guidance about selectors, operators, and values, refer to [Gateway](/cloudflare-one/policies/gateway/resolver-policies/#selectors).
95+
96+
Use the rule settings object to define `resolve_dns_internally`, specifying `view_id` and `fallback` option. The fallback options behave as follows:
97+
98+
- `none`: Gateway DNS resolver returns the response as-is to the client.
99+
- `public_dns`: 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.
100+
101+
</TabItem> </Tabs>

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

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
pcx_content_type: overview
3+
title: Internal DNS (beta)
4+
sidebar:
5+
order: 14
6+
label: Overview
7+
group:
8+
badge:
9+
text: Beta
10+
label: Internal DNS
11+
head:
12+
- tag: title
13+
content: Internal DNS
14+
---
15+
16+
import { Render, Description, Plan, RelatedProduct, DirectoryListing, GlossaryTooltip, Example } from "~/components";
17+
18+
<Description>
19+
Simplify private network management with Cloudflare DNS for your internal resources.
20+
</Description>
21+
22+
<Plan type="enterprise" />
23+
24+
Manage DNS records that should only be accessible within your private network. Internal DNS [zones](/dns/internal-dns/internal-zones/) and [views](/dns/internal-dns/dns-views/) pair up with [Gateway resolver policies](/cloudflare-one/policies/gateway/resolver-policies/) so that you can control how a DNS query should be responded to according to the query context, such as its source IP.
25+
26+
<Render file="internal-dns-beta-note" />
27+
28+
## Architecture overview
29+
30+
You can use different [connectivity options](/dns/internal-dns/connectivity/) to on-ramp your traffic to Cloudflare. Then, Cloudflare Gateway resolver acts as an interface between the DNS client and internal DNS zones.
31+
32+
Internal DNS zones do not get assigned Cloudflare nameservers and can only be queried via Cloudflare Gateway resolver.
33+
34+
```mermaid
35+
flowchart LR
36+
accTitle: Internal DNS query overview
37+
accDescr: Diagram comparing internal DNS query with public DNS
38+
A[Client]
39+
subgraph Cloudflare account
40+
subgraph Gateway
41+
B[Default 1.1.1.1 resolver]
42+
X[Resolver policy selecting an internal DNS view]
43+
end
44+
subgraph Authoritative DNS
45+
Y[(Public DNS)]
46+
Z[(Internal DNS)]
47+
end
48+
end
49+
50+
C[Public resolver]
51+
52+
B --Query--> Y
53+
X --Query + View ID--> Z
54+
A --Query--> B
55+
A --Query--> X
56+
C --Query--> Y
57+
```
58+
59+
Internal DNS zones are grouped into DNS views, which are selected by the resolver policy you define. Views are usually logical groupings relevant to your organization, such as different geographical locations.
60+
61+
```mermaid
62+
flowchart LR
63+
accTitle: Internal DNS views and zones
64+
accDescr: Diagram exemplifying Internal DNS views and zones relationship
65+
subgraph Internal DNS
66+
subgraph View 111 - London
67+
Y[Zone 600 <br /> example.local]
68+
Z[Zone 601 <br /> local]
69+
end
70+
subgraph View 110 - San Francisco
71+
X[Zone 101 <br /> example.com]
72+
B[Zone 100 <br /> example.local]
73+
S[Zone 102 <br /> com]
74+
end
75+
W[Zone 701 <br /> net]
76+
end
77+
```
78+
79+
Internal DNS zones contain the <GlossaryTooltip term="DNS record" link="/dns/manage-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).
80+
81+
<Example>
82+
83+
```mermaid
84+
flowchart LR
85+
accTitle: Internal DNS zones and internal records
86+
accDescr: Diagram exemplifying Internal DNS zones and records relationship
87+
subgraph View 111 - London
88+
subgraph Zone 601 - local
89+
S[@ A 192.0.2.10]
90+
T[ghi.example A 192.0.2.15]
91+
end
92+
subgraph Zone 600 - example.local
93+
X[@ A 192.0.2.1]
94+
Y[abc A 192.0.2.6]
95+
Z[def A 192.0.2.9]
96+
end
97+
end
98+
```
99+
In this example, a query for `ghi.example.local` routed to view ID 111 would go to zone 600, which presents the longest matching zone name (`example.local`). Zone 600 does not contain a record for `ghi` but, if it is referencing zone 601, Cloudflare will then look for the queried record within the reference zone.
100+
101+
</Example>
102+
103+
## Resources
104+
105+
<DirectoryListing />
106+
107+
## Related products
108+
109+
<RelatedProduct header="Cloudflare Gateway" href="/cloudflare-one/policies/gateway/" product="privacy-gateway">
110+
Set up policies to inspect DNS, Network, HTTP, and Egress traffic.
111+
</RelatedProduct>
112+
113+
<RelatedProduct header="Cloudflare Magic WAN" href="/magic-wan/" product="magic-wan">
114+
Improve security and performance for your entire corporate networking, reducing cost and operation complexity.
115+
</RelatedProduct>

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

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
pcx_content_type: concept
3+
title: Internal zones
4+
sidebar:
5+
order: 2
6+
group:
7+
label: Internal zones
8+
---
9+
10+
import { Example, Render } from "~/components";
11+
12+
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.
13+
14+
Refer to [Manage internal zones](/dns/internal-dns/internal-zones/setup/) for a full list of configuration conditions and step-by-step instructions.
15+
16+
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.
17+
18+
## Reference zones
19+
20+
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.
21+
22+
Each internal zone can only reference one other zone, but the same zone can be referenced by multiple internal zones. Public zones cannot be used as reference zones.
23+
24+
Refer to [Set up reference zones](/dns/internal-dns/internal-zones/reference-zones/) for step-by-step instructions.
25+
26+
## Internal DNS records
27+
28+
Internal zones can contain the same [DNS record types](/dns/manage-dns-records/reference/dns-record-types/) that Cloudflare supports for public zones.
29+
30+
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.
31+
32+
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.

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

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Set up reference zones
4+
sidebar:
5+
order: 4
6+
---
7+
8+
import { Example, Render } from "~/components";
9+
10+
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.
11+
12+
Each internal zone can only reference one other zone, but the same zone can be referenced by multiple internal zones. Public zones cannot be used as reference zones.
13+
14+
## Steps
15+
16+
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`.
17+
18+
<Example>
19+
<Render file="internal-reference-zone-api"/>
20+
21+
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.
22+
23+
</ Example>

0 commit comments

Comments
 (0)