Skip to content

Commit 060e209

Browse files
RebeccaTamachiroRebeccaTamachiro
authored
[DNS] Records batched operations (#16984)
* Create new page for DNS records batch operations * Adjust pages order within how-to folder * Fill in intro and add more to the outline * Adjust pages order to ascending complexity and specificity * Make Dash h3s more generic and fill in content placeholders * More specific on UI capabilities and add different Free limits * Fix typo * Fill in Dash deletion section * Fill in API intro and operations requirements following PM feedback * Overall review and add execution order and fail API behavior * Fill in Dashboard instructions for editing proxy status * Remove use-cases section and change mixed status callout to Note * Text review * Reference batch option from subdomain setup instructions * Reference batch option from the delete-all-records page * Fix record limit * Mention tags and comments are also supported and cross-link * Process PM feedback * Fix required fields for 'puts' and update example * Update example * More visible and detailed callout around propagation * Update note with Eng feedback * Replace TBDs with actual URL references * Overall review and fix typo * Remove specific blog link - to be added again later * Improve manage DNS records page and link to batched option * Overall review and improve text for clarity
1 parent 0d2d570 commit 060e209

File tree

14 files changed

+209
-31
lines changed

14 files changed

+209
-31
lines changed

‎src/content/docs/dns/manage-dns-records/how-to/batch-record-changes.mdx‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Batch record changes
4+
sidebar:
5+
order: 7
6+
---
7+
8+
import { GlossaryTooltip, Example, Render } from "~/components";
9+
10+
Cloudflare allows you to apply several changes to your zone records in just one action. You can [use the dashboard](#use-the-dashboard) to delete DNS records or update their <GlossaryTooltip term="proxy status">proxy status</GlossaryTooltip> in bulk, or [use the API](#use-the-api) to perform further batched operations.
11+
12+
:::caution[Propagation through the Cloudflare network]
13+
Although Cloudflare will execute the batched operations in a single [database transaction](https://en.wikipedia.org/wiki/Database_transaction), Cloudflare's distributed KV store must treat each record change as a single key-value pair. This means that the propagation of changes is not atomic. Refer to our [blog post](https://blog.cloudflare.com/) for details.
14+
:::
15+
16+
## Availability and limits
17+
18+
Batch DNS record changes is available on all plans.
19+
20+
The number of records that you can operate with in one action depends on your zone plan:
21+
22+
- Free: 200
23+
- Pro: 3,500
24+
- Business: 3,500
25+
- Enterprise: 3,500
26+
27+
---
28+
29+
## Use the dashboard
30+
31+
### Edit proxy status in bulk
32+
33+
`A`,`AAAA`, and `CNAME` records can be [proxied](/dns/manage-dns-records/reference/proxied-dns-records/). The **Proxy status** of a DNS record affects [how Cloudflare responds to DNS queries](/fundamentals/concepts/how-cloudflare-works/) to that record.
34+
35+
<Render file="mix-proxied-and-unproxied" product="dns" />
36+
37+
1. Go to [**DNS** > **Records**](https://dash.cloudflare.com/?to=/:account/:zone/dns/records).
38+
2. Select the DNS records you want to set the proxy status for. Note that only `A`, `AAAA`, and `CNAME` records can be proxied.
39+
3. Select **Edit records**.
40+
4. Choose the proxy status you want to apply to the selected records.
41+
5. Select **Save** to confirm.
42+
43+
You can only set records to either **Proxied** or **DNS only** in bulk. This means that if your selection includes both proxied and DNS-only records, some of them will have the proxy status updated while others will keep their original value:
44+
45+
<Example>
46+
47+
For example, if you select the following records and then edit their proxy status in bulk, choosing **Proxied** in [step 4 above](#edit-proxy-status-in-bulk), the outcome will be:
48+
49+
| Selected records | Original proxy status | Resulting proxy status |
50+
| ---------------- | --------------------- | ---------------------- |
51+
| `www` | DNS only | Proxied |
52+
| `blog` | DNS only | Proxied |
53+
| `docs` | Proxied | Proxied |
54+
55+
</Example>
56+
57+
### Delete records in bulk
58+
59+
:::caution
60+
61+
Deleting DNS records can cause downtime and cannot be reverted. Make sure you only select DNS records that you can safely delete.
62+
63+
:::
64+
65+
1. Go to [**DNS** > **Records**](https://dash.cloudflare.com/?to=/:account/:zone/dns/records).
66+
2. Select the DNS records you want to delete.
67+
3. Select **Delete records**.
68+
4. In the **Delete DNS records** prompt, type in `DELETE` and select **Delete** to confirm.
69+
70+
## Use the API
71+
72+
:::note
73+
74+
This option requires familiarity with API usage and concepts. For further information about the Cloudflare API, refer to [Fundamentals](/fundamentals/api/get-started/).
75+
76+
:::
77+
78+
The [Batched DNS record changes](/api/operations/dns-records-for-a-zone-batch-dns-records) endpoint allows you to trigger the execution of `DELETES`, `PATCHES`, `PUTS`, and `POSTS` in a single request.
79+
80+
[Tags and comments](/dns/manage-dns-records/reference/record-attributes/) are also supported with batch changes.
81+
82+
The operations you specify within the `/batch` request body are always executed in the following order:
83+
84+
1. Deletes
85+
2. Patches
86+
3. Puts
87+
4. Posts
88+
89+
Within each of these four lists, each individual action is executed following the DNS records order you provide. If any of the individual action fails, no changes are applied and the API returns the first error it encountered.
90+
91+
### Aspects to consider
92+
93+
:::caution[Propagation through the Cloudflare network]
94+
Although Cloudflare will execute the batched operations in a single [database transaction](https://en.wikipedia.org/wiki/Database_transaction), Cloudflare's distributed KV store must treat each record change as a single key-value pair. This means that the propagation of changes is not atomic. Refer to our [blog post](https://blog.cloudflare.com/) for details.
95+
:::
96+
97+
For each operation that you list in the `/batch` request body, consider the required information and how unspecified fields will behave:
98+
99+
- **`deletes`**: only the `id` is required for each record object. You can keep additional parameters such as `name` for readability, but any other fields aside from `id` will be ignored in this case.
100+
- **`patches`**: aside from each record `id`, you should specify the fields you want to update. All unspecified fields will remain as they are.
101+
- **`puts`**: you must specify each record `id`, `content`, `name`, and `type`. You should also specify any other fields you want to set to a value that is not the default. Any unspecified fields will assume their default value for each [record type](/dns/manage-dns-records/reference/dns-record-types/). This operation works as an overwrite, so all fields in a given record are always affected.
102+
- **`posts`**: since you are creating a new record, `id` is not required. For field definitions, refer to the [Create DNS Record](/api/operations/dns-records-for-a-zone-create-dns-record) endpoint and select the desired record type under the request body specification.
103+
104+
### Example request
105+
106+
In this example, the `proxied` field for the first record listed under `"puts"` will assume the default value (`false`).
107+
108+
```bash
109+
{
110+
"deletes": [
111+
{
112+
"id": "2bff0ebc4df64beaa44b0dca93e37a28"
113+
},
114+
{
115+
"id": "31d1d6e79ce04b8d93cbc5a13401d728"
116+
}
117+
],
118+
"patches": [
119+
{
120+
"id": "62276440f783445380480484648c1017",
121+
"content": "192.0.2.46"
122+
},
123+
{
124+
"id": "c942d948dc2343b9b97aed78479c9fb9",
125+
"name": "update.example.com",
126+
"proxied": true
127+
}
128+
],
129+
"puts": [
130+
{
131+
"id": "a50364543094428abde0f14061d42b0e",
132+
"content": "192.0.2.50",
133+
"name": "change.example.com",
134+
"type": "A",
135+
"ttl:": 1
136+
},
137+
{
138+
"id": "3bce0920f19d43949498bd067b05dfa9",
139+
"content": "192.0.2.45",
140+
"name": "no-change.example.com",
141+
"type": "A",
142+
"proxied": false,
143+
"ttl:": 3000
144+
}
145+
],
146+
"posts": [
147+
{
148+
"name": "@",
149+
"type": "A",
150+
"content": "192.0.2.41",
151+
"proxied": false,
152+
"ttl": 3000
153+
},
154+
{
155+
"name": "a.example.com",
156+
"type": "A",
157+
"content": "192.0.2.42",
158+
"proxied": true
159+
}
160+
]
161+
}
162+
```

‎src/content/docs/dns/manage-dns-records/how-to/create-dns-records.mdx‎

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,13 @@ sidebar:
55
order: 1
66
---
77

8-
import { GlossaryTooltip, Render, TabItem, Tabs } from "~/components";
8+
import { GlossaryTooltip, Render, TabItem, Tabs, Details } from "~/components";
99

10-
<Render file="dns-scan-intro" /> <br />
10+
<Render file="dns-scan-intro" />
1111

12+
<Details header="When the quick scan is not automatically invoked">
1213
<Render file="dns-scan-note" />
14+
</ Details>
1315

1416
<Render file="dns-scan-procedure" />
1517

@@ -29,13 +31,13 @@ To create a DNS record in the dashboard:
2931

3032
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select an account and domain.
3133
2. Go to **DNS** > **Records**.
32-
3. Click **Add record**.
34+
3. Select **Add record**.
3335
4. Choose a record [**Type**](/dns/manage-dns-records/reference/dns-record-types/).
3436
5. Complete the required fields, which vary per record. Particularly important fields (for some records) include:
3537
- **Proxy status**: For `A`, `AAAA`, and `CNAME` records, decide whether hostname traffic is <GlossaryTooltip term="proxy status" link="/dns/manage-dns-records/reference/proxied-dns-records/">proxied through Cloudflare</GlossaryTooltip>.
3638
- **TTL**: Short for [_Time to Live_](/dns/manage-dns-records/reference/ttl/), this field controls how long each record is valid and — as a result — how long it takes for record updates to reach your end users.
3739
- **Comment** and **Tag**: [Record attributes](/dns/manage-dns-records/reference/record-attributes/) meant for your reference.
38-
6. Click **Save**.
40+
6. Select **Save**.
3941

4042
</TabItem>
4143

@@ -57,9 +59,9 @@ To edit DNS records in the dashboard:
5759

5860
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select an account and domain.
5961
2. Go to **DNS** > **Records**.
60-
3. On a specific record, click **Edit**.
62+
3. On a specific record, select **Edit**.
6163
4. Make any necessary changes.
62-
5. Click **Save**.
64+
5. Select **Save**.
6365

6466
</TabItem>
6567

@@ -79,9 +81,9 @@ To delete DNS records in the dashboard:
7981

8082
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select an account and domain.
8183
2. Go to **DNS** > **Records**.
82-
3. On a specific record, click **Edit**.
83-
4. Click **Delete**.
84-
5. Click **Delete** again to confirm.
84+
3. On a specific record, select **Edit**.
85+
4. Select **Delete**.
86+
5. Select **Delete** again to confirm.
8587

8688
</TabItem>
8789

@@ -90,3 +92,9 @@ To delete DNS records in the dashboard:
9092
To delete records with the API, use a [DELETE request](/api/operations/dns-records-for-a-zone-delete-dns-record).
9193

9294
</TabItem> </Tabs>
95+
96+
---
97+
98+
## Batch record changes
99+
100+
For guidance on how to apply several changes to your zone records in just one action, refer to [Batch record changes](/dns/manage-dns-records/how-to/batch-record-changes/).

‎src/content/docs/dns/manage-dns-records/how-to/create-subdomain.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
pcx_content_type: reference
33
title: Create subdomain records
44
sidebar:
5-
order: 4
5+
order: 3
66

77
---
88

‎src/content/docs/dns/manage-dns-records/how-to/create-zone-apex.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
pcx_content_type: reference
33
title: Create zone apex record
44
sidebar:
5-
order: 3
5+
order: 2
66

77
---
88

‎src/content/docs/dns/manage-dns-records/how-to/email-records.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
pcx_content_type: how-to
33
title: Set up email records
44
sidebar:
5-
order: 5
5+
order: 4
66

77
---
88

‎src/content/docs/dns/manage-dns-records/how-to/import-and-export.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
pcx_content_type: how-to
33
title: Import and export records
44
sidebar:
5-
order: 2
5+
order: 6
66
---
77

88
import { Render, TabItem, Tabs } from "~/components";

‎src/content/docs/dns/manage-dns-records/how-to/managing-dynamic-ip-addresses.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
pcx_content_type: reference
33
title: Dynamically update DNS records
44
sidebar:
5-
order: 6
5+
order: 9
66

77
---
88

‎src/content/docs/dns/manage-dns-records/how-to/round-robin-dns.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
pcx_content_type: reference
33
title: Round-robin DNS
44
sidebar:
5-
order: 7
5+
order: 10
66

77
---
88

‎src/content/docs/dns/manage-dns-records/reference/record-attributes.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ Comments and tags are only supported for [full](/dns/zone-setups/full-setup/) an
4949

5050
Create or edit record attributes just like any other aspect of DNS records, whether through the [dashboard](/dns/manage-dns-records/how-to/create-dns-records/) or [API](/api/operations/dns-records-for-a-zone-create-dns-record).
5151

52-
You can also add or edit attributes by [exporting and re-importing](/dns/manage-dns-records/how-to/import-and-export/#dns-record-attributes) your records.
52+
You can also add or edit attributes by [exporting and re-importing](/dns/manage-dns-records/how-to/import-and-export/#dns-record-attributes) your records, or using the [Batch record changes API](/dns/manage-dns-records/how-to/batch-record-changes/#use-the-api).
5353

5454
***
5555

‎src/content/docs/dns/zone-setups/full-setup/setup.mdx‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,9 @@ When you start using Cloudflare's nameservers for authoritative DNS and your zon
5252

5353
<Render file="dns-scan-intro" /> <br />
5454

55+
:::note
5556
<Render file="dns-scan-note" />
57+
:::
5658

5759
<Render file="dns-scan-procedure" />
5860

@@ -78,7 +80,7 @@ When you start using Cloudflare's nameservers for authoritative DNS and your zon
7880

7981
:::note
8082

81-
Cloudflare automatically assigns nameservers to a domain and these assignments cannot be changed. For more details, refer to [Nameserver assignments](/dns/zone-setups/reference/nameserver-assignment/).
83+
Cloudflare automatically assigns nameservers to a domain and these assignments cannot be changed. For more details, refer to [Nameserver assignments](/dns/zone-setups/reference/nameserver-assignment/).
8284
:::
8385

8486
### Update your registrar
@@ -87,7 +89,7 @@ Cloudflare automatically assigns nameservers to a domain and these assignments c
8789

8890
:::note
8991

90-
Depending on your use case, you may have to perform this step on the DNS records management of your domain parent zone, or at a domain reseller, instead. Refer to [Nameservers](/dns/nameservers/update-nameservers/#specific-processes) for details.
92+
Depending on your use case, you may have to perform this step on the DNS records management of your domain parent zone, or at a domain reseller, instead. Refer to [Nameservers](/dns/nameservers/update-nameservers/#specific-processes) for details.
9193
:::
9294

9395
2. Remove your existing authoritative nameservers.

0 commit comments

Comments
 (0)