refactor: reorganize install documentation structure#719
Closed
youyongsong wants to merge 1 commit into
Closed
Conversation
Contributor
WalkthroughRestructures the ACP Core installation docs: adds planning, validation, and next-steps pages; reorganizes overview, installing, and download content; updates index/metadata and llms routing; and standardizes product naming in node preprocessing. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 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. Review rate limit: 0/1 reviews remaining, refill in 60 minutes.Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/en/install/validation.mdx`:
- Around line 24-25: Update the heading text to match the kubectl command:
replace "Check if there are any failed Charts" with wording that references the
actual resource being queried (e.g., "Check if there are any failed AppReleases"
or "Check for failed apprelease resources") so the label aligns with the command
`kubectl get apprelease --all-namespaces`.
🪄 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: 5c637a32-d7f7-49f4-ad34-259a2ec810dc
📒 Files selected for processing (9)
docs/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/validation.mdxllms.txt
💤 Files with no reviewable changes (1)
- docs/en/install/index.mdx
Deploying alauda-container-platform with
|
| Latest commit: |
9cd4096
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://62956fd9.alauda-container-platform.pages.dev |
| Branch Preview URL: | https://refactor-install-section.alauda-container-platform.pages.dev |
- 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>
youyongsong
force-pushed
the
refactor-install-section
branch
from
1f3416f to
9cd4096
Compare
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@llms.txt`:
- Around line 313-323: The install index (llms.txt) is missing the prepare
landing page referenced by overview.mdx; add an entry for
docs/en/install/prepare/index.mdx into the "install" list alongside the existing
prepare subpages so the new install flow (overview.mdx → ./prepare/index.mdx) is
discoverable end-to-end. Ensure the new line follows the same format as other
entries and appears before the prepare/* subpage lines so readers see the
landing page first.
🪄 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: 3567c29f-b810-4def-a510-19e33a8fded2
📒 Files selected for processing (10)
docs/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.mdxllms.txt
💤 Files with no reviewable changes (1)
- docs/en/install/index.mdx
✅ Files skipped from review due to trivial changes (6)
- docs/en/install/global_dr.mdx
- docs/en/install/prepare/node_preprocessing.mdx
- docs/en/install/next_steps.mdx
- docs/en/install/validation.mdx
- docs/en/install/prepare/download.mdx
- docs/en/install/planning.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/en/install/installing.mdx
Comment on lines
313
to
+323
| ## install | ||
|
|
||
| - [docs/en/install/global_dr.mdx](docs/en/install/global_dr.mdx): Global cluster disaster recovery guide for ACP using primary and standby global clusters with real-time etcd synchronization. It covers supported failure scenarios, excluded namespaces and data limitations, DNS and VIP planning, primary and standby installation requirements, encryption key copying, etcd Synchronizer plugin configuration, sync verification, failover steps, service restarts, package upload considerations, and routine consistency checks. | ||
| - [docs/en/install/installing.mdx](docs/en/install/installing.mdx): Step-by-step guide for installing the ACP `global` cluster from the Core Package. It covers extracting the installer, starting `setup.sh` with optional IPv6 mode, configuring installation parameters in the web UI, verifying app releases and Pods with `kubectl`, installing the Product Docs plugin, detailed parameter guidance for Kubernetes version, endpoints, certificates, image registry, networking, nodes, and cleanup of the installer container. | ||
| - [docs/en/install/overview.mdx](docs/en/install/overview.mdx): Overview of ACP Core installation, defining installation as deployment of the `global` cluster before creating or importing workload clusters and installing extensions. It explains preparation, execution, and verification stages, and introduces the Alauda Customer Portal as the official source for downloads, documentation, support, marketplace packages, and license management. | ||
| - [docs/en/install/installing.mdx](docs/en/install/installing.mdx): Installing guide for ACP Core and the ACP `global` cluster from the Core Package. It covers extracting the installer, starting `setup.sh` with optional IPv6 mode, configuring installation parameters in the web UI, linking to ACP Core validation, detailed parameter guidance for Kubernetes version, endpoints, certificates, image registry, networking, nodes, and cleanup of the installer container. | ||
| - [docs/en/install/next_steps.mdx](docs/en/install/next_steps.mdx): Next steps after ACP Core validation. It directs users to Product Docs plugin installation, Global Cluster Disaster Recovery, workload cluster onboarding, Extensions, identity and access setup, storage, networking, registry access, backup, upgrade, and observability documentation, and includes the Product Docs plugin installation steps. | ||
| - [docs/en/install/overview.mdx](docs/en/install/overview.mdx): Overview of ACP Core installation, defining installation as deployment of the `global` cluster and separating ACP Core from workload clusters, imported clusters, Extensions Packages, Operators, and Cluster Plugins. It provides the install route map across planning, preparation, download, installation, validation, and post-install tasks. | ||
| - [docs/en/install/planning.mdx](docs/en/install/planning.mdx): Planning guide for ACP Core installation. It compares Multi-Cluster, Single Cluster, and Single Node deployment architectures; lists install-time decisions such as package architecture, IP family, endpoints, load balancing, certificates, image repository, nodes, and Global DR; and links to read-before-install source pages. | ||
| - [docs/en/install/prepare/download.mdx](docs/en/install/prepare/download.mdx): Preparation guide for downloading the ACP Core Package from the Alauda Customer Portal. It explains architecture choices for x86, ARM, and hybrid packages, the requirement to install Core before extension packages in ACP v4.1 and later, and the process for migrating a single-architecture installation to hybrid by syncing images and removing the `cpaas.io/node-arch-constraint` label if present. | ||
| - [docs/en/install/prepare/node_preprocessing.mdx](docs/en/install/prepare/node_preprocessing.mdx): Node preprocessing checklist for ACP global cluster installation. It lists supported OS and kernel versions, CPU architecture notes, the `init.sh` quick configuration script, required checks for grub parameters, kernel modules, SELinux, swap, SSH, DNS, routes, ports, packages, temporary mounts, conflicting container or Kubernetes software, filesystem cleanup, cross-node connectivity, unique hostnames, and clock synchronization. | ||
| - [docs/en/install/prepare/prerequisites.mdx](docs/en/install/prepare/prerequisites.mdx): Prerequisites and resource planning guide for installing an ACP global cluster. It covers deployment architectures for multi-cluster, single-cluster, and single-node setups, minimum CPU and memory guidance including ARM sizing notes, required VIPs, external IPs, domain names, certificates, bandwidth, latency, network segments, and load balancer forwarding rules for ports such as 443, 6443, 11443, and optionally 2379. | ||
| - [docs/en/install/validation.mdx](docs/en/install/validation.mdx): ACP Core installation validation guide. It covers Web UI access validation, `kubectl` checks for failed app releases, Pod health checks, expected successful states, and the next step after validation. |
Contributor
There was a problem hiding this comment.
Add the prepare landing page to the install index.
docs/en/install/overview.mdx now routes step 2 through ./prepare/index.mdx, but llms.txt only lists the prep subpages. Adding the landing page keeps the new install flow discoverable end-to-end.
Suggested addition
## install
- [docs/en/install/global_dr.mdx](docs/en/install/global_dr.mdx): Global cluster disaster recovery guide for ACP using primary and standby global clusters with real-time etcd synchronization.
+- [docs/en/install/prepare/index.mdx](docs/en/install/prepare/index.mdx): Install preparation landing page covering prerequisites, node preprocessing, and download guidance.
- [docs/en/install/installing.mdx](docs/en/install/installing.mdx): Installing guide for ACP Core and the ACP `global` cluster from the Core Package.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@llms.txt` around lines 313 - 323, The install index (llms.txt) is missing the
prepare landing page referenced by overview.mdx; add an entry for
docs/en/install/prepare/index.mdx into the "install" list alongside the existing
prepare subpages so the new install flow (overview.mdx → ./prepare/index.mdx) is
discoverable end-to-end. Ensure the new line follows the same format as other
entries and appears before the prepare/* subpage lines so readers see the
landing page first.
chinameok
reviewed
Apr 30, 2026
| | Priority | Task | When to use | Continue with | | ||
| | --- | --- | --- | --- | | ||
| | Recommended immediately | Install the Product Docs plugin. | Install this plugin so in-console help links can open product documentation. | [Install Product Docs Plugin](#install_product_docs_plugin) | | ||
| | Conditional | Configure Global Cluster Disaster Recovery. | Use this path when your environment requires primary and standby `global` clusters. | [Global Cluster Disaster Recovery](./global_dr.mdx) | |
Contributor
There was a problem hiding this comment.
Global Cluster Disaster Recovery should not be presented as a normal post-install next step. DR planning affects pre-install decisions such as domain names, VIPs, certificates, LoadBalancer rules, image registry choices, package architecture, and Primary/Standby installation parameter consistency. This PR already states in planning.mdx that users should read the DR guide before installing Core, so listing “Configure Global Cluster Disaster Recovery” here after Core validation can mislead users into planning DR too late. Please remove this row from Next Steps, or reword it to cover only post-install DR verification/drill actions for environments where DR was already planned before installation.
Collaborator
Author
|
Closing this PR because it is superseded by the combined install + overview refactor branch: refactor-install-overview-sections. A new PR will be opened from that branch. |
Collaborator
Author
|
Replacement PR: #764 |
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
2 participants
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 by CodeRabbit