NO-JIRA: docs(azure): add self-managed Azure setup without external DNS #7191
Conversation
openshift-ci
bot
added
the
do-not-merge/work-in-progress
|
Skipping CI for Draft Pull Request. |
WalkthroughDocumentation restructuring of three Azure how-to guides to present DNS configuration options as branching paths. Changes introduce "With External DNS" and "Without External DNS" scenarios across cluster creation, management setup, and the index page, replacing single-path instructions with dual-path approaches and comparison tables. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
openshift-ci
bot
added
area/cli
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: bryan-cox The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
openshift-ci
bot
added
area/hypershift-operator
bryan-cox
force-pushed
the
docs-self-managed-azure-without-external-dns
branch
2 times, most recently
from
501d7b4 to
0d747ce
Compare
Update existing self-managed Azure documentation to include both "with External DNS" and "without External DNS" approaches in the same guides, eliminating duplication. Changes: - Updated setup-management-cluster.md to show both operator installation methods - Updated create-self-managed-azure-cluster.md to show cluster creation with/without --external-dns-domain - Updated self-managed-azure-index.md to explain DNS options without duplication - Removed duplicate standalone files for "without External DNS" The consolidated approach makes it clearer that both DNS options are supported and reduces documentation maintenance burden. Signed-off-by: Bryan Cox <[email protected]> Commit-Message-Assisted-by: Claude (via Claude Code)
bryan-cox
force-pushed
the
docs-self-managed-azure-without-external-dns
branch
from
0d747ce to
2905931
Compare
bryan-cox
changed the title
openshift-ci-robot
added
the
jira/valid-reference
|
@bryan-cox: This pull request explicitly references no jira issue. In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository. |
|
/auto-cc |
openshift-ci
bot
removed
the
do-not-merge/work-in-progress
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/content/how-to/azure/create-self-managed-azure-cluster.md (1)
21-24: Prerequisite clarity: differentiate optional configuration from optional component.Line 24 states "Optional: External DNS configured" which conflates optional component availability with optional setup. Consider rephrasing to: "Optional: External DNS can be configured for automatic DNS management" or similar to clarify that External DNS itself is the optional choice, not just its configuration state.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to Reviews -> Disable Knowledge Base setting
📒 Files selected for processing (3)
docs/content/how-to/azure/create-self-managed-azure-cluster.md(2 hunks)docs/content/how-to/azure/self-managed-azure-index.md(6 hunks)docs/content/how-to/azure/setup-management-cluster.md(3 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**
⚙️ CodeRabbit configuration file
-Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity.
Files:
docs/content/how-to/azure/create-self-managed-azure-cluster.mddocs/content/how-to/azure/self-managed-azure-index.mddocs/content/how-to/azure/setup-management-cluster.md
🪛 LanguageTool
docs/content/how-to/azure/setup-management-cluster.md
[style] ~196-~196: Using many exclamation marks might seem excessive (in this case: 21 exclamation marks for a text that’s 2658 characters long)
Context: ...T} \ --limit-crd-install Azure ``` !!! tip "Custom HyperShift Image" Add ...
(EN_EXCESSIVE_EXCLAMATION)
🪛 markdownlint-cli2 (0.18.1)
docs/content/how-to/azure/self-managed-azure-index.md
106-106: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
130-130: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
131-131: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
docs/content/how-to/azure/setup-management-cluster.md
219-219: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
237-237: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
🔇 Additional comments (6)
docs/content/how-to/azure/create-self-managed-azure-cluster.md (1)
119-202: Excellent dual-path structure with clear branching for DNS choices.The tabbed "With External DNS" and "Without External DNS" sections cleanly present the two approaches with properly differentiated commands and DNS behavior explanations. The distinction is immediately apparent (presence/absence of
--external-dns-domainflag), and post-creation DNS results are explained concisely for each path. Users can easily follow the section matching their setup.docs/content/how-to/azure/self-managed-azure-index.md (2)
28-45: DNS Management Options section effectively frames dual approaches for users.The comparison table (lines 32–38) clearly contrasts With/Without External DNS across use case, DNS naming, complexity, and management. The tip (lines 39–44) provides concrete guidance on section selection. This context upfront helps users choose their path before diving into setup details.
70-96: Phase descriptions consistently reference both DNS approaches.The updates to Phase 2 (line 70: "optional External DNS configuration") and Phase 3 (line 96: "Includes both DNS approaches") align well with the dual-path architecture. Users understand from the index that both options are documented in the linked guides.
docs/content/how-to/azure/setup-management-cluster.md (3)
9-27: DNS Management Options section with conditional guidance sets clear expectations.The tip (lines 13–27) explicitly maps each DNS approach to corresponding setup steps, helping users select and follow the correct path. "External DNS Only" warnings in subsequent sections (lines 38–40, 94–96) with skip-to links prevent users from getting stuck in irrelevant sections.
147-209: Dual operator installation paths clearly differentiate flags and validation.The "With External DNS" (lines 151–181) and "Without External DNS" (lines 182–208) subsections make the configuration differences explicit:
- External DNS path includes
--external-dns-provider=azure,--external-dns-credentials, and--external-dns-domain-filterflags- Non-External-DNS path omits these, resulting in simplified setup
Verification steps (lines 214–235) use tabs to show expected output differences, aligning with actual deployment behavior. This clarity reduces configuration errors.
36-145: External DNS sections are logically organized with clear prerequisites and warnings.Placing DNS Zone Configuration before the service principal setup, and marking both "(External DNS Only)" with warnings, guides users to skip them if not using External DNS. The warnings link to the non-External-DNS operator installation path, preventing navigation confusion.
|
/lgtm |
|
/verified by @bryan-cox |
openshift-ci-robot
added
the
verified
|
@bryan-cox: This PR has been marked as verified by In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository. |
|
@bryan-cox: all tests passed! Full PR test history. Your PR dashboard. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here. |
3 participants
Description
This PR updates the existing self-managed Azure HyperShift documentation to include both "with External DNS" and "without External DNS" approaches in the same guides, eliminating duplication.
What Changed
Instead of creating separate documentation files, the existing guides now include sections for both DNS approaches:
Updated Files
setup-management-cluster.mdcreate-self-managed-azure-cluster.mdself-managed-azure-index.mdmkdocs.ymlKey Benefits
How DNS Options Work
With External DNS
--external-dns-provider=azure,--external-dns-credentials,--external-dns-domain-filter--external-dns-domainapi-cluster.example.comWithout External DNS
--external-dns-domainfrom cluster creationabc123.eastus.cloudapp.azure.comThe difference is literally just a few command-line flags - no need for entirely separate guides.
Testing
Related Issues
Addresses the need for simpler self-managed Azure setup documentation without requiring External DNS configuration, while avoiding documentation duplication.