[DNS] Document shadowed records and shadow metadata by matildeopbravo · Pull Request #31731 · cloudflare/cloudflare-docs

matildeopbravo · 2026-06-26T17:48:30Z

Summary

Adds a new DNS reference page documenting shadowed records and the shadow metadata API behavior.

The page explains what shadowed records are, covers glue and dead glue records, and documents the shadow metadata fields (shadowed_by, is_glue, dead_glue, shadowed_records_count) along with how to request them.

Documentation checklist

Is there a changelog entry (guidelines)? If you don't add one for something awesome and new (however small) — how will our customers find out? Changelogs are automatically posted to RSS feeds, the Discord, and X.
The change adheres to the documentation style guide.
If a larger change - such as adding a new page- an issue has been opened in relation to any incorrect or out of date information that this PR fixes.

github-actions · 2026-06-26T17:49:15Z

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
`/src/content/docs/dns/`	`@RebeccaTamachiro`, `@hannes-cf`, `@cloudflare/product-owners`, `@esomoza-cf`, `@fattouche`, `@xofyarg`, `@dklbreitling`, `@chreo`, `@svenr-cf`, `@kerolasa`, `@matildeopbravo`, `@vavrusa`, `@mworsley-cloudflare`, `@sebastiaanyn`, `@vendemiat`, `@Woutifier`

ask-bonk

Verdict: 5 style issues need fixing before merge. No build breakers.

Issues:

HIGH (line 28): ns1.externalprovider.com is not a reserved example domain and could resolve to a live origin. Replace with ns1.example.org.
MEDIUM (line 4): description exceeds the 160-character limit. Shorten to stay within the style guide range.
MEDIUM (line 9): H1 heading in body content duplicates the frontmatter title. Remove it to match other pages in this directory.
LOW (line 20): Directional language (below) and See should be Refer to.
LOW (lines 171, 180): Placeholders <ns-record-id> should be <NS_RECORD_ID> (uppercase, underscores) per non-API placeholder conventions.

Note: Consider adding products:\n - dns to frontmatter for consistency with sibling reference pages. The changelog checkbox is unchecked — if include_shadow_metadata is new API behavior, add a changelog entry.

ask-bonk · 2026-06-26T17:55:13Z

+---
+title: Shadowed records
+pcx_content_type: concept
+description: Shadowed records are DNS records that exist in your zone but are never served because a subdomain delegation takes precedence. Learn how Cloudflare detects and annotates them.


Shorten to meet the 160-character limit:

Suggested change

description: Shadowed records are DNS records that exist in your zone but are never served because a subdomain delegation takes precedence. Learn how Cloudflare detects and annotates them.

description: DNS records that exist in your zone but are never served because a subdomain delegation takes precedence. Learn how Cloudflare detects and annotates them.

ask-bonk · 2026-06-26T17:55:13Z

+  order: 5
+---
+
+# Shadowed records


Remove this H1 heading. The title frontmatter already renders as the page H1. Sibling reference pages in this directory do not include an H1 in body content.

ask-bonk · 2026-06-26T17:55:13Z

+Shadowed records are invisible to DNS resolvers. Consider this example:
+
+```txt
+sub.example.com    NS    ns1.externalprovider.com.


Use a reserved example domain to avoid resolving to a live origin:

Suggested change

sub.example.com NS ns1.externalprovider.com.

sub.example.com NS ns1.example.org.

ask-bonk · 2026-06-26T17:55:13Z

+This metadata is exposed in two places: as fields on API responses (covering whether a record is shadowed, whether it serves a special role as glue, and how many records a delegation hides) and as warnings in the Cloudflare dashboard on record creation and in the DNS record list.
+
+:::note
+Shadow metadata is computed on demand at read time and is never stored. It is not returned unless you explicitly request it. See [Request shadow metadata](#request-shadow-metadata) below.


Avoid directional language. Use Refer to instead of See:

Suggested change

Shadow metadata is computed on demand at read time and is never stored. It is not returned unless you explicitly request it. See [Request shadow metadata](#request-shadow-metadata) below.

Shadow metadata is computed on demand at read time and is never stored. It is not returned unless you explicitly request it. Refer to [Request shadow metadata](#request-shadow-metadata).

ask-bonk · 2026-06-26T17:55:13Z

+    "name": "ns1.sub.example.com",
+    "content": "192.0.2.1",
+    "meta": {
+      "shadowed_by": ["<ns-record-id>"],


Use uppercase placeholder format consistent with style guide conventions:

Suggested change

"shadowed_by": ["<ns-record-id>"],

"shadowed_by": ["<NS_RECORD_ID>"],

ask-bonk · 2026-06-26T17:55:41Z

I have completed the review of PR #31731. Here's a summary of what I did:

Labels applied: product:dns, documentation, content:new, triage

Review summary: I posted a review comment with 5 inline suggestions/comments. The PR introduces a well-structured DNS reference page for shadowed records and shadow metadata. The main issues I flagged are:

HIGH (line 28): ns1.externalprovider.com is not a reserved example domain and could resolve to a live origin.
MEDIUM (line 4): The description field exceeds the 160-character style guide limit.
MEDIUM (line 9): There is an H1 heading in the body content, which duplicates the frontmatter title and doesn't match other pages in the directory.
LOW (line 20): Directional language (below) and See should be Refer to.
LOW (lines 171, 180): Placeholders <ns-record-id> should use uppercase/underscore format (<NS_RECORD_ID>).

I also noted that the author should consider adding products: - dns for consistency, and check whether a changelog entry is needed for the new include_shadow_metadata API behavior documentation.

github run

…ords.mdx Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com>

Shorten description under the 160-char limit, add products frontmatter, remove the duplicate H1, use a reserved example domain, fix the remaining placeholder, and replace directional link text.

github-actions · 2026-06-26T18:40:54Z

Preview URL: https://bfc023b6.preview.developers.cloudflare.com
Preview Branch URL: https://matilde-shadowed-records-clarify.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/dns/manage-dns-records/reference/shadowed-records/	https://matilde-shadowed-records-clarify.preview.developers.cloudflare.com/dns/manage-dns-records/reference/shadowed-records/

github-actions Bot added product:dns Issues or PRs related to DNS size/m labels Jun 26, 2026

github-actions Bot assigned chreo, dklbreitling, esomoza-cf, hannes-cf, kerolasa, svenr-cf, vendemiat, Woutifier and xofyarg Jun 26, 2026

[DNS] Document shadowed records and shadow metadata

ca9e9b5

matildeopbravo force-pushed the matilde/shadowed-records-clarify branch from 4975690 to ca9e9b5 Compare June 26, 2026 17:51

ask-bonk Bot added documentation Documentation edits content:new Request for new/missing content triage Waiting for a docs team review. labels Jun 26, 2026

ask-bonk Bot reviewed Jun 26, 2026

View reviewed changes

matildeopbravo and others added 2 commits June 26, 2026 18:57

Update src/content/docs/dns/manage-dns-records/reference/shadowed-rec…

2a732d9

…ords.mdx Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com>

[DNS] Apply review fixes to shadowed records page

bfc023b

Shorten description under the 160-char limit, add products frontmatter, remove the duplicate H1, use a reserved example domain, fix the remaining placeholder, and replace directional link text.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[DNS] Document shadowed records and shadow metadata#31731

[DNS] Document shadowed records and shadow metadata#31731
matildeopbravo wants to merge 3 commits into
productionfrom
matilde/shadowed-records-clarify

matildeopbravo commented Jun 26, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 26, 2026

Uh oh!

ask-bonk Bot left a comment

Uh oh!

ask-bonk Bot Jun 26, 2026

Uh oh!

ask-bonk Bot Jun 26, 2026

Uh oh!

ask-bonk Bot Jun 26, 2026

Uh oh!

ask-bonk Bot Jun 26, 2026

Uh oh!

ask-bonk Bot Jun 26, 2026

Uh oh!

Uh oh!

ask-bonk Bot commented Jun 26, 2026

Uh oh!

github-actions Bot commented Jun 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

11 participants

	description: Shadowed records are DNS records that exist in your zone but are never served because a subdomain delegation takes precedence. Learn how Cloudflare detects and annotates them.
	description: DNS records that exist in your zone but are never served because a subdomain delegation takes precedence. Learn how Cloudflare detects and annotates them.

	sub.example.com NS ns1.externalprovider.com.
	sub.example.com NS ns1.example.org.

	Shadow metadata is computed on demand at read time and is never stored. It is not returned unless you explicitly request it. See [Request shadow metadata](#request-shadow-metadata) below.
	Shadow metadata is computed on demand at read time and is never stored. It is not returned unless you explicitly request it. Refer to [Request shadow metadata](#request-shadow-metadata).

	"shadowed_by": ["<ns-record-id>"],
	"shadowed_by": ["<NS_RECORD_ID>"],

Uh oh!

Conversation

matildeopbravo commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Documentation checklist

Uh oh!

github-actions Bot commented Jun 26, 2026

Uh oh!

ask-bonk Bot left a comment

Choose a reason for hiding this comment

Uh oh!

ask-bonk Bot Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

ask-bonk Bot Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

ask-bonk Bot Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

ask-bonk Bot Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

ask-bonk Bot Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ask-bonk Bot commented Jun 26, 2026

Uh oh!

github-actions Bot commented Jun 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

11 participants

matildeopbravo commented Jun 26, 2026 •

edited

Loading