docs: prefer Route 53 alias records, keep CNAME as fallback#4879
Merged
Conversation
Bring the catalog DNS guidance in line with the Connect Server docs: recommend Route 53 alias records for customers whose hosted zone is in Route 53 (free queries, zone-apex support), and present CNAMEs as the fallback for non-Route-53 DNS. Renames the "CNAMEs" section to "DNS records" but preserves the existing #cnames anchor for backward compatibility with cross-doc links. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #4879 +/- ##
=======================================
Coverage 46.51% 46.51%
=======================================
Files 832 832
Lines 34116 34116
Branches 5828 5828
=======================================
Hits 15868 15868
Misses 16243 16243
Partials 2005 2005
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
The Troubleshooting "Unable to log in" links pointed to technical-reference.md#cnames, an anchor that does not exist in that file. The CNAME content lives in Catalog/Installation.md. - SSO link: drop the dead #cnames fragment (technical-reference.md covers SSO at the file level). - DNS link: retarget to Catalog/Installation.md#dns-records. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Point the "SSO connector misconfigured" link at the "Single sign-on (SSO)" heading in technical-reference.md instead of the file root. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates Quilt Catalog installation documentation to recommend Route 53 alias records (with CNAME as a fallback for non–Route 53 DNS) and fixes pre-existing broken troubleshooting links related to SSO and DNS guidance.
Changes:
- Update Catalog installation DNS guidance: rename “CNAMEs” section to “DNS records”, recommend Route 53 alias records, and keep CNAME instructions as fallback (while preserving the legacy
#cnamesanchor). - Broaden the installation prerequisite to include Route 53 alias records or CNAMEs.
- Fix broken links in Troubleshooting to point to the correct SSO anchor and the updated DNS section.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/Catalog/Installation.md | Reworks DNS setup section to prefer Route 53 alias records, retains CNAME fallback, updates prerequisite wording, and updates internal link target. |
| docs/Troubleshooting.md | Fixes broken links for SSO reference and DNS-related guidance, updates wording from “CNAMEs” to “hostnames”. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Drop stray "Key" column text and fix <RegistryHostName> -> <RegistryHost> to match the actual CFN output names. - Replace overly broad "no per-query DNS charges" claim with the accurate AWS wording (free for alias queries to AWS resources like ALBs). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
kevinemoore
approved these changes
May 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Aligns the catalog installation DNS guidance with the Quilt Connect Server docs and the new CFN-output policy in deployment#2408: CFN output descriptions stay generic about record type; the docs are explicit.
Customer-driven: DNS record-type guidance
Prompted by a customer (Walter Gillett) noticing that we tell people to create CNAMEs while the Connect docs (correctly) recommend Route 53 alias records. Aliases are strictly better when the hosted zone is in Route 53 (no per-query charges, zone-apex support); CNAME is the right answer when DNS is hosted elsewhere.
LoadBalancerCanonicalHostedZoneIDas the alias hosted zone), present CNAME as the fallback for non-Route-53 DNS.<a id="cnames"></a>anchor preserved so existing cross-doc links to#cnamesstill resolve.[CNAMEs](#cnames)link to[DNS records](#dns-records).Opportunistic: pre-existing broken links
Noticed while auditing the DNS guidance — these were already broken on
master, unrelated to the policy change but cheap to fix here.technical-reference.md#cnames(no such anchor); retargeted totechnical-reference.md#single-sign-on-sso.Catalog/Installation.md#dns-records.Test plan
#cnamesdeep links still scroll to the section🤖 Generated with Claude Code