refactor: reorganize install and overview documentation#764
refactor: reorganize install and overview documentation#764youyongsong wants to merge 6 commits into
Conversation
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
WalkthroughThis PR restructures ACP docs into modular overview, cluster-management models, a guided install workflow (planning, validation, next steps), availability/recovery, and explicit version/onboarding boundaries for ACP 4.3. ChangesDocumentation Framework Restructuring
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/en/install/validation.mdx`:
- Around line 23-28: The current kubectl+awk validation misses pods that are
"Running" but have zero or incomplete READY containers; update the awk logic in
the kubectl get pod --all-namespaces pipeline to also inspect the READY column
($3) and flag pods where the ready count is zero or not equal to the desired
count (e.g., "0/1" or "1/2") in addition to the existing
non-Running/non-Completed check; locate the pipeline using the command string
"kubectl get pod --all-namespaces | awk ..." and change the filter to combine
the status check ($4) OR a readiness check on $3 so Running pods with incomplete
readiness are reported.
In `@docs/en/overview/glossary.mdx`:
- Line 30: The glossary entry currently links to a non-existent namespace index
("../developer/building_application/namespace/index.mdx"); update that link to
point to a real namespace doc (e.g.,
"../developer/building_application/namespace/manage_namespace.mdx" or
"create_namespace.mdx") so the Namespace Management anchor resolves; locate the
line containing the Term "productShort" and the link string
"../developer/building_application/namespace/index.mdx" and replace the target
with the chosen existing namespace page.
In `@docs/en/overview/kubernetes-support-matrix.mdx`:
- Line 82: The link reference "../upgrade/index.mdx" in the sentence "For
upgrade procedures, see [Upgrade](../upgrade/index.mdx)." points to a
non-existent page; update the Markdown link target to the correct upgrade page
by replacing "../upgrade/index.mdx" with "../upgrade/overview.mdx" so the
[Upgrade] link resolves to the existing overview document.
In `@docs/en/overview/release_notes.mdx`:
- Line 40: The link in release_notes.mdx currently points to
../upgrade/index.mdx which is incorrect; update the Markdown link target in
docs/en/overview/release_notes.mdx by replacing ../upgrade/index.mdx with the
actual page path ../upgrade/overview.mdx so the "Upgrade" link resolves to the
correct guide.
In `@llms.txt`:
- Line 317: Update the llms.txt index entry for next_steps.mdx to remove the
outdated "Global Cluster Disaster Recovery" mention and any reference to Global
DR; specifically edit the line that begins with "-
[docs/en/install/next_steps.mdx](docs/en/install/next_steps.mdx): Next steps
after ACP Core validation..." so the list of post-install topics reflects the PR
intent (Product Docs plugin installation, workload cluster onboarding,
Extensions, identity and access setup, storage, networking, registry access,
backup, upgrade, and observability) and ensure the phrase "Global Cluster
Disaster Recovery" is deleted or replaced to prevent LLM navigation to the
removed flow.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 66e63cd6-c2cf-47ce-b1e9-0610522e9b7a
📒 Files selected for processing (22)
docs/en/configure/clusters/overview.mdxdocs/en/install/global_dr.mdxdocs/en/install/index.mdxdocs/en/install/installing.mdxdocs/en/install/next_steps.mdxdocs/en/install/overview.mdxdocs/en/install/planning.mdxdocs/en/install/prepare/download.mdxdocs/en/install/prepare/node_preprocessing.mdxdocs/en/install/validation.mdxdocs/en/overview/architecture.mdxdocs/en/overview/availability-and-recovery.mdxdocs/en/overview/cluster-management-models.mdxdocs/en/overview/core-and-extensions.mdxdocs/en/overview/glossary.mdxdocs/en/overview/introduction.mdxdocs/en/overview/kubernetes-support-matrix.mdxdocs/en/overview/learn-more.mdxdocs/en/overview/platform-model.mdxdocs/en/overview/release_notes.mdxdocs/en/overview/version-and-lifecycle.mdxllms.txt
💤 Files with no reviewable changes (1)
- docs/en/install/index.mdx
Deploying alauda-container-platform with
|
| Latest commit: |
4883fe5
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://5bf3537f.alauda-container-platform.pages.dev |
| Branch Preview URL: | https://refactor-install-overview-se.alauda-container-platform.pages.dev |
Terminology cross-check against
|
| Deprecated non-term | Occurrences |
|---|---|
Master Node / master node |
0 |
Slave Node |
0 |
Application Worker Node |
0 |
Ingress Node / Egress Node |
0 |
Imported Cluster (as a type) |
0 |
ACP-Provisioned Cluster |
0 |
Bastion Node / Provisioner Node |
0 |
HostedCluster / HyperShift |
0 |
Managed Cluster is used correctly — only as the UI/navigation label, with Third-party cluster as the product-model planning term. This matches spec §4.1 row + the v0.7 round 6 decision exactly.
The conceptual structure of overview/cluster-management-models.mdx (three independent axes — Infrastructure Responsibility, Control-Plane Topology, Kubernetes Ownership) and the boundary statements in overview/availability-and-recovery.mdx (Global DR as global-control-plane DR rather than full-platform DR, with backup composed by data domain) match the spec verbatim. Good work.
Recommendation
- Must address before merge: P1 (12 PPI occurrences). This is a committed cross-doc rename and PR refactor: reorganize install and overview documentation #764 is the right place.
- Strongly suggested in the same PR: P2 (HCP Kamaji mention). One-line change in two files; keeps abstraction level consistent.
Happy to draft the exact diff for either if useful.
JounQin
force-pushed
the
refactor-install-overview-sections
branch
from
8c12cf9 to
384c5d1
Compare
|
/doc-pr-build |
- Add planning.mdx for pre-installation planning guidance - Add validation.mdx for post-installation validation steps - Add next_steps.mdx for post-installation next steps - Update install section weights and navigation - Fix internal links to use relative paths - Update llms.txt to reflect new structure Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Split the overview section into focused reader-path pages for the introduction, platform model, cluster management models, core and extensions, version and lifecycle, availability and recovery, and follow-up reading. Rework the architecture and cluster overview docs to separate infrastructure responsibility, control-plane topology, Kubernetes ownership, third-party onboarding, and availability/recovery boundaries. Update the Kubernetes support matrix and release notes for ACP 4.3 Kubernetes 1.34 support, compatible-version upgrade requirements, the third-party onboarding range, the default Extend validation baseline, CVO upgrades, standalone Cluster Plugin upgrades, immutable infrastructure updates, and the next-generation console preview entry. Refresh the glossary with canonical platform, cluster, Extension, identity, networking, disaster recovery, backup, and upgrade terminology, including related-document links. Regenerate llms.txt summaries so the LLM navigation index reflects the new overview structure and revised cluster overview.
Remove Global Cluster Disaster Recovery from the post-install Next Steps table so the install flow does not imply that DR planning can wait until after Core validation. Reword the overview Learn More entry to frame Global DR as planning and operation work, matching the install planning page and the DR procedure scope.
Address terminology review feedback on PR #764. P1: Rename Platform-Provisioned Infrastructure to Installer-Provisioned Infrastructure (IPI) across overview/cluster-management-models.mdx, overview/glossary.mdx, overview/platform-model.mdx, and configure/clusters/overview.mdx. The scenario matches OpenShift IPI at the customer-facing responsibility boundary (platform provisions machines, immutable node OS, and full Kubernetes lifecycle; customer provides only IaaS credentials), so adopt the OCP-canonical naming per the terminology spec. Add (IPI) and (UPI) on first use per page, and update the "platform-provisioned nodes" adjective in the Immutable OS glossary entry for consistency. P2: Add the Kamaji TenantControlPlane implementation note to the HCP description in overview/glossary.mdx and overview/cluster-management- models.mdx, plus the matching note in overview/platform-model.mdx and configure/clusters/overview.mdx. Mirrors the abstraction level already used for Immutable OS -> MicroOS in the glossary, so readers do not look for HyperShift HostedCluster/NodePool CRDs that ACP does not use. Refresh the matching llms.txt entries so the LLM navigation index stays consistent with the renamed terms and the Kamaji note. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
youyongsong
force-pushed
the
refactor-install-overview-sections
branch
from
384c5d1 to
f8515f9
Compare
|
@chinameok thanks for the cross-check against the terminology spec — both items addressed in P1 — PPI → IPI sweep ✅All 12 noun-phrase occurrences of
While in the area I also updated one adjectival mention — No inbound links to a P2 — HCP Kamaji note ✅Added an
Mirrors the abstraction level you cited for llms.txtRefreshed the matching Rebase note (not part of your review, FYI)Rebased onto current
|
There was a problem hiding this comment.
♻️ Duplicate comments (1)
docs/en/overview/release_notes.mdx (1)
40-40:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winPotential broken link target for Upgrade guide.
Line 40 links to
../upgrade/index.mdx, but this doc set appears to use../upgrade/overview.mdx. Please switch this to the actual page path to avoid dead navigation.Suggested patch
-For operational guidance, see [Upgrade](../upgrade/index.mdx). +For operational guidance, see [Upgrade](../upgrade/overview.mdx).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/en/overview/release_notes.mdx` at line 40, Replace the broken Upgrade link target in release_notes.mdx: change the relative link string '../upgrade/index.mdx' to the actual page path '../upgrade/overview.mdx' so the anchor in the sentence "For operational guidance, see [Upgrade](...)" points to the correct document; update the link text if needed and verify the rendered link resolves to the overview page.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Duplicate comments:
In `@docs/en/overview/release_notes.mdx`:
- Line 40: Replace the broken Upgrade link target in release_notes.mdx: change
the relative link string '../upgrade/index.mdx' to the actual page path
'../upgrade/overview.mdx' so the anchor in the sentence "For operational
guidance, see [Upgrade](...)" points to the correct document; update the link
text if needed and verify the rendered link resolves to the overview page.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 4a3ca4ff-3b23-4b09-a557-59dda53bd4a0
📒 Files selected for processing (22)
docs/en/configure/clusters/overview.mdxdocs/en/install/global_dr.mdxdocs/en/install/index.mdxdocs/en/install/installing.mdxdocs/en/install/next_steps.mdxdocs/en/install/overview.mdxdocs/en/install/planning.mdxdocs/en/install/prepare/download.mdxdocs/en/install/prepare/node_preprocessing.mdxdocs/en/install/validation.mdxdocs/en/overview/architecture.mdxdocs/en/overview/availability-and-recovery.mdxdocs/en/overview/cluster-management-models.mdxdocs/en/overview/core-and-extensions.mdxdocs/en/overview/glossary.mdxdocs/en/overview/introduction.mdxdocs/en/overview/kubernetes-support-matrix.mdxdocs/en/overview/learn-more.mdxdocs/en/overview/platform-model.mdxdocs/en/overview/release_notes.mdxdocs/en/overview/version-and-lifecycle.mdxllms.txt
💤 Files with no reviewable changes (1)
- docs/en/install/index.mdx
✅ Files skipped from review due to trivial changes (9)
- docs/en/install/next_steps.mdx
- docs/en/install/global_dr.mdx
- docs/en/install/prepare/node_preprocessing.mdx
- docs/en/overview/introduction.mdx
- docs/en/install/planning.mdx
- docs/en/overview/learn-more.mdx
- docs/en/install/validation.mdx
- llms.txt
- docs/en/overview/platform-model.mdx
🚧 Files skipped from review as they are similar to previous changes (6)
- docs/en/overview/kubernetes-support-matrix.mdx
- docs/en/overview/core-and-extensions.mdx
- docs/en/install/overview.mdx
- docs/en/install/installing.mdx
- docs/en/overview/glossary.mdx
- docs/en/install/prepare/download.mdx
Address review finding F-2 from the 2026-05-19 cross-skill review of PR #764 against the acp-docs-guide and acp-section-refactor lessons ledger (AGC-007: avoid page self-description in favor of user-facing guidance). The two Immutable Infrastructure routing banners in installing.mdx and global_dr.mdx were originally added upstream by PR #760 and start with "This page documents..." That phrasing reads as page self-description. Rewrite both as "This installation path applies to..." / "This disaster recovery path applies to..." so the banner directs the reader to the right installation path or disaster recovery path instead of describing what the page is. The banners' routing function is unchanged. The Immutable Infrastructure link and the call to action still target the same external site entries. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Post-rebase sweep to carry forward the terminology spec (PPI -> IPI; Kamaji impl note for HCP) into Configure pages and refresh stale llms.txt paths for the new Configure tree. - configure/hosted_control_planes/overview.mdx: replace "Platform-Provisioned Infrastructure" with "Installer-Provisioned Infrastructure (IPI)"; add the "implemented through Kamaji (\`TenantControlPlane\`)" clause on the page's first HCP mention. - configure/storage/cosi/cosi-concepts.mdx and intro.mdx: adopt the cleaner reader-task framing from the original PR #795 wording while keeping the MinIO removal already applied on master. - llms.txt: mechanically rewrite 43 entries to the new Configure paths (clusters/nodes -> nodes, clusters/etcd-encryption -> etcd/encryption, configure/networking -> networking, developer/registry -> configure/registry, configure/notification/cluster_notification -> observability/alerting/notification, etc.) and remove 4 entries for files deleted by either PR. Full llms.txt regeneration for newly added Configure pages remains a follow-up under the llmstxt-generator workflow. References: ACP terminology spec v0.8 sec 3.1 axis 1, sec 4.1, sec 9.2; shared ledger TW-001, TW-011, TW-013 (updated 2026-05-19). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3 participants
Summary
Supersedes #719.
This PR combines the install section refactor and the overview section refactor into one review branch so the documentation flow can be reviewed together.
Install documentation
Overview documentation
Navigation and review notes
Validation
Summary by CodeRabbit