Skip to content

refactor: reorganize install and overview documentation #764

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
youyongsong wants to merge 6 commits into
base: master
Choose a base branch
from
Open

refactor: reorganize install and overview documentation #764

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6629e10
refactor: reorganize install documentation structure
youyongsong Apr 30, 2026
9b3cea8
refactor: expand ACP overview documentation
youyongsong May 9, 2026
463c6b5
docs: address global DR next-step feedback
youyongsong May 9, 2026
3d6c5db
docs: clarify cluster overview model split
youyongsong May 9, 2026
f8515f9
docs(overview): rename PPI to IPI and document HCP Kamaji impl
youyongsong May 19, 2026
4883fe5
docs(install): rewrite path-selection banners as reader-task framing
youyongsong May 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 43 additions & 77 deletions docs/en/configure/clusters/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,111 +5,77 @@ title: Overview

# Clusters Overview

The platform supports multiple Kubernetes cluster management models depending on how the underlying infrastructure is provisioned and how the control plane is deployed.
Start here to choose whether to create a platform-managed cluster, evaluate Hosted Control Plane, or onboard an existing Kubernetes environment. For the platform-level relationship between cluster responsibility, control-plane topology, and onboarding boundaries, see [Cluster Management Models](../../overview/cluster-management-models.mdx).

## Platform-Provisioned Infrastructure
## Choose A Cluster Path

**Description:**
| If you need to | Start with | Key boundary |
| --- | --- | --- |
| Let the platform provision machines and manage Immutable OS for supported providers. | [About Immutable Infrastructure](./immutable-infra.mdx) | Platform-owned lifecycle applies only within the supported provider and workflow scope. |
| Create a cluster on machines that you prepare and maintain. | [Creating an On-Premise Cluster](./on-premises.mdx) | The platform manages Kubernetes after node preparation; node OS lifecycle remains user-owned. |
| Evaluate HCP for a non-production <Term name="productShort" /> 4.3 scenario. | [About Hosted Control Plane](./about-hcp.mdx) | HCP is Technology Preview in <Term name="productShort" /> 4.3 and is not production-supported. |
| Onboard an existing Kubernetes environment. | [Managed Clusters Overview](./managed/overview.mdx) | The external owner, distribution, or provider usually owns Kubernetes, node, and infrastructure lifecycle. |
| Choose between direct platform access and reverse-connect onboarding. | [Import Clusters](./managed/import/overview.mdx) and [Register Cluster](./managed/register.mdx) | Import and register are onboarding methods, not separate day-2 capability models. |

In this model, the platform provisions both the machines and the node operating systems.
All nodes use an **Immutable OS**, which ensures a consistent, declarative, and easily recoverable infrastructure state.
This model provides full automation across the entire cluster lifecycle — from provisioning to scaling and upgrades.
## Platform-Managed Cluster Creation

**Examples of Immutable OS:**
For clusters that <Term name="productShort" /> creates and lifecycle-manages, choose the creation path by infrastructure responsibility.

Common Immutable OS examples include **Fedora CoreOS**, **Flatcar Linux**, and **openSUSE MicroOS**.
Currently, the platform supports **MicroOS** for immutable node management.
| Infrastructure responsibility | Use when | Continue with |
| --- | --- | --- |
| Installer-Provisioned Infrastructure (IPI) | The platform should provision machines and manage node operating systems through Immutable OS for a supported provider integration. | [About Immutable Infrastructure](./immutable-infra.mdx) |
| User-Provisioned Infrastructure (UPI) | You prepare physical or virtual machines, and the platform installs and manages Kubernetes on those nodes. | [Creating an On-Premise Cluster](./on-premises.mdx) |

**Responsibilities:**
## Installer-Provisioned Infrastructure

| Component | Managed by |
| ---------------- | ---------------------------- |
| Machines / Nodes | Platform |
| Node OS | Platform (Immutable OS only) |
| Kubernetes | Platform |
In Installer-Provisioned Infrastructure (IPI), the platform provisions machines and manages node operating systems through Immutable OS. This model is used when the platform owns the supported cluster provisioning, scaling, and upgrade lifecycle for the selected provider integration.

## User-Provisioned Infrastructure
Currently, the platform supports MicroOS for immutable node management. For immutable infrastructure concepts and provider-specific workflows, see [About Immutable Infrastructure](./immutable-infra.mdx).

**Description:**
## User-Provisioned Infrastructure

In this model, the user provides pre-provisioned physical or virtual machines.
The platform installs and manages Kubernetes on these nodes, while node OS management — including provisioning, patching, or replacement — remains under the user's control.
In User-Provisioned Infrastructure, users prepare physical or virtual machines before cluster creation. The platform installs and manages Kubernetes on those nodes, while node operating system management, including provisioning, patching, and replacement, remains under the user's control.

This model is designed for organizations that already have established procedures or automation tools for managing their infrastructure or operating systems.
This model is suitable when organizations already have established infrastructure or operating system management procedures. For the cluster creation workflow, see [Creating an On-Premise Cluster](./on-premises.mdx).

To create and manage User-Provisioned Infrastructure clusters through APIs, see <ExternalSiteLink name="immutable-infra" href="/apis/index.html" children="Immutable Infrastructure API Reference" /> and go to **Provider APIs > User-Provisioned Infrastructure Provider APIs**.

**Responsibilities:**

| Component | Managed by |
| ---------------- | ---------- |
| Machines / Nodes | User |
| Node OS | User |
| Kubernetes | Platform |

## Hosted Control Plane (HCP)

**Description:**

**Hosted Control Plane (HCP)** is a deployment model in which multiple clusters share a single control plane hosted in a dedicated management cluster.
Only the control plane components are shared — the worker nodes are still provisioned following one of the two infrastructure models above (either platform-provisioned or user-provisioned).

**Characteristics:**

* Reduces control plane resource consumption.
* Supports mixed models: worker nodes can be immutable or user-provisioned.
* Ideal for large bare-metal or resource-constrained environments.

## Connected Clusters

The platform also supports connecting and managing existing Kubernetes clusters, whether they are public cloud clusters or CNCF-compliant Kubernetes distributions.
## Hosted Control Plane

### Public Cloud Kubernetes
Hosted Control Plane is a control-plane topology. Each hosted cluster has its own control plane, and multiple hosted control planes run as workloads on a management cluster.

* Connects to managed Kubernetes services such as EKS, AKS, and GKE through cloud-specific providers (e.g., *Alauda Container Platform EKS Provider*).
* Cloud credentials can be securely stored in the platform.
* Enables creation and management of public cloud clusters directly from the platform.
In <Term name="productShort" />, HCP is implemented through Kamaji (`TenantControlPlane`). In <Term name="productShort" /> 4.3, HCP is Technology Preview, is not production-supported, supports disconnected environments, and defaults to IPI only. For evaluation details, see [About Hosted Control Plane](./about-hcp.mdx).

### CNCF-Compliant Kubernetes
## Third-Party Cluster Onboarding

* Connects any existing Kubernetes cluster conforming to CNCF standards.
* Supports unified visibility, policy control, and monitoring across environments.
* [Refer to the Kubernetes Support Matrix](../../overview/kubernetes-support-matrix.mdx).
Third-party clusters are existing Kubernetes environments provided outside <Term name="company" />. They can include standard Kubernetes environments, external Kubernetes distributions, or public cloud Kubernetes services. <Term name="productShort" /> can provide centralized governance and operations within documented prerequisites and caveats, but onboarding does not make <Term name="productShort" /> the owner of the external cluster's Kubernetes lifecycle, node lifecycle, or provider infrastructure lifecycle.

### Tunnel-Based Connectivity
Third-party clusters are onboarded through import or register workflows:

* When the **Global cluster** cannot directly access a **Workload cluster**, a **Tunnel Server** (global side) and **Tunnel Agent** (workload side) establish secure communication.
* Suitable for disconnected or restricted network environments.
| Onboarding method | Connection model | Use when |
| --- | --- | --- |
| Import cluster | The `global` cluster connects to the target cluster API server with supplied address, CA, and credentials. | The platform can reach the target cluster API server and the operator can provide the required cluster information. |
| Register cluster | A reverse proxy service in the target cluster initiates registration and establishes a tunnel to the platform. | The target cluster should initiate the connection, or direct platform access to the target API server is restricted. |

## Choosing the Right Model
Provider-specific caveats can apply to certificates, audit data, control-plane metrics, ingress, storage, node operations, connectivity, and Extension compatibility. Use the import and register workflow pages for detailed prerequisites.

| Scenario | Infra Provisioned By | Node OS Managed By | Kubernetes Managed By | Automation Level |
| ----------------------------------- | -------------------- | ---------------------------- | --------------------- | ---------------- |
| Platform-provisioned Infrastructure | Platform | Platform (Immutable OS only) | Platform | Full |
| User-provisioned Infrastructure | User | User | Platform | Partial |
| Hosted Control Plane (HCP) | Platform | Shared nodes (Platform) | Platform | Partial |
| Connected Cluster (Cloud or CNCF) | External Provider | External Provider | Partial / External | Minimal |
For onboarding workflows, see [Managed Clusters Overview](./managed/overview.mdx), [Import Clusters](./managed/import/overview.mdx), and [Register Cluster](./managed/register.mdx).

## Version Compatibility \{#version-compatibility}

When importing or connecting existing clusters, validate the Kubernetes version against the current ACP compatibility policy.
When importing or connecting existing clusters, validate the Kubernetes version against the current <Term name="productShort" /> compatibility policy.

### ACP 4.3 and Later
### ACP 4.3 And Later

- ACP 4.3 adds support for Kubernetes 1.34 for platform-managed cluster scenarios.
- For upgrades to ACP 4.3, workload clusters must remain within the compatible version range 1.34, 1.33, 1.32, and 1.31 before the `global` cluster upgrade.
- For third-party clusters, ACP 4.3 accepts Kubernetes versions in the range `>=1.19.0 <1.35.0` for management.
- Product documentation continues to list only the Kubernetes versions that have passed product validation for third-party cluster support and the default Extend baseline.
- Product validation for the Extend baseline covers the following capability areas:
- Installing and using Operators
- Installing and using Cluster Plugins
- ClickHouse-based logging
- VictoriaMetrics-based monitoring
- This does not mean that all specific Operators or Cluster Plugins are covered by product validation.
- For specific Operators or Cluster Plugins outside this baseline, refer to the relevant product documentation or contact technical support.
- For ACP 4.3 and later, workload clusters no longer need to be on the single latest compatible Kubernetes minor release before the `global` cluster upgrade.
- <Term name="productShort" /> 4.3 adds support for Kubernetes 1.34 for platform-managed cluster scenarios.
- For upgrades to <Term name="productShort" /> 4.3, workload clusters must remain within the compatible version range 1.34, 1.33, 1.32, and 1.31 before the `global` cluster upgrade.
- For third-party clusters, <Term name="productShort" /> 4.3 accepts Kubernetes versions in the range `>=1.19.0 <1.35.0` for onboarding. Clusters outside that range are blocked from onboarding.
- The accepted onboarding range is separate from the compatible Kubernetes versions used to determine whether the `global` cluster can be upgraded.
- The accepted onboarding range does not mean that every Kubernetes version, provider, operation, capability, or Extension in the range has complete product validation.
- Product validation for the default Extend baseline covers installing and using Operators, installing and using Cluster Plugins, ClickHouse-based logging, and VictoriaMetrics-based monitoring. This does not mean that all specific Operators or Cluster Plugins are covered by product validation.
- For <Term name="productShort" /> 4.3 and later, workload clusters no longer need to be on the single latest compatible Kubernetes minor release before the `global` cluster upgrade.

### ACP 4.2 and Earlier
### ACP 4.2 And Earlier

- Upgrade workload clusters to the latest documented compatible Kubernetes version before upgrading the `global` cluster.
- Use the [Kubernetes Support Matrix](../../overview/kubernetes-support-matrix.mdx) as the main reference for the documented version mapping.
4 changes: 2 additions & 2 deletions docs/en/install/global_dr.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
weight: 40
weight: 60
---

# Global Cluster Disaster Recovery

<Directive type="info" title="Disaster Recovery Path">
This page documents disaster recovery for `global` clusters running on a **traditional operating system**. Disaster recovery for `global` clusters on Immutable Infrastructure is in development; see <ExternalSiteLink name="immutable-infra" href="/global/disaster_recovery.html" children="Global Cluster Disaster Recovery on Immutable Infrastructure" />.
This disaster recovery path applies to `global` clusters running on a **traditional operating system**. Disaster recovery for `global` clusters on Immutable Infrastructure is in development; see <ExternalSiteLink name="immutable-infra" href="/global/disaster_recovery.html" children="Global Cluster Disaster Recovery on Immutable Infrastructure" />.
</Directive>

## Overview
Expand Down
2 changes: 0 additions & 2 deletions docs/en/install/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ weight: 20

# Install

This document will provide all the information regarding the installation of <Term name="productShort" />.

<Directive type="info" title="Installation Path Selection">
This section documents installation onto a **traditional operating system** such as Ubuntu or RHEL. If your environment runs on Immutable Infrastructure (MicroOS on Huawei DCS, VMware vSphere, or Huawei Cloud Stack), see <ExternalSiteLink name="immutable-infra" href="/global/install.html" children="Installing the global Cluster on Immutable Infrastructure" /> instead.
</Directive>
Expand Down
Loading