Skip to content

Commit 8c306ac

Browse files
grstnhbrgrstnhbr
authored
[Cloudflare One] Add maximum DNS TTL documentation and changelog entry (#32386)
1 parent f2a5268 commit 8c306ac

3 files changed

Lines changed: 151 additions & 0 deletions

File tree

‎src/assets/images/changelog/cloudflare-one/gateway-max-ttl-traffic-settings.png‎

68 KB
Loading

‎src/content/changelog/cloudflare-one/2026-07-28-gateway-maximum-dns-ttl.mdx‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Control Cloudflare Gateway DNS caching with a maximum TTL setting
3+
description: Cloudflare One admins can now set a maximum time-to-live (TTL) for DNS responses at the account level and override it per DNS location.
4+
date: 2026-07-28
5+
products:
6+
- cloudflare-one
7+
- gateway
8+
---
9+
10+
You can now set a maximum time-to-live (TTL) for DNS responses returned by Gateway. When an upstream DNS record has a TTL that exceeds the configured maximum, Gateway caps it to your specified value. This ensures that DNS policy changes - such as blocking a newly identified malicious domain - take effect faster across all clients.
11+
12+
![The maximum DNS TTL setting in Traffic policies > Traffic settings, showing a numeric input field that accepts values between 60 and 36,000 seconds](~/assets/images/changelog/cloudflare-one/gateway-max-ttl-traffic-settings.png)
13+
14+
The setting is available at two levels:
15+
16+
- **Account level** - In **Traffic Policies** > **Traffic Settings**, under **Proxy and inspection**. This sets the default cap for all DNS locations.
17+
- **Per-location** - Each [DNS location](/cloudflare-one/networks/resolvers-proxies/) can inherit the account setting, disable the cap, or override it with a custom value.
18+
19+
Two new fields are also available in DNS logs: `upstream_record_ttls` (the original TTL from the upstream response) and `applied_max_ttl` (the cap Gateway applied). These appear in the DNS logs column picker and in Logpush datasets.
20+
21+
For more information, refer to [Maximum DNS TTL](/cloudflare-one/traffic-policies/dns-policies/maximum-dns-ttl/).

‎src/content/docs/cloudflare-one/traffic-policies/dns-policies/maximum-dns-ttl.mdx‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Maximum DNS TTL
4+
description: Set a maximum time-to-live (TTL) for DNS responses returned by Gateway to ensure policy changes propagate faster.
5+
products:
6+
- cloudflare-one
7+
sidebar:
8+
order: 5
9+
---
10+
11+
import { Tabs, TabItem } from "~/components";
12+
13+
Set a maximum time-to-live (TTL) for DNS responses returned by Gateway. When an upstream DNS record has a TTL that exceeds the configured maximum, Gateway caps the TTL to the value you specify. Lower values ensure that DNS policy changes - such as blocking a newly identified malicious domain - take effect faster across all clients, at the cost of increased query volume from reduced caching.
14+
15+
The maximum TTL cap only applies to upstream-derived DNS answers for allowed queries. Gateway-generated responses (blocks, overrides, safe-search answers) are not affected because they already use a short default TTL.
16+
17+
## How it works
18+
19+
Gateway applies a tiered TTL hierarchy. The most specific setting takes precedence:
20+
21+
1. If the DNS location has a per-location override, that value is used.
22+
2. If the location inherits its setting, the account-level maximum TTL is used.
23+
3. If no maximum TTL is configured at any level, upstream TTL values pass through unchanged.
24+
25+
The valid range for any maximum TTL value is **60 to 36,000 seconds** (1 minute to 10 hours).
26+
27+
## Configure the account-level maximum TTL
28+
29+
The account-level setting applies to all DNS locations that do not have a per-location override.
30+
31+
<Tabs> <TabItem label="Dashboard">
32+
33+
1. In [Zero Trust](https://dash.cloudflare.com/one), go to **Traffic Policies** > **Traffic Settings**.
34+
2. Under **Proxy and inspection**, find the **Configure time-to-live for DNS resolution** section.
35+
3. Enter a value in seconds (between 60 and 36,000).
36+
4. Select **Save**.
37+
38+
</TabItem> <TabItem label="API">
39+
40+
```sh
41+
curl --request PUT \
42+
https://api.cloudflare.com/client/v4/accounts/{account_id}/gateway/configuration \
43+
--header "Authorization: Bearer {api_token}" \
44+
--header "Content-Type: application/json" \
45+
--data '{
46+
"settings": {
47+
"max_ttl_secs": 3600
48+
}
49+
}'
50+
```
51+
52+
To remove the account-level cap (allow upstream TTLs to pass through), omit the `max_ttl_secs` field or set it to `null`.
53+
54+
</TabItem> </Tabs>
55+
56+
## Configure a per-location maximum TTL
57+
58+
Each [DNS location](/cloudflare-one/networks/resolvers-proxies/) can override the account-level setting. The per-location setting supports three modes:
59+
60+
| Mode | Behavior |
61+
| --- | --- |
62+
| **Respect account-level setting** (`inherit`) | Uses whatever value is configured at the account level. This is the default for new locations. |
63+
| **Do not set max value** (`disabled`) | Disables the maximum TTL cap for this location, even if one is configured at the account level. Upstream TTL values pass through unchanged. |
64+
| **Custom** (`override`) | Sets a location-specific maximum TTL that overrides the account-level value. Requires a `ttl_secs` value between 60 and 36,000. |
65+
66+
<Tabs> <TabItem label="Dashboard">
67+
68+
1. In [Zero Trust](https://dash.cloudflare.com/one), go to **Networks** > **Resolvers & Proxies** > **DNS locations**.
69+
2. Select a location, or create a new one.
70+
3. In the **DNS Endpoints** tab, find the **Configure time-to-live for this location** section.
71+
4. Choose one of:
72+
- **Respect account-level setting** - inherits the account-level TTL cap.
73+
- **Do not set max value** - disables the TTL cap for this location.
74+
- **Custom** - enter a TTL value in seconds.
75+
5. Select **Save**.
76+
77+
</TabItem> <TabItem label="API">
78+
79+
```sh
80+
# Inherit account-level setting (default)
81+
curl --request PUT \
82+
https://api.cloudflare.com/client/v4/accounts/{account_id}/gateway/locations/{location_id} \
83+
--header "Authorization: Bearer {api_token}" \
84+
--header "Content-Type: application/json" \
85+
--data '{
86+
"max_ttl": {
87+
"mode": "inherit"
88+
}
89+
}'
90+
```
91+
92+
```sh
93+
# Disable max TTL for this location
94+
curl --request PUT \
95+
https://api.cloudflare.com/client/v4/accounts/{account_id}/gateway/locations/{location_id} \
96+
--header "Authorization: Bearer {api_token}" \
97+
--header "Content-Type: application/json" \
98+
--data '{
99+
"max_ttl": {
100+
"mode": "disabled"
101+
}
102+
}'
103+
```
104+
105+
```sh
106+
# Override with a custom value
107+
curl --request PUT \
108+
https://api.cloudflare.com/client/v4/accounts/{account_id}/gateway/locations/{location_id} \
109+
--header "Authorization: Bearer {api_token}" \
110+
--header "Content-Type: application/json" \
111+
--data '{
112+
"max_ttl": {
113+
"mode": "override",
114+
"ttl_secs": 3600
115+
}
116+
}'
117+
```
118+
119+
</TabItem> </Tabs>
120+
121+
## DNS log fields
122+
123+
When a maximum TTL is active, two additional fields appear in Gateway DNS logs:
124+
125+
| Field | Description |
126+
| --- | --- |
127+
| `upstream_record_ttls` | The original TTL values from the upstream DNS response, before any cap was applied. |
128+
| `applied_max_ttl` | The maximum TTL value that Gateway applied to the response. If no cap was applied, this field is absent. |
129+
130+
These fields are visible in the DNS logs column picker under the **DNS Response Details** group in the dashboard, and in Logpush datasets.

0 commit comments

Comments
 (0)