diff --git a/docs/en/configure/clusters/overview.mdx b/docs/en/configure/clusters/overview.mdx index f155e7db7..bb55eb9ee 100644 --- a/docs/en/configure/clusters/overview.mdx +++ b/docs/en/configure/clusters/overview.mdx @@ -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 4.3 scenario. | [About Hosted Control Plane](./about-hcp.mdx) | HCP is Technology Preview in 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 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 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 , HCP is implemented through Kamaji (`TenantControlPlane`). In 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 . They can include standard Kubernetes environments, external Kubernetes distributions, or public cloud Kubernetes services. can provide centralized governance and operations within documented prerequisites and caveats, but onboarding does not make 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 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. +- 4.3 adds support for Kubernetes 1.34 for platform-managed cluster scenarios. +- For upgrades to 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, 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 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. diff --git a/docs/en/install/global_dr.mdx b/docs/en/install/global_dr.mdx index fe627b434..d1d5b549e 100644 --- a/docs/en/install/global_dr.mdx +++ b/docs/en/install/global_dr.mdx @@ -1,11 +1,11 @@ --- -weight: 40 +weight: 60 --- # Global Cluster Disaster Recovery -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 . +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 . ## Overview diff --git a/docs/en/install/index.mdx b/docs/en/install/index.mdx index 6a5b0b708..5d302afb1 100644 --- a/docs/en/install/index.mdx +++ b/docs/en/install/index.mdx @@ -4,8 +4,6 @@ weight: 20 # Install -This document will provide all the information regarding the installation of . - 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 instead. diff --git a/docs/en/install/installing.mdx b/docs/en/install/installing.mdx index 79dbe71f3..1b6c5e22f 100644 --- a/docs/en/install/installing.mdx +++ b/docs/en/install/installing.mdx @@ -4,10 +4,10 @@ weight: 30 # Installing -This section describes the specific steps for installing the `global` cluster. +This section describes how to install Core and deploy the `global` cluster. -This page documents the **traditional operating system** installation path. If your environment runs on Immutable Infrastructure (MicroOS on Huawei DCS, VMware vSphere, or Huawei Cloud Stack), see instead. +This installation path applies to clusters running on a **traditional operating system**. For environments on Immutable Infrastructure (MicroOS on Huawei DCS, VMware vSphere, or Huawei Cloud Stack), see instead. Before starting the installation, please ensure that you have completed the prerequisite checks, installation package download and verification, node preprocessing, and other preparatory work. @@ -28,7 +28,7 @@ cd /root/cpaas-install/installer || exit 1 - This machine will become the first control plane node after the `global` cluster installation is complete. - After the Core Package is extracted, at least **100GB** of disk space is required. Please ensure sufficient storage resources. -- If you have already downloaded extensions, complete the ACP Core installation first, and then follow [Extend](/extend) to upload and install them. +- If you have already downloaded extensions, complete the Core installation first, and then follow [Extend](../extend/index.mdx) to upload and install them. ### Start the Installer \{#start_installer} @@ -59,83 +59,11 @@ After completing the installation parameter configuration according to the page [Parameter Description](#parameters) provides detailed descriptions of key parameters. Please read carefully and configure according to actual needs. -### Monitor Installation Progress \{#monitor-progress} - -After you confirm the parameters, the installer runs through several phases. A 3-node `global` cluster usually completes in 30–60 minutes; total time depends on node hardware, network throughput, and the number of plugins selected. - -#### Phases You Will Observe - -| Phase | What is happening | First place to watch | -|---|---|---| -| Bootstrap | The installer container starts in the temporary `minialauda` KIND environment on the installation node and brings up the embedded registry. | Terminal output of `bash setup.sh` | -| Control plane provisioning | The first control plane node is bootstrapped with kubeadm; etcd starts; additional control plane nodes join. | Installer Web UI; installer log | -| Network and core add-ons | The CNI (Kube-OVN by default), CoreDNS, kube-proxy, and other in-cluster networking components come up. | Installer Web UI; `kubectl get pods -n kube-system` on the new cluster | -| Core platform | The base operator deploys, `ClusterModule/global` is created, and the platform control plane comes up. | Installer Web UI; `kubectl get clustermodule global` | -| Aligned plugins | AppReleases for the selected Aligned plugins reconcile. | `kubectl get apprelease -A` | -| Completion | The installer posts the platform access URL and stops the bootstrap container after a short grace period. | Installer Web UI; `/var/cpaas/data/installer.log` | - -#### Signals During Installation - -If the Web UI appears stuck for more than a few minutes, check the backend signals instead — the Web UI polls a backend progress API and can lag, but the underlying state is always available from the installation node. - -```shell -# Live installer log on the installation node -tail -f /var/cpaas/data/installer.log - -# Use the installer kubeconfig until the global cluster takes over -export KUBECONFIG=/var/cpaas/data/alauda.kubeconfig - -# Cluster API resources that drive the new global cluster -kubectl get clusters.cluster.x-k8s.io -A -kubectl get kubeadmcontrolplane -A -kubectl get machines -A - -# Charts that the installer is reconciling -kubectl get apprelease -A -``` - -The installer log records each phase transition and any retryable errors. Most transient errors retry automatically on a 10-second interval; persistent errors stay in the log and surface in the Web UI as a stalled phase. - -### Verify Successful Installation - -After the installation completes, the platform access URL is displayed in the Web UI. Click the **Access** button to open the platform and confirm that login succeeds. - -Next, run the following commands on a control plane node of the new `global` cluster to confirm the installed state: - -```shell -# All nodes are Ready -kubectl get nodes - -# ClusterModule/global reports the base module as healthy -kubectl get clustermodule global -o jsonpath='{.status.phase}' - -# No AppRelease is in a failed state -kubectl get apprelease -A - -# No Pod is stuck outside Running or Completed -kubectl get pod --all-namespaces | awk '{if ($4 != "Running" && $4 != "Completed")print}' | awk -F'[/ ]+' '{if ($3 != $4)print}' -``` - -The installation is healthy when: - -- All `global` cluster nodes are `Ready`. -- `ClusterModule/global` reports a healthy phase. -- Every AppRelease is in a non-failed state. -- Critical Pods in `cpaas-system` are `Running` or `Completed`. - -### Install Product Docs Plugin - -:::info -The **Alauda Container Platform Product Docs** plugin provides access to product documentation within the platform. All help links throughout the platform will direct users to this documentation. If this plugin is not installed, clicking help links in the platform will result in 404 access errors. -::: - -1. Navigate to **Administrator**. - -2. In the left sidebar, click **Marketplace** > **Cluster Plugins** and select the `global` cluster. + -3. Locate the **Alauda Container Platform Product Docs** plugin and click **Install**. +## Validate the Installation - +After the installer reports that Core installation is complete, validate the platform before continuing with post-install tasks. For the checklist and commands, see [Validation](./validation.mdx). ## Parameter Description \{#parameters} @@ -275,4 +203,6 @@ nerdctl rm -f minialauda-control-plane ## Additional Resources -- [Upload and Install Extensions](../extend) +- [Upload and Install Extensions](../extend/index.mdx) +- [Validation](./validation.mdx) +- [Next Steps](./next_steps.mdx) diff --git a/docs/en/install/next_steps.mdx b/docs/en/install/next_steps.mdx new file mode 100644 index 000000000..738501ac1 --- /dev/null +++ b/docs/en/install/next_steps.mdx @@ -0,0 +1,32 @@ +--- +weight: 50 +--- + +# Next Steps + +After Core validation succeeds, complete the following post-install tasks according to your scenario. + +| 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 | Create workload clusters or connect existing clusters. | Use this path when your architecture requires workload clusters separate from the `global` cluster. | [Clusters](../configure/clusters/index.mdx) | +| Conditional | Upload and install Extensions Packages. | Use this path when you need additional platform capabilities after Core is installed. | [Extend](../extend/index.mdx) | +| Recommended before broad user onboarding | Configure identity providers, users, roles, projects, and project membership. | Use this path before onboarding administrators, project users, or application teams. | [Users and Roles](../security/users_and_roles/index.mdx) and [Projects](../security/project/index.mdx) | +| Recommended before application workloads | Prepare storage, networking, registry access, and workload prerequisites. | Use this path before application teams deploy workloads. | [Storage](../configure/storage/index.mdx), [Networking](../configure/networking/index.mdx), [Registry](../developer/registry/index.mdx), and [Clusters](../configure/clusters/index.mdx) | +| Recommended before production operation | Review backup, upgrade, monitoring, and operational documentation. | Use this path before operating the platform for production workloads. | [Backup](../configure/backup/index.mdx), [Upgrade](../upgrade/index.mdx), and [Observability](../observability/index.mdx) | + +These tasks do not all apply to every installation. Follow the paths that match your deployment architecture and operational requirements. + +## Install Product Docs Plugin \{#install_product_docs_plugin} + +The ** Product Docs** plugin provides access to product documentation within the platform. All help links throughout the platform direct users to this documentation. If this plugin is not installed, clicking help links in the platform results in 404 access errors. + + +### Open Cluster Plugins + +Navigate to **Administrator**. In the left sidebar, click **Marketplace** > **Cluster Plugins** and select the `global` cluster. + +### Install the Plugin + +Locate the ** Product Docs** plugin and click **Install**. + diff --git a/docs/en/install/overview.mdx b/docs/en/install/overview.mdx index e539278f1..0bbdde063 100644 --- a/docs/en/install/overview.mdx +++ b/docs/en/install/overview.mdx @@ -4,68 +4,53 @@ weight: 10 # Overview -By following this guide, you will complete the installation of ** Core**. -If you need to understand the concept of ** Core**, refer to [Architecture](../overview/architecture.mdx). +Use the Install section to plan and complete ** Core** installation. -Installing ** Core** refers to the process of deploying the `global` cluster. + Core installation deploys the `global` cluster, which provides the platform management plane for web console access, cluster management, users and roles, and extension management. For the platform architecture and definitions of `global` cluster and workload cluster, see [Architecture](../overview/architecture.mdx) and [Glossary](../overview/glossary.mdx). -After the installation, you can **create new workload clusters** or **connect existing ones**, and install additional **Extensions** to enhance the platform's capabilities. + Core installation does not create workload clusters, import existing clusters, or install Extensions Packages. Operators and Cluster Plugins that are delivered as Extensions are installed after Core through the [Extend](../extend/index.mdx) workflow. -Before installation, please ensure that you have completed capacity planning, environment preprocessing, and prerequisite checks to ensure that the hardware, network, and OS of each node meet the requirements. -The following content covers platform architecture design, installation methods, and key term explanations to help you grasp the core points during the actual installation process. + Core installation does not support direct installation of the `global` cluster into an existing Kubernetes environment. Prepare new nodes that meet the hardware, network, storage, and OS requirements before you start installation. -## Installation Method +## Installation Scope + + Core installation provides the foundation for the platform management plane. After Core is installed and verified, you can create or connect workload clusters and install Extensions according to your platform scenario. The procedure described in this section installs the `global` cluster onto a **traditional operating system** such as Ubuntu or RHEL. If you want the `global` cluster to run on Immutable Infrastructure (MicroOS on Huawei DCS, VMware vSphere, or Huawei Cloud Stack), see instead. -The installation process of the `global` cluster is mainly divided into three stages: - -1. **Preparation Stage** - - **Prerequisite Check**: Ensure that all node hardware, network, and OS meet the requirements, such as kernel version, CPU architecture, and network configuration. - - **Installation Package Download**: Log in to the Customer Portal to obtain the latest installation package. - - **Node Preprocessing**: Complete the preprocessing work of all nodes. - -2. **Execution Stage** - - **Installation Package Upload and Extraction**: Upload the installation package to the target control plane node (recommended directory: `/root/cpaas-install`) and extract the installation resources. - - **Start the Installer**: Execute the installation script (such as `bash setup.sh`) on the control plane node, and select IP protocol mode (IPv4/IPv6/dual stack) and VIP configuration according to the actual environment. - - **Parameter Configuration**: Access the Web UI provided by the installer, and set the Kubernetes version, cluster network, node name, access address, and other key parameters in sequence to complete the installation of the `global` cluster. - -3. **Verification Stage** - - **System Status Check**: After the installation is complete, log in to the platform Web UI to check the cluster status and the operating status of each component. - - **CLI Verification**: Use command-line tools to check the cluster resource status to ensure that all services are running normally and there are no exceptions or failures. - -The following chapters will further explain the detailed operations, configuration parameters, and verification methods of each installation stage. Please read carefully and complete the corresponding preparatory work before the formal installation. - -## Appendix — Customer Portal +The following work is outside the Core installation flow: -** Customer Portal** is 's unified customer service and delivery platform that provides centralized access to all product-related resources and support services. It serves as the official entry point for customers, partners, and delivery teams to obtain software packages, documentation, support, and license management in a secure and consistent manner. +- Creating workload clusters. +- Connecting existing Kubernetes clusters. +- Uploading and installing Extensions Packages. +- Installing Operators or Cluster Plugins that are delivered as Extensions. +- Configuring optional platform capabilities such as storage, monitoring, backup, registry, or identity integrations. -### Purpose and Overview +## Installation Workflow -The Customer Portal streamlines the end-to-end product lifecycle—from installation and configuration to maintenance and support—by consolidating all essential resources into one platform. It ensures that every deployment is based on verified software versions and official technical guidance. + Core installation follows this high-level path: -### Key Features +1. [Plan](./planning.mdx). Choose the deployment architecture and confirm install-time decisions. +2. [Prepare for installation](./prepare/index.mdx). Prepare resources, network access, storage, and nodes. +3. [Download](./prepare/download.mdx). Obtain the official Core Package from the Customer Portal. +4. [Installing](./installing.mdx). Upload the Core Package, start the installer, and configure installation parameters. +5. [Validation](./validation.mdx). Confirm that the platform Web UI, core applications, and Pods are healthy. +6. [Next Steps](./next_steps.mdx). Install the Product Docs plugin and follow scenario-based next steps. -* **Product Downloads** - Provides access to verified installation and upgrade packages, ensuring that deployments are consistent with the latest supported product versions. +The Customer Portal is the official source for installation packages. For download requirements and package architecture options, see [Download](./prepare/download.mdx). -* **Knowledge Base** - Offers comprehensive product documentation, technical articles, troubleshooting guides, and best practices to assist with installation, configuration, and operations. - -* **Support Tickets** - Enables users to submit, track, and manage support requests directly online, ensuring timely issue resolution and full visibility into support progress. - -* **Application Marketplace** - Delivers a curated collection of official and third-party extensions that can be installed to extend or customize the platform's capabilities. - -* **License Management** - Supports the application, activation, and renewal of software licenses, providing traceable and compliant license usage across all environments. + +If you have already downloaded Extensions Packages, install Core first. Upload and install Extensions Packages only after Core installation is complete. + -### Usage Guidance +## Related Documentation -Before starting installation or upgrade activities, users should log in to the ** Customer Portal** using their authorized account to download the required installation packages and verify license status. -For customer delivery and production environments, the versions and documentation published on the Customer Portal should always be regarded as the **official baseline** for deployment and maintenance. +- [Architecture](../overview/architecture.mdx) +- [Glossary](../overview/glossary.mdx) +- [Kubernetes Support Matrix](../overview/kubernetes-support-matrix.mdx) +- [Disk Configuration Requirements](../configure/scalability/disk_configuration.mdx) +- [Extend](../extend/index.mdx) diff --git a/docs/en/install/planning.mdx b/docs/en/install/planning.mdx new file mode 100644 index 000000000..148faeb58 --- /dev/null +++ b/docs/en/install/planning.mdx @@ -0,0 +1,51 @@ +--- +weight: 15 +--- + +# Plan + +Before you start the installer, choose the deployment architecture and confirm the installation settings that affect later operations. + + + Core installation deploys the `global` cluster on prepared nodes. It does not support direct installation of the `global` cluster into an existing Kubernetes environment. + + +## Choose a Deployment Architecture + +Choose the architecture that matches your business scenario, management model, workload placement, resource planning, and isolation requirements. + +| Architecture | Use when | Planning notes | +| --- | --- | --- | +| Multi-Cluster | You need one `global` cluster to manage multiple workload clusters. | Avoid running non-platform workloads on the `global` cluster. Plan resources for the expected number of managed workload clusters. | +| Single Cluster | You intentionally use one cluster for platform components and application workloads. | Single Cluster supports production use when it fits the business scenario. Because the `global` cluster also runs application workloads, plan resources and platform/workload isolation before installation. | +| Single Node | You need a test or proof-of-concept environment. | Do not use Single Node for production. | + +For resource requirements and sizing guidance, see [Prerequisites](./prepare/prerequisites.mdx). + +## Confirm Install-Time Decisions + +Confirm the following decisions before running the installer: + +| Decision | What to confirm | Continue with | +| --- | --- | --- | +| Package architecture | Choose an x86, ARM, or hybrid Core Package. | [Download](./prepare/download.mdx) | +| Cluster network protocol | Choose IPv4, IPv6, or dual stack before starting the installer. | [Installing](./installing.mdx#start_installer) | +| Cluster Endpoint and Platform Access Address | Prepare the access addresses that cluster components, administrators, and users will use. | [Prerequisites](./prepare/prerequisites.mdx#network-resources) and [Parameter Description](./installing.mdx#parameters) | +| Load balancing | Decide whether to use an external load balancer or Self-built VIP. | [Prerequisites](./prepare/prerequisites.mdx#network-resources) and [LoadBalancer Forwarding Rules](./prepare/prerequisites.mdx#port-forward) | +| Certificates | Decide whether to use installer-generated self-signed certificates or trusted certificates that you provide. | [Prerequisites](./prepare/prerequisites.mdx#network-resources) and [Parameter Description](./installing.mdx#parameters) | +| Image repository | Decide whether to use the platform deployment image repository or an external image repository. | [Parameter Description](./installing.mdx#parameters) | +| Nodes | Confirm node names, node roles, and whether platform node isolation is required. | [Node Preprocessing](./prepare/node_preprocessing.mdx) and [Parameter Description](./installing.mdx#parameters) | +| Global Cluster Disaster Recovery | Decide whether your environment requires primary and standby `global` clusters. | [Global Cluster Disaster Recovery](./global_dr.mdx) | + +If you plan to use Global Cluster Disaster Recovery, read [Global Cluster Disaster Recovery](./global_dr.mdx) before installing Core. Disaster recovery planning affects domain names, VIPs, certificates, load balancer rules, image registry choices, package architecture, and installation parameter consistency. + +## Read Before You Install + +Use the following pages as the source of truth before running the installer: + +- [Prerequisites](./prepare/prerequisites.mdx): Prepare resource, network, and storage requirements. +- [Disk Configuration Requirements](../configure/scalability/disk_configuration.mdx): Confirm disk capacity and performance requirements. +- [Node Preprocessing](./prepare/node_preprocessing.mdx): Check and prepare each node before installation. +- [Download](./prepare/download.mdx): Download the Core Package and select the package architecture. +- [Global Cluster Disaster Recovery](./global_dr.mdx): Plan primary and standby `global` clusters if disaster recovery is required. +- [Installing](./installing.mdx): Upload the Core Package, start the installer, and configure parameters. diff --git a/docs/en/install/prepare/download.mdx b/docs/en/install/prepare/download.mdx index a7eb1de7d..742a12cd3 100644 --- a/docs/en/install/prepare/download.mdx +++ b/docs/en/install/prepare/download.mdx @@ -1,22 +1,34 @@ --- weight: 20 -title: Download --- +# Download \{#download_core_package} -# Download Core Package \{#download_core_package} +Before installation, download the **Core Package** from the ** Customer Portal**. -Before installation, you need to download the **Core Package**. +## About the Customer Portal + +The ** Customer Portal** is the official service and delivery portal for product resources. Use it to obtain verified software packages and official technical guidance for installation, upgrade, and maintenance activities. + +The Customer Portal provides access to the following resources: + +- Product downloads, including installation, upgrade, and extension packages. +- Product documentation and technical guidance. +- Support resources for submitting, tracking, and managing support requests. +- Marketplace packages for extending platform capabilities. +- License-related resources for deployment and maintenance planning. + +Use an authorized account to download the package required for your environment. If you do not have a registered account, contact technical support. Starting from v4.1, if you download both the **Core Package** and the **Extensions Packages**, you must complete the installation of the **Core Package** before uploading and installing **Extensions Packages**. -Log in to the ** Customer Portal** to download the **Core Package**. +For customer delivery and production environments, use the package versions and documentation published on the Customer Portal as the official deployment and maintenance baseline. -Packages are available for **x86**, **ARM**, and **hybrid** architectures. The hybrid package includes images for both x86 and ARM, resulting in a larger package size. Select the package that best matches your environment. +## Choose a Package Architecture -If you do not have a registered account, please contact technical support. +Packages are available for **x86**, **ARM**, and **hybrid** architectures. The hybrid package includes images for both x86 and ARM, resulting in a larger package size. Select the package that best matches your environment. ## Migrating from Single-Architecture to Hybrid diff --git a/docs/en/install/prepare/node_preprocessing.mdx b/docs/en/install/prepare/node_preprocessing.mdx index 32346b4f6..91f28b47a 100644 --- a/docs/en/install/prepare/node_preprocessing.mdx +++ b/docs/en/install/prepare/node_preprocessing.mdx @@ -21,9 +21,9 @@ The platform enforces strict version matching policies for official support: ::: :::info -`x86-64-v2` is a CPU instruction set baseline used by some operating systems, platform images, or optional components. For user-provided operating systems, ACP does not impose a universal `x86-64-v2` requirement on all x86 nodes. If you use older CPUs, verify CPU compatibility according to the selected operating system and the components you plan to deploy. +`x86-64-v2` is a CPU instruction set baseline used by some operating systems, platform images, or optional components. For user-provided operating systems, does not impose a universal `x86-64-v2` requirement on all x86 nodes. If you use older CPUs, verify CPU compatibility according to the selected operating system and the components you plan to deploy. -For ACP-provided immutable operating system images or platform images, follow the CPU baseline requirements documented for those images. +For -provided immutable operating system images or platform images, follow the CPU baseline requirements documented for those images. ::: ### x86 diff --git a/docs/en/install/validation.mdx b/docs/en/install/validation.mdx new file mode 100644 index 000000000..b497fe6f2 --- /dev/null +++ b/docs/en/install/validation.mdx @@ -0,0 +1,46 @@ +--- +weight: 35 +--- + +# Validation + +Validate Core after the installer completes and before you continue with post-install tasks. + +## Prerequisites + +- Core installation completed. +- You can access the platform Web UI address shown by the installer. +- You can run `kubectl` from the installation node. + +## Validate Web UI Access + +After the installation is complete, the installer displays the platform access URL. Click **Access** to open the platform Web UI and verify that the platform login page is reachable. + +## Validate Core Applications and Pods + +Run the following commands on a control plane node of the new `global` cluster to confirm the installed state: + +```shell +# All nodes are Ready +kubectl get nodes + +# ClusterModule/global reports the base module as healthy +kubectl get clustermodule global -o jsonpath='{.status.phase}' + +# No AppRelease is in a failed state +kubectl get apprelease -A + +# No Pod is stuck outside Running or Completed +kubectl get pod --all-namespaces | awk '{if ($4 != "Running" && $4 != "Completed")print}' | awk -F'[/ ]+' '{if ($3 != $4)print}' +``` + +The installation is healthy when: + +- All `global` cluster nodes are `Ready`. +- `ClusterModule/global` reports a healthy phase. +- Every AppRelease is in a non-failed state. +- Critical Pods in `cpaas-system` are `Running` or `Completed`. + +## Next Step + +After validation succeeds, continue with [Next Steps](./next_steps.mdx). diff --git a/docs/en/overview/architecture.mdx b/docs/en/overview/architecture.mdx index 8fdd7a8dc..3614d47fb 100644 --- a/docs/en/overview/architecture.mdx +++ b/docs/en/overview/architecture.mdx @@ -1,168 +1,97 @@ --- -weight: 10 -sourceSHA: 4da89a515625df223ad9cf7619ce7d5675d47744a3e30e8f5d63ae1c78041c06 +weight: 30 --- # Architecture -## Introduction to + uses a hub-and-spoke architecture. The `global` cluster provides the central management plane, and workload clusters or third-party clusters provide Kubernetes environments where applications and cluster-local components run. -The () provides an enterprise-grade Kubernetes-based platform that enables organizations to build, deploy, and manage applications consistently across hybrid and multi-cloud environments. integrates core Kubernetes capabilities with enhanced management, observability, and security services, offering a unified control plane and flexible workload clusters. +Use the diagram as a high-level view of this model. The architecture details below clarify 4.3 boundaries that are not visible in the diagram. -The architecture follows a **hub-and-spoke** model, consisting of a `global` cluster and multiple workload clusters. This design provides centralized governance while allowing independent workload execution and scalability. +![Architecture overview](./assets/arch-overview.svg) -For canonical definitions of platform-wide terms such as `global` cluster, workload cluster, and cluster plugin, see [Glossary](./glossary.mdx). +For platform-wide terms, see [Glossary](./glossary.mdx). For the conceptual platform model, see [Platform Model](./platform-model.mdx). -![](./assets/arch-overview.svg) +## Hub-And-Spoke Model -## Core Architectural Components +| Part | Role | +| --- | --- | +| `global` cluster | Hosts the platform management plane, including web console access, platform APIs, authentication integration, project governance, cluster management, Extension management, and platform-wide coordination. | +| Workload clusters | Run application workloads and cluster-local components under governance from the `global` cluster. | +| Third-party clusters | Existing Kubernetes environments onboarded to the platform for centralized governance and operations within documented prerequisites and caveats. | -### Global Cluster +The hub-and-spoke model describes the relationship between the `global` cluster and the Kubernetes environments that it manages. For control-plane topology, including Hosted Control Plane, see [Cluster Management Models](./cluster-management-models.mdx). -The `global` cluster serves as the centralized management and control hub of . It provides platform-wide services such as authentication, policy management, cluster lifecycle operations, and observability. It's also a central hub for multi-cluster management and provides cross-cluster functionality. +The `global` cluster is the platform hub. Workload clusters and third-party clusters are spokes. A project can span associated clusters, and namespaces provide Kubernetes resource isolation inside those clusters. -Key components include: +## Access And Request Path -- **Gateway** - Acts as the main entry point to the platform. It manages API requests from the UI, CLI (kubectl), and automation tools, routing them to appropriate backend services. -- **Authentication and Authorization (Auth)** - Integrates with external Identity Providers (**IdPs**) to provide Single Sign-On (SSO) and RBAC-based access control. -- **Web Console** - Provides a web-based interface for . It interfaces with platform APIs through the gateway. -- **Cluster Management** - Handles the registration, provisioning, and lifecycle management of workload clusters. -- ** Services** -- **Operator Lifecycle Manager (OLM) and Cluster Plugins** - Manages the installation, updates, and lifecycle of operators and cluster extensions. -- **Internal Image Registry** - Offers an out-of-box integrated container image repository with role-based access. -- **Observability** - Provides centralized logging, metrics, and tracing for both the `global` and workload clusters. -- **Cluster Proxy** - Enables secure communication between the `global` cluster and workload clusters. +Users and automation usually access the platform through the Platform Access Address, web console, platform APIs, Kubernetes APIs, or CLI tools. -### Workload Cluster +At a high level: -Workload clusters are Kubernetes-based environments managed by the `global` cluster. Each workload cluster runs isolated application workloads and inherits governance and configuration from the central control plane. +1. A user, CLI, automation tool, or browser connects to the Platform Access Address. +2. A load balancer, VIP, DNS record, or ingress path routes traffic to platform entry components. +3. Platform API services evaluate authentication and authorization. +4. Requests are handled by the `global` cluster or forwarded to target clusters through the documented cluster access path. +5. Kubernetes API requests to target clusters are evaluated against the user's effective RBAC permissions. -### External Integrations +For API usage, see [API Introduction](../apis/overview/intro.mdx). For CLI tools, see [CLI Tools](../ui/cli_tools/index.mdx). For cluster KubeConfig access, see [Access a Cluster with KubeConfig](../configure/clusters/how-to/access-cluster-with-kubeconfig.mdx). -- **Identity Provider (IdP)** - Supports federated authentication via standard protocols (OIDC, SAML) for unified user management. -- **API and CLI Access** - Users can interact with through RESTful APIs, the web console, or command-line tools like `kubectl` and `ac`. -- **Load Balancer (VIP/DNS/SLB)** - Provides high availability and traffic distribution to the Gateway and ingress endpoints of the `global` and workload Clusters. +## Management Path -## Scalability and High Availability +The `global` cluster coordinates platform management operations: - is designed for horizontal scalability and high availability: +- Cluster creation and lifecycle operations for supported lifecycle-managed cluster models. +- Third-party cluster onboarding through import or register workflows. +- Project, namespace, user, role, and quota governance. +- Operator and Cluster Plugin discovery, package upload, installation, and upgrade entry points. +- Central views for observability, audit, inventory, and operations when the required components are installed. -- Each component can be deployed redundantly to eliminate single points of failure. -- The `global` cluster supports managing dozens to hundreds of workload clusters. -- Workload clusters can scale independently according to workload demand. -- The use of VIP/DNS/Ingress ensures seamless routing and failover. +For third-party clusters, the management path depends on version range, connectivity, credentials, provider prerequisites, installed components, and Extension compatibility. Onboarding a third-party cluster does not make the owner of that cluster's Kubernetes lifecycle, node lifecycle, or provider infrastructure lifecycle. -## Functional Perspective +For model boundaries, see [Cluster Management Models](./cluster-management-models.mdx). - ()'s complete functionality consists of ** Core** and extensions based on two technical stacks: **Operator** and **Cluster Plugin**. +## State And Data Domains -- ** Core** +Different data domains have different protection and recovery paths: - The minimal deliverable unit of , providing core capabilities such as cluster management, container orchestration, projects, and user administration. +| Domain | Primary location or owner | Recovery path | +| --- | --- | --- | +| `global` cluster Kubernetes resource state | `global` cluster etcd | Global Cluster Disaster Recovery or etcd backup/restore, depending on scenario. | +| Workload cluster Kubernetes resource state | Each workload cluster etcd | Cluster-specific backup/restore or upgrade procedures. | +| Third-party cluster lifecycle data | External cluster owner, distribution, or provider | External provider or owner procedures, plus onboarding and operations records. | +| Registry data | Registry component or backend | Registry backup and recovery procedures. | +| Monitoring and logging data | Installed monitoring and logging components | Component-specific backup or restore procedures. | +| Application data | Application namespaces, persistent volumes, databases, and storage backends | Application backup/restore or the data-service-specific recovery procedure. | - - Meets the highest security standards - - Delivers maximum stability - - Offers the longest support lifecycle +Global Cluster Disaster Recovery protects only the `global` control-plane DR scenario documented in [Availability and Recovery](./availability-and-recovery.mdx). It is not full platform data DR and is not application data DR. -- **Extensions** +## Core And Extension Boundary - Extensions in both the Operator and Cluster Plugin stacks can be classified into: + Core provides the platform management plane and the frameworks used to manage clusters, projects, users, APIs, and Extensions. - - **Aligned** – Life cycle strategy consisting of multiple maintenance streams, with alignment to . - - **Agnostic** – Life cycle strategy consisting of multiple maintenance streams, released independently from . +Additional capabilities can require separately installed Extensions, such as Operators and Cluster Plugins, or separate products. Examples include specific observability backends, registry plugins, API filtering, compliance features, container security, data services, GitOps, logging, Immutable Infrastructure, and Hosted Control Plane. - For more details about extensions, see [Extend](../extend/index.mdx). +Before planning those capabilities as part of an architecture, check the corresponding documentation for installation, upgrade, compatibility, and limitations. -## Technical Perspective +For details, see [Core and Extensions](./core-and-extensions.mdx). -**Platform Component Runtime** -All platform components run as containers within a Kubernetes management cluster (the `global` cluster). +## Availability And Recovery Model -**High Availability Architecture** +Availability is planned by topology: -- The `global` cluster typically consists of at least three control plane nodes and multiple worker nodes -- High availability of etcd is central to cluster HA; see *Key Component High Availability Mechanisms* for details -- Load balancing can be provided by an external load balancer or a self-built VIP inside the cluster +- Single Node is for testing or proof-of-concept only. +- Single Cluster can support production use when it fits the business scenario and resources are planned for both platform components and workloads. +- Multi-Cluster separates the `global` cluster management plane from workload clusters and should avoid non-platform business workloads on the `global` cluster. +- Three control plane nodes are the HA baseline. Five control plane nodes are scale and reliability guidance, not a universal production gate. -**Request Routing** +For detailed planning, sizing, Global DR, and backup/restore entry points, see [Availability and Recovery](./availability-and-recovery.mdx). -- Client requests first pass through the load balancer or self-built VIP -- Requests are forwarded to **ALB** (the platform's default Kubernetes Ingress Gateway) running on designated ingress nodes (or control-plane nodes if configured) -- ALB routes traffic to the target component pods according to configured rules +## Continue Reading -**Replica Strategy** - -- Core components run with at least two replicas -- Key components (such as registry, MinIO, ALB) run with three replicas - -**Fault Tolerance & Self-healing** - -- Achieved through cooperation between kubelet, kube-controller-manager, kube-scheduler, kube-proxy, ALB, and other components -- Includes health checks, failover, and traffic redirection - -**Data Storage & Recovery** - -- Control-plane configuration and platform state are stored in etcd as Kubernetes resources -- In catastrophic failures, recovery can be performed from etcd snapshots - -**Primary / Standby Disaster Recovery** - -- Two separate `global` clusters: **Primary Cluster** and **Standby Cluster** -- The disaster recovery mechanism is based on real-time synchronization of etcd data from the Primary Cluster to the Standby Cluster. -- If the Primary Cluster becomes unavailable due to a failure, services can quickly switch to the Standby Cluster. - -### Key Component High Availability Mechanisms - -**etcd** - -- Deployed on three (or five) control plane nodes -- Uses the RAFT protocol for leader election and data replication -- Three-node deployments tolerate up to one node failure; five-node deployments tolerate up to two -- Supports local and remote S3 snapshot backups - -**Monitoring Components** - -- **Prometheus**: Multiple instances, deduplication with Thanos Query, and cross-region redundancy -- **VictoriaMetrics**: Cluster mode with distributed VMStorage, VMInsert, and VMSelect components - -**Logging Components** - -- **Nevermore** collects logs and audit data -- **Kafka / Elasticsearch / Razor / Lanaya** are deployed in distributed and multi-replica modes - -**Networking Components (CNI)** - -- **Kube-OVN / Calico / Flannel**: Achieve HA via stateless DaemonSets or triple-replica control plane components - -**ALB** - -- Operator deployed with three replicas, leader election enabled -- Instance-level health checks and load balancing - -**Self-built VIP** - -- High-availability virtual IP based on Keepalived -- Supports heartbeat detection and active-standby failover - -**Harbor** - -- ALB-based load balancing -- PostgreSQL with Patroni HA -- Redis Sentinel mode -- Stateless services deployed in multiple replicas - -**Registry and MinIO** - -- Registry deployed with three replicas -- MinIO in distributed mode with erasure coding, data redundancy, and automatic recovery +- [Introduction](./introduction.mdx) +- [Platform Model](./platform-model.mdx) +- [Cluster Management Models](./cluster-management-models.mdx) +- [Core and Extensions](./core-and-extensions.mdx) +- [Learn More](./learn-more.mdx) diff --git a/docs/en/overview/availability-and-recovery.mdx b/docs/en/overview/availability-and-recovery.mdx new file mode 100644 index 000000000..648800aea --- /dev/null +++ b/docs/en/overview/availability-and-recovery.mdx @@ -0,0 +1,77 @@ +--- +weight: 70 +--- + +# Availability and Recovery + +Plan availability and recovery by matching your environment to the appropriate deployment topology, high availability baseline, Global Cluster Disaster Recovery path, and backup or restore procedure. + +For detailed sizing, backup, restore, and disaster recovery procedures, follow the linked topic-specific pages. The guidance below focuses on planning choices and support boundaries. + +## Deployment Topology + +Choose topology by scenario, not by a single production minimum table. + +| Topology | Use when | Availability notes | +| --- | --- | --- | +| Multi-Cluster | One `global` cluster manages multiple workload clusters. | Avoid non-platform business workloads on the `global` cluster. Size the `global` cluster for the number of managed clusters, user concurrency, API traffic, and installed plugins. | +| Single Cluster | One cluster intentionally runs both platform components and business workloads. | Production-capable when it fits a single-business-system scenario. Plan resources for both platform components and workloads. The `global` cluster control plane uses 3 nodes in this mode. | +| Single Node | Test or proof-of-concept environments. | Do not use for production. | + +For installation planning, see [Plan](../install/planning.mdx) and [Prerequisites](../install/prepare/prerequisites.mdx). + +## High Availability Baseline + +For production-like environments, use 3 control plane nodes as the HA baseline. A 5 control plane node topology can improve scale and reliability for larger environments, but it is not a universal hard requirement for every production deployment. + +Infra nodes or custom role nodes are useful for isolating platform components or high-load components, but they are not a universal requirement unless a sizing tier or component document says so. For Extra Large `global` cluster sizing, follow the sizing guidance for dedicated infra nodes. + +| Planning topic | Source | +| --- | --- | +| `global` cluster sizing by managed cluster count | [Evaluating Resources for Global Cluster](../configure/scalability/evaluating_global.mdx) | +| Workload cluster control plane sizing and scale factors | [Evaluating Resources for Workload Cluster](../configure/scalability/evaluating_workload.mdx) | +| Node roles and infra/custom role nodes | [Cluster Node Planning](../configure/clusters/acp-node-planning.mdx) | +| Node requirements and OS/kernel support | [Node Preprocessing](../install/prepare/node_preprocessing.mdx) | + +## Global Cluster Disaster Recovery + +Global Cluster Disaster Recovery protects the platform management entry point and `global` control-plane services when the Primary `global` cluster becomes unavailable. + +For 4.3, Global DR has the following scope: + +- It uses Primary and Standby `global` clusters. +- It relies on real-time synchronization of resource state stored in the Primary `global` cluster etcd, except excluded namespaces. +- It restores the platform entry point and `global` control-plane services by switching DNS or VIP access to the Standby cluster. +- Primary and Standby should follow the validated path of aligned versions, patches, component versions, and key configuration. + +Do not treat Global DR as full platform data DR, application data DR, automatic failover, or an SLA-backed RPO/RTO commitment. Global DR does not cover registry data, chartmuseum data, other component data, application data, or resources excluded from etcd synchronization. + +For the procedure and supported scenarios, see [Global Cluster Disaster Recovery](../install/global_dr.mdx). + +## Backup And Restore Paths + +Recovery is composed by scenario. Each mechanism protects a specific data domain and has its own procedure, prerequisite, and limitation. + +| Scenario | Use | Source | +| --- | --- | --- | +| Primary `global` cluster failure | Global Cluster Disaster Recovery. | [Global Cluster Disaster Recovery](../install/global_dr.mdx) | +| Accidental cluster-state deletion or rollback | etcd backup and restore. | [etcd Backup and Restore](../configure/backup/etcd.mdx) | +| Registry image repository data | Registry backup and recovery. | [Registry Data Backup and Recovery](../developer/registry/how_to/registry_data_restore.mdx) | +| Monitoring data | Monitoring component backup or restore. | [VictoriaMetrics Backup and Recovery](../observability/monitor/how_to/restore_victoriametrics.mdx) | +| Logging data | Logging component backup or restore, according to the installed logging backend. | [Logging Service](../observability/log/intro.mdx) | +| Application resources and persistent volumes | Application backup and restore with Data Backup Essentials and Data Backup for Velero. | [Backup Overview](../configure/backup/overview.mdx) | + +Application backup can protect namespaces, Kubernetes resources, and persistent volume data according to the backup configuration. It does not support every storage or application data pattern. For example, `hostPath` PersistentVolumes are not supported by the documented application backup path, and database workloads should follow data-service-specific backup guidance. + +## Recovery Checklist + +Use this checklist to choose follow-up work. It does not replace the linked procedures: + +1. Choose Single Cluster, Multi-Cluster, or Single Node during installation planning. +2. Size the `global` cluster and workload clusters from the scalability guidance. +3. Decide whether Global Cluster Disaster Recovery is required before installing Core. +4. Configure backups for etcd, registry data, monitoring data, logging data, and applications according to the data domains you need to recover. +5. Run regular recovery checks and failover drills where your operational process requires them. +6. Verify platform access, `global` services, connected cluster access, and component-level recovery after failover or restore. + +For the next documentation path, see [Learn More](./learn-more.mdx). diff --git a/docs/en/overview/cluster-management-models.mdx b/docs/en/overview/cluster-management-models.mdx new file mode 100644 index 000000000..fb3ae0971 --- /dev/null +++ b/docs/en/overview/cluster-management-models.mdx @@ -0,0 +1,91 @@ +--- +weight: 50 +--- + +# Cluster Management Models + +Use the cluster management model to separate three planning decisions: + +1. Infrastructure responsibility. +2. Control-plane topology. +3. Kubernetes ownership and onboarding. + +Each cluster path combines choices from these axes. Installer-Provisioned Infrastructure (IPI), User-Provisioned Infrastructure (UPI), Hosted Control Plane (HCP), and the current UI label `Managed Cluster` are not one flat list of mutually exclusive cluster types. + +## Infrastructure Responsibility + +Infrastructure responsibility explains who provides and manages machines, node operating systems, and Kubernetes lifecycle. + +| Model | Machines and nodes | Node operating system | Kubernetes lifecycle | Main docs | +| --- | --- | --- | --- | --- | +| Installer-Provisioned Infrastructure (IPI) | Provisioned through the platform and its infrastructure provider integration. | Managed by the platform with Immutable OS. | Managed by the platform, including supported provisioning, scaling, and upgrade flows. | [About Immutable Infrastructure](../configure/clusters/immutable-infra.mdx) | +| User-Provisioned Infrastructure (UPI) | Prepared by the user as physical or virtual machines. | Managed by the user. | Installed and managed by the platform after the user prepares nodes. | [Creating an On-Premise Cluster](../configure/clusters/on-premises.mdx) | + +IPI and UPI describe responsibility boundaries. They do not by themselves describe whether the control plane is hosted or dedicated, and they do not describe whether a third-party cluster has been imported or registered. + +Existing third-party Kubernetes environments are covered under [Kubernetes Ownership And Onboarding](#kubernetes-ownership-and-onboarding), because their Kubernetes distribution and lifecycle usually exist outside . + +## Control-Plane Topology + +Control-plane topology explains where Kubernetes control plane components run. + +| Topology | Meaning | 4.3 boundary | +| --- | --- | --- | +| Dedicated control plane | Control plane components run on control plane nodes in the target cluster. | This is the normal topology for current production guidance. | +| Hosted Control Plane | Each hosted cluster has its own control plane, but the control plane runs as workloads on a management cluster. In , HCP is implemented through Kamaji (`TenantControlPlane`). | Technology Preview, not production-supported, supports disconnected environments, and defaults to IPI only. | + +HCP is an architecture for the control plane. It is not a Core default capability and is not a peer concept to IPI or UPI. + +For more information, see [About Hosted Control Plane](../configure/clusters/about-hcp.mdx). + +## Kubernetes Ownership And Onboarding \{#kubernetes-ownership-and-onboarding} + +Kubernetes ownership explains whether owns the Kubernetes lifecycle or whether the Kubernetes environment already exists outside . + +| Model | How it enters the platform | Lifecycle boundary | +| --- | --- | --- | +| lifecycle-managed workload cluster | Created through supported cluster workflows. | manages the supported Kubernetes lifecycle for the selected model. | +| Third-party cluster | Onboarded through import or register workflows. | provides central governance and operations within documented prerequisites and caveats. The external cluster owner, distribution, or provider usually owns Kubernetes lifecycle, node lifecycle, and provider infrastructure lifecycle. | + +`Managed Cluster` is the current UI and navigation label for third-party cluster onboarding and management areas. For product-model planning, use `Third-party cluster`. + +`Import cluster` and `Register cluster` are onboarding methods for third-party clusters: + +| 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. | + +After onboarding, expected day-2 management is treated as the same at the Overview level. Provider and workflow-specific caveats still apply. + +## Third-Party Cluster Capability Boundaries + + can provide these entry capabilities for third-party clusters when prerequisites are met: + +- Resource visibility and centralized governance. +- Project and namespace association. +- Application operations. +- Operator and Cluster Plugin installation, subject to Extension compatibility. +- Observability integration, subject to installed components, network paths, credentials, and provider caveats. + +Third-party cluster onboarding does not mean that manages every Kubernetes version, provider operation, node operation, certificate, control-plane metric, audit source, ingress path, storage class, or Extension image on every third-party cluster. + +For 4.3, third-party Kubernetes clusters are accepted for onboarding only in the range `>=1.19.0 <1.35.0`. Clusters outside that range are blocked from onboarding. This is an onboarding gate, not a complete product validation matrix for every Kubernetes version, provider, operation, or Extension. + +For the exact matrix and upgrade relationship, see [Kubernetes Support Matrix](./kubernetes-support-matrix.mdx) and [Version and Lifecycle](./version-and-lifecycle.mdx). + +## Provider And Workflow Caveats + +Use the following caveat categories to decide which provider or workflow documentation to check for provider-specific details. + +| Caveat category | What to check | Continue with | +| --- | --- | --- | +| Kubernetes lifecycle | Whether Kubernetes installation or upgrade is managed by or by the external owner. | [Clusters Overview](../configure/clusters/overview.mdx) | +| Node lifecycle | Whether adding, deleting, or scaling nodes is supported from the platform UI for the selected model. | [Node Management](../configure/clusters/nodes/overview.mdx) | +| Connectivity | Whether the `global` cluster and target cluster can reach the required endpoints and whether a platform URL annotation is needed. | [Managed Cluster Network Configuration](../configure/clusters/managed/how-to/annotate-platform-url.mdx) | +| Certificates | Which certificates are visible or rotated by the platform for the selected workflow. | Provider or onboarding workflow docs under [Import Clusters](../configure/clusters/managed/import/overview.mdx) | +| Audit and metrics | Whether audit data and control-plane metrics are available from the target environment. | [Audit](../security/audit/intro.mdx) and provider workflow docs | +| Ingress and storage | Whether post-import initialization is required for ingress, load balancing, or storage classes. | [Public Cloud Cluster Initialization](../configure/clusters/managed/cloud-init/index.mdx) | +| Extension compatibility | Whether the exact Operator or Cluster Plugin version supports the target version and cluster model. | [Core and Extensions](./core-and-extensions.mdx) | + +If you need to choose what to read next, see [Learn More](./learn-more.mdx). diff --git a/docs/en/overview/core-and-extensions.mdx b/docs/en/overview/core-and-extensions.mdx new file mode 100644 index 000000000..a77db4c46 --- /dev/null +++ b/docs/en/overview/core-and-extensions.mdx @@ -0,0 +1,75 @@ +--- +weight: 60 +--- + +# Core and Extensions + + capabilities are delivered through Core and separately installed Extensions. Understanding this boundary helps you plan installation, upgrade, compatibility checks, and troubleshooting. + +## Core + + Core is installed first and deploys the `global` cluster. It provides the platform management plane for web console access, platform API and CLI access, cluster management, project and namespace management, users and RBAC, Extension management frameworks, and core communication paths such as Cluster Proxy. + +Core capabilities are installed with Core or are part of the platform management plane deployed with the `global` cluster. Capabilities that require a separate installation flow, Operator, Cluster Plugin, or separate product are not default Core functionality. + +For installation scope, see [Install Overview](../install/overview.mdx). + +## Extension Types + +Extension is the umbrella term for the two main extension mechanisms in : + +| Extension type | Technology | Where installation is executed | Start here | +| --- | --- | --- | --- | +| Operator | Operator Lifecycle Manager (OLM), OperatorHub, `CatalogSource`, `Subscription`, `InstallPlan`, and `ClusterServiceVersion`. | In the target cluster where the Operator runs. | [Operator](../extend/operator.mdx) | +| Cluster Plugin | `ModulePlugin`, `ModuleConfig`, and `ModuleInfo` custom resources. | YAML-based installation creates `ModuleInfo` in the `global` cluster; the plugin target depends on affinity and configuration. | [Cluster Plugin](../extend/cluster_plugin.mdx) | + +OperatorHub is the interface for discovering, installing, upgrading, and managing Operators. Cluster Plugins are published to the `global` cluster and installed through the platform according to each plugin's configuration and affinity. + +For the Extension section, see [Extend](../extend/index.mdx). + +## Lifecycle Types + +Operators and Cluster Plugins use the same lifecycle model: + +| Lifecycle | Meaning | Upgrade behavior | +| --- | --- | --- | +| `Core` | Follows the Core release and cluster Distribution Version. | Updated by upgrading the cluster. Standalone upgrade is not supported. | +| `Aligned` | Follows the release stream but can be updated independently when a compatible version is published. | Can be upgraded independently when the exact version is compatible. | +| `Agnostic` | Released independently from . | Can be upgraded independently when the exact version is compatible. | + +Cluster Plugins expose this model through the `cpaas.io/lifecycle-type` label. For Operators, check compatibility through the Customer Portal metadata, Extension documentation, or release guidance instead of expecting every lifecycle label to be visible in the product interface. + +For Cluster Plugin details, see [Cluster Plugin](../extend/cluster_plugin.mdx). + +## Compatibility Source + +For a specific Operator or Cluster Plugin version, use the Customer Portal `ACP compatible versions` field as the compatibility authority. If the exact version lists 4.3, that version supports 4.3. + +Use product documentation for each Extension to understand capabilities, installation steps, upgrade steps, limitations, and known issues. Release notes are useful for version changes, but they are not the primary compatibility source for every specific Extension version. The Kubernetes support matrix explains Kubernetes compatibility and the default Extend baseline; it is not a complete compatibility matrix for every Operator or Cluster Plugin. + +For package handling, see [Upload Packages](../extend/upload_package.mdx) and [Download Packages](../extend/download_package.mdx). + +## Default Extend Baseline + +For 4.3, product validation for the default Extend baseline covers: + +- Installing and using Operators. +- Installing and using Cluster Plugins. +- ClickHouse-based logging. +- VictoriaMetrics-based monitoring. + +This baseline does not mean every specific Operator or Cluster Plugin is validated for every Kubernetes version, provider, third-party cluster, CPU architecture, runtime, or disconnected scenario. Check the exact Extension version and its own documentation before installation or upgrade. + +## Capability Boundaries + +Use these boundaries when planning installation, upgrade, and operations: + +| Capability area | How to read it | +| --- | --- | +| Registry | The platform can provide registry entry points and registry-related workflows. Registry plugins, backends, backup, and recovery have their own installation and operational boundaries. | +| Observability | Centralized observability depends on installed monitoring, logging, event, tracing, or inspection components. Provider and connectivity caveats apply to third-party clusters. | +| Audit | Audit uses platform audit views and depends on logging service components. Third-party provider audit data is not universally available. | +| Security and compliance | Authentication, RBAC, NetworkPolicy, API filtering, compliance features, and security products have separate component boundaries and installation requirements. | +| Separate products and independently installed capabilities | Service Mesh, AI, Hyperflux, Data Services, Cost Management, DevOps, Container Security, Compliance Service, GitOps, Logging Service, Immutable Infrastructure, Hosted Control Plane, and Cluster Authentication are not default Core functionality. Check the corresponding documentation before planning installation, upgrade, compatibility, or limitations. | + +For a task-oriented route map, see [Learn More](./learn-more.mdx). diff --git a/docs/en/overview/glossary.mdx b/docs/en/overview/glossary.mdx index 4ed270986..87670016d 100644 --- a/docs/en/overview/glossary.mdx +++ b/docs/en/overview/glossary.mdx @@ -1,76 +1,92 @@ --- -weight: 12 +weight: 110 queries: - acp glossary - alauda container platform terminology - acp cluster model terms - global cluster workload cluster hosted control plane - - immutable infrastructure immutable os managed cluster + - immutable infrastructure immutable os third-party cluster --- # Glossary -This glossary defines canonical platform-wide terms used across documentation. It focuses on concepts that appear in multiple sections of the product. Terms that apply only to a single workflow or subsystem should remain documented in their local pages. +Use this glossary to interpret platform-wide terms in . For workflow-specific terms, use the corresponding workflow or component documentation. -## Platform and Cluster Terms +## Platform And Cluster Terms | Term | Definition | Related doc | -| ---- | ---------- | ----------- | -| Global Cluster | The centralized management and control hub of . In the platform's hub-and-spoke architecture, it provides platform-wide services such as authentication, policy management, cluster lifecycle operations, and observability. | [Architecture](./architecture.mdx) | -| Workload Cluster | A Kubernetes-based environment managed by the `global` cluster. A workload cluster runs isolated application workloads and inherits governance and configuration from the central control plane. | [Architecture](./architecture.mdx) | -| Platform-Provisioned Infrastructure | A cluster management model in which the platform provisions both machines and node operating systems, and manages the full cluster lifecycle. In this model, all nodes use an immutable operating system. | [Clusters Overview](../configure/clusters/overview.mdx) | -| User-Provisioned Infrastructure | A cluster management model in which users provide pre-provisioned physical or virtual machines. The platform manages Kubernetes on those nodes, while node operating system management remains under user control. | [Clusters Overview](../configure/clusters/overview.mdx) | -| Hosted Control Plane (HCP) | A deployment model in which each cluster has its own dedicated control plane, while multiple control planes are hosted as workloads on a dedicated management cluster. This model separates the control plane from worker nodes to reduce resource consumption and improve multi-cluster scalability. | [About Hosted Control Plane](../configure/clusters/about-hcp.mdx) | -| Managed Cluster | An existing cluster brought under the platform for centralized governance and operations. In ACP, managed clusters include existing standard Kubernetes clusters and selected public cloud clusters that are onboarded through import or registration workflows. | [Managed Clusters Overview](../configure/clusters/managed/overview.mdx) | -| Immutable OS | An immutable operating system used for platform-managed nodes in platform-provisioned environments. Node state is kept consistent and recoverable by treating the operating system layer as read-only and centrally managed. | [Clusters Overview](../configure/clusters/overview.mdx) | -| Immutable Infrastructure | A cluster provisioning and operating model in which node configurations are baked into images and remain unchanged after deployment. Cluster upgrades and configuration changes are applied by replacing nodes with new images. | [About Immutable Infrastructure](../configure/clusters/immutable-infra.mdx) | -| Project | A platform governance unit that isolates resources and personnel for a tenant or team. A project can span multiple associated clusters and acts as the management boundary for quotas, policies, and namespace ownership. | [Create Project](../security/project/functions/create_project.mdx) | -| Namespace | A Kubernetes namespace managed directly or indirectly by the platform. In ACP, a namespace can be created within or imported into a project so that it inherits project-level governance and visibility. | [Importing Namespaces](../developer/building_application/namespace/import_namespace.mdx) | -| Control Plane | The Kubernetes management layer that runs core cluster components such as the API server, scheduler, and controller manager. | [Architecture](./architecture.mdx) | -| Control Plane Node | A node that runs Kubernetes control plane components used for cluster management. Use this term instead of outdated alternatives such as "master node". | [Architecture](./architecture.mdx) | -| Worker Node | A node that runs application workloads and supporting platform components. Use this term instead of outdated alternatives such as "slave node". | [Architecture](./architecture.mdx) | +| --- | --- | --- | +| Core | The platform management foundation installed first. It deploys the `global` cluster and provides core management-plane capabilities such as web console access, platform APIs, users and RBAC, cluster management, project governance, and Extension management frameworks. | [Core and Extensions](./core-and-extensions.mdx) | +| `global` cluster | The central management cluster deployed by Core. It hosts platform management services and coordinates cluster, project, user, Extension, and platform operations. | [Platform Model](./platform-model.mdx) | +| Workload cluster | A Kubernetes cluster that runs application workloads under governance from the `global` cluster. Depending on the selected model, can create and lifecycle-manage workload clusters. | [Platform Model](./platform-model.mdx) | +| Third-party cluster | A Kubernetes environment whose Kubernetes distribution and lifecycle are provided or managed outside . can onboard third-party clusters for centralized governance and operations within documented prerequisites and caveats. | [Cluster Management Models](./cluster-management-models.mdx) | +| Managed Cluster | The current UI/navigation label for the interface that manages onboarded third-party clusters. It is not a conceptual model parallel to `third-party cluster`. | [Managed Clusters Overview](../configure/clusters/managed/overview.mdx) | +| Installer-Provisioned Infrastructure (IPI) | An infrastructure responsibility model where the platform provisions machines, manages node operating systems through Immutable OS, and manages the supported Kubernetes lifecycle. | [Cluster Management Models](./cluster-management-models.mdx) | +| User-Provisioned Infrastructure (UPI) | An infrastructure responsibility model where users prepare physical or virtual machines and retain node OS responsibility, while the platform installs and manages Kubernetes on those nodes. | [Cluster Management Models](./cluster-management-models.mdx) | +| Hosted Control Plane (HCP) | A control-plane topology where each hosted cluster has its own control plane, and multiple hosted control planes run as workloads on a management cluster. In , HCP is implemented through Kamaji (`TenantControlPlane`). In 4.3, HCP is Technology Preview and not production-supported. | [Cluster Management Models](./cluster-management-models.mdx) | +| Immutable Infrastructure | A provisioning and operating model where node configurations are baked into images and changes are applied by replacing nodes with new images. | [About Immutable Infrastructure](../configure/clusters/immutable-infra.mdx) | +| Immutable OS | An immutable operating system used by installer-provisioned nodes. Node state is kept consistent by treating the operating system layer as centrally managed and replaced through image-based updates. | [About Immutable Infrastructure](../configure/clusters/immutable-infra.mdx) | +| Project | A platform governance unit for a tenant, team, or business system. A project can span multiple associated clusters and acts as a boundary for quotas, policies, users, and namespace ownership. | [Project Introduction](../security/project/intro.mdx) | +| Namespace | A Kubernetes namespace managed directly or indirectly by the platform. In , a namespace can belong to a project and inherit project-level governance. | [Namespace Management](../developer/building_application/namespace/index.mdx) | +| Control plane | The Kubernetes management layer that runs components such as the API server, scheduler, controller manager, and etcd. | [Architecture](./architecture.mdx) | +| Control plane node | A node that runs Kubernetes control plane components for a cluster using a dedicated control-plane topology. | [Node Management](../configure/clusters/nodes/overview.mdx) | +| Worker node | A node that runs application workloads and cluster-local supporting components. | [Node Management](../configure/clusters/nodes/overview.mdx) | -## Identity and Access Terms +## Extension And Packaging Terms | Term | Definition | Related doc | -| ---- | ---------- | ----------- | -| Identity Provider (IdP) | An external identity system that authenticates users for the platform, such as LDAP, Active Directory, or an OpenID Connect provider. | [Accessing the Web Console](../ui/web_console/access.mdx) | -| OpenID Connect (OIDC) | An identity layer built on OAuth 2.0 that ACP uses in several authentication and authorization scenarios. | [Disabling the PKCE Plain Method](../security/platform_security_configurations/disable_pkce_plain_method.mdx) | +| --- | --- | --- | +| Extension | The umbrella term for Operator and Cluster Plugin based mechanisms that add capabilities to environments. | [Core and Extensions](./core-and-extensions.mdx) | +| Operator | An Extension mechanism built on Kubernetes custom resources and controllers. In , Operators are managed through Operator Lifecycle Manager and OperatorHub. | [Operator](../extend/operator.mdx) | +| Operator Lifecycle Manager (OLM) | The operator management framework that handles Operator installation, upgrades, dependency resolution, and related resources such as `CatalogSource`, `Subscription`, `InstallPlan`, and `ClusterServiceVersion`. | [Operator](../extend/operator.mdx) | +| OperatorHub | The platform interface for discovering, installing, upgrading, and managing Operators through OLM. | [Operator](../extend/operator.mdx) | +| Cluster Plugin | The platform Extension mechanism for chart-based plugins managed through `ModulePlugin`, `ModuleConfig`, and `ModuleInfo` custom resources. | [Cluster Plugin](../extend/cluster_plugin.mdx) | +| `Core` lifecycle | Extension lifecycle type that follows the Core release and cluster Distribution Version. Standalone upgrade is not supported. | [Core and Extensions](./core-and-extensions.mdx) | +| `Aligned` lifecycle | Extension lifecycle type that follows the release stream but can be upgraded independently when a compatible version is published. | [Core and Extensions](./core-and-extensions.mdx) | +| `Agnostic` lifecycle | Extension lifecycle type released independently from and upgraded independently when a compatible version is published. | [Core and Extensions](./core-and-extensions.mdx) | +| Customer Portal compatible versions | The compatibility field in the Customer Portal that indicates which versions a specific Operator or Cluster Plugin version supports. | [Core and Extensions](./core-and-extensions.mdx) | -## Extension and Packaging Terms +## Identity, Access, And Security Terms | Term | Definition | Related doc | -| ---- | ---------- | ----------- | -| Operator | An extension mechanism built on Kubernetes custom resources and controllers that automates lifecycle management for complex applications or services. In , Operators are managed through Operator Lifecycle Manager. | [Operator](../extend/operator.mdx) | -| Operator Lifecycle Manager (OLM) | The operator management framework that handles Operator installation, upgrades, channel subscriptions, dependency resolution, and related custom resources such as `CatalogSource`, `Subscription`, and `InstallPlan`. | [Operator](../extend/operator.mdx) | -| OperatorHub | The platform interface for discovering, installing, upgrading, and managing Operators through OLM. | [Operator](../extend/operator.mdx) | -| Cluster Plugin | The platform's extension mechanism for chart-based plugins. Cluster plugins are managed through the `ModulePlugin`, `ModuleConfig`, and `ModuleInfo` custom resources. | [Cluster Plugin](../extend/cluster_plugin.mdx) | +| --- | --- | --- | +| Identity Provider (IdP) | An external identity system used for platform account authentication, such as LDAP or OIDC. | [Identity Provider Introduction](../security/users_and_roles/idp/intro.mdx) | +| LDAP | A directory access protocol supported by the platform for enterprise user authentication. Active Directory can be integrated through LDAP. | [LDAP Management](../security/users_and_roles/idp/functions/ldap_manage.mdx) | +| OpenID Connect (OIDC) | An identity layer based on OAuth 2.0 that the platform supports for third-party user authentication. | [OIDC Management](../security/users_and_roles/idp/functions/oidc_manage.mdx) | +| Platform Roles | System-provided role templates used by the platform after the RBAC refactor. They are bound to users or groups and convert to Kubernetes permissions. | [Roles Introduction](../security/users_and_roles/role/intro.mdx) | +| Kubernetes Roles | Native Kubernetes `Role` and `ClusterRole` objects used for fine-grained permissions. They are bound with `RoleBinding` or `ClusterRoleBinding`. | [Roles Introduction](../security/users_and_roles/role/intro.mdx) | +| Audit | Platform operation records for users and system actions. Audit views depend on logging service components. | [Audit Introduction](../security/audit/intro.mdx) | +| NetworkPolicy | A Kubernetes resource for namespace-scoped network traffic policy. Enforcement depends on the selected CNI. | [NetworkPolicy](../networking/security/network_policy.mdx) | +| API Refiner | API filtering capability that can filter or mask Kubernetes API responses based on user permissions, project, cluster, and namespace. | [API Security](../security/security_and_compliance/api_security/intro.mdx) | +| Compliance features | Kyverno-based features for policy enforcement, violation monitoring, and reporting. Use the Compliance Service documentation for scope and prerequisites. | [Compliance Service](../security/security_and_compliance/compliance_service.mdx) | -## Networking and Access Terms +## Networking And Access Terms | Term | Definition | Related doc | -| ---- | ---------- | ----------- | -| Ingress | A Kubernetes resource that exposes HTTP and HTTPS routes from outside the cluster to internal services. ACP uses Ingress as one of its main north-south traffic entry models. | [Configure Ingresses](../configure/networking/functions/configure_ingress.mdx) | -| Gateway API | The Kubernetes networking API family that defines role-oriented resources for advanced L4 and L7 routing. In ACP, Gateway API is positioned as a next-generation traffic management model alongside Service and Ingress. | [Networking Overview](../networking/overview.mdx) | -| Service | In Kubernetes, a Service is a method for exposing a network application that runs as one or more Pods in a cluster. In ACP, Service is a core service-discovery and traffic-exposure primitive, including `ClusterIP`, `NodePort`, and `LoadBalancer` types. | [Configure Services](../configure/networking/functions/configure_service.mdx) | -| LoadBalancer | A Service type that exposes a Service through an external load balancer. This usually requires either a cloud-provider integration or a separately provided load-balancing component. | [Configure Services](../configure/networking/functions/configure_service.mdx) | -| Platform Access Address | The external address used to access platform services such as the web console and platform APIs. It can be the same as the Cluster Endpoint or a separate address for external access scenarios. | [Install](../install/installing.mdx) | -| Cluster Endpoint | The address used by cluster components and administrators to reach the target cluster control plane endpoint. It is the primary control-plane access entry during installation and later operations. | [Install](../install/installing.mdx) | -| Self-built VIP | The built-in virtual IP option used when an external load balancer is not provided for the Cluster Endpoint. | [Install](../install/installing.mdx) | +| --- | --- | --- | +| Platform Access Address | The external address used to access platform services such as the web console and platform APIs. It can be the same as the Cluster Endpoint or a separate address for external access scenarios. | [Installing](../install/installing.mdx) | +| Cluster Endpoint | The address used by cluster components and administrators to reach the target Kubernetes control plane endpoint. | [Installing](../install/installing.mdx) | +| LoadBalancer | A Kubernetes Service type that exposes a Service through an external load balancer. In the platform, load-balancing can also involve external devices, VIPs, or provider-specific services. | [Configure Services](../configure/networking/functions/configure_service.mdx) | +| Self-built VIP | The built-in virtual IP option used when an external load balancer is not provided for the Cluster Endpoint. | [Prerequisites](../install/prepare/prerequisites.mdx) | +| Cluster Proxy | A platform communication capability used to connect the `global` cluster and managed clusters for supported management operations. | [Architecture](./architecture.mdx) | +| Import cluster | An onboarding method where the `global` cluster connects to the target third-party cluster API server with supplied address, CA, and credentials. | [Import Clusters](../configure/clusters/managed/import/overview.mdx) | +| Register cluster | An onboarding method where a reverse proxy service in the target third-party cluster initiates registration and establishes a tunnel to the platform. | [Register Cluster](../configure/clusters/managed/register.mdx) | -## Disaster Recovery and Upgrade Terms +## Disaster Recovery, Backup, And Upgrade Terms | Term | Definition | Related doc | -| ---- | ---------- | ----------- | -| Global Cluster Disaster Recovery | The disaster recovery model for the `global` cluster in which a primary global cluster and a standby global cluster are kept ready for failover through etcd data synchronization and coordinated operational procedures. | [Global Cluster Disaster Recovery](../install/global_dr.mdx) | -| Cluster Version Operator (CVO) | The operator-based upgrade workflow and controller used to coordinate target version, preflight status, and execution progress for `global` and workload cluster upgrades. | [Upgrade Overview](../upgrade/overview.mdx) | +| --- | --- | --- | +| Global Cluster Disaster Recovery | A Primary and Standby `global` cluster DR mechanism based on `global` cluster etcd synchronization and DNS/VIP failover. It protects the `global` control-plane scenario only within documented boundaries. | [Availability and Recovery](./availability-and-recovery.mdx) | +| etcd backup and restore | Backup and restore path for Kubernetes control-plane resource state stored in etcd. | [etcd Backup and Restore](../configure/backup/etcd.mdx) | +| Application backup and restore | Velero-based backup and restore path for application resources and persistent volumes, delivered through Data Backup components. | [Backup Overview](../configure/backup/overview.mdx) | +| Cluster Version Operator (CVO) | The upgrade workflow and controller used to coordinate target versions, preflight checks, status, and execution progress for `global` and workload cluster upgrades. | [Upgrade Overview](../upgrade/overview.mdx) | +| ClusterVersionShadow | A custom resource used by the CVO-based upgrade workflow to expose desired version, status, preflight results, stages, and upgrade history. | [Upgrade Overview](../upgrade/overview.mdx) | +| Distribution Version | The cluster distribution version used to coordinate upgrade gating and version alignment for `global` and workload cluster upgrades. | [Upgrade Overview](../upgrade/overview.mdx) | +| Preflight | The set of checks run before upgrade execution to reduce upgrade risk. | [Pre-Upgrade](../upgrade/pre-upgrade.mdx) | -## Usage Notes +## Terminology Conventions -- Use this page as the canonical source for ACP-wide terms that appear across multiple documentation sections. -- Keep page-local `## Terminology` sections for workflow-specific or subsystem-specific terms that are not reused broadly across the product. -- The **Term** column uses a normalized display style for readability. -- Keep official feature names, protocol names, UI labels, and API-facing names in their official capitalization, such as `OperatorHub`, `Platform Access Address`, `ClusterIP`, `Self-built VIP`, and `OpenID Connect (OIDC)`. -- Favor product concepts, platform models, and high-value cross-section entry terms over generic engineering vocabulary. -- Expand an acronym on first mention when needed, then use the acronym consistently. -- When a term is already defined by Kubernetes or OpenShift, use the upstream meaning first and add ACP-specific context only when needed. +- The `global` cluster is the platform management cluster. +- `Third-party cluster` refers to externally provided Kubernetes environments. `Managed Cluster` is the current UI or navigation label. +- UI labels, API resource names, protocol names, and feature names keep their official capitalization. +- Acronyms are expanded on first mention when the surrounding page needs the expansion. diff --git a/docs/en/overview/introduction.mdx b/docs/en/overview/introduction.mdx new file mode 100644 index 000000000..425bd5a84 --- /dev/null +++ b/docs/en/overview/introduction.mdx @@ -0,0 +1,38 @@ +--- +weight: 20 +--- + +# Introduction + + () is a Kubernetes-based platform for building, deploying, operating, and governing cloud-native applications across private cloud, data center, hybrid cloud, multi-cloud, and edge environments. + + keeps Kubernetes APIs and workload primitives at the center of the platform, then adds enterprise capabilities for cluster management, project governance, application delivery, extension management, observability, security, upgrade planning, and recovery. + +## What the Platform Provides + +| Area | What it helps you do | Continue with | +| --- | --- | --- | +| Platform management | Install Core, access the web console and APIs, and manage platform-wide services from the `global` cluster. | [Architecture](./architecture.mdx) | +| Cluster operations | Create lifecycle-managed workload clusters or onboard third-party Kubernetes environments for centralized governance. | [Cluster Management Models](./cluster-management-models.mdx) | +| Projects and namespaces | Understand how projects, namespaces, users, quotas, and associated clusters form the platform governance model. | [Platform Model](./platform-model.mdx) | +| Application delivery | Create and operate applications from images, YAML, charts, source code, and Kubernetes workload resources. | [Developer Overview](../developer/overview.mdx) | +| Extensions | Add capabilities through Operators and Cluster Plugins, and check version compatibility before installation or upgrade. | [Core and Extensions](./core-and-extensions.mdx) | +| Availability and recovery | Plan deployment topology, high availability, Global Cluster Disaster Recovery, and backup or restore paths. | [Availability and Recovery](./availability-and-recovery.mdx) | +| Version planning | Understand Kubernetes compatibility, third-party cluster onboarding range, runtime baseline, and lifecycle boundaries. | [Version and Lifecycle](./version-and-lifecycle.mdx) | +| Security and access | Configure LDAP or OIDC identity providers, Kubernetes RBAC-based authorization, audit, network policy, API filtering, compliance features, and security product integrations. | [Security](../security/index.mdx) | + +## Relationship To Kubernetes + + is built on Kubernetes. Users still work with Kubernetes resources such as clusters, namespaces, workloads, Services, Ingresses, NetworkPolicies, custom resources, and RBAC objects. adds a management plane that helps platform teams apply governance, lifecycle management, observability, and operational workflows across multiple Kubernetes environments. + +Some capabilities are included with Core. Other capabilities are provided through separately installed Extensions, such as Operators and Cluster Plugins, or through separate products. Before planning or using those capabilities, check the corresponding documentation for installation, upgrade, compatibility, and limitations. + +## Reader Path + +If you are new to , read these pages first: + +1. [Architecture](./architecture.mdx) to understand the hub-and-spoke model. +2. [Platform Model](./platform-model.mdx) to understand the `global` cluster, workload clusters, third-party clusters, projects, and namespaces. +3. [Cluster Management Models](./cluster-management-models.mdx) to understand infrastructure responsibility, control-plane topology, and third-party onboarding. +4. [Core and Extensions](./core-and-extensions.mdx) to understand which capabilities belong to Core and which require an Extension. +5. [Learn More](./learn-more.mdx) to choose the next documentation path for installation, cluster operations, application delivery, upgrade planning, recovery, security, API, or CLI tasks. diff --git a/docs/en/overview/kubernetes-support-matrix.mdx b/docs/en/overview/kubernetes-support-matrix.mdx index 952205975..71f6c77d7 100644 --- a/docs/en/overview/kubernetes-support-matrix.mdx +++ b/docs/en/overview/kubernetes-support-matrix.mdx @@ -1,19 +1,20 @@ --- -weight: 11 -title: Kubernetes Support Matrix +weight: 90 --- # Kubernetes Support Matrix -This document provides the Kubernetes version support matrix for . This information is critical when creating clusters, upgrading , and managing third-party clusters. +Use the Kubernetes support matrix to confirm Kubernetes version relationships for releases and to distinguish cluster creation, upgrade compatibility, and third-party cluster onboarding boundaries. -## Overview +For the conceptual lifecycle guidance, see [Version and Lifecycle](./version-and-lifecycle.mdx). - supports multiple Kubernetes versions across different releases. Understanding the supported versions is essential for: +## How To Read This Page -- **Creating clusters** – Determine which Kubernetes versions can be used when provisioning new clusters -- **Upgrading ** – Ensure all workload clusters meet the documented compatible-version requirements before upgrading the global cluster -- **Managing third-party clusters** – Verify that public cloud or CNCF-compliant Kubernetes clusters are within the supported management range +| Term | Meaning | +| --- | --- | +| Supported for cluster creation | The Kubernetes version that can be used when creates a new platform-managed cluster for that release. | +| Compatible Versions | The Kubernetes versions that workload clusters can run before the `global` cluster is upgraded to that release. | +| Third-party cluster accepted onboarding range | The Kubernetes version range accepted for onboarding third-party clusters. This is an onboarding gate, not proof of complete validation for every version, provider, capability, operation, or Extension. | ## Version Support Matrix \{#version-support-matrix} @@ -22,38 +23,60 @@ The following table shows the Kubernetes version support for each minor versions and does not distinguish between patch versions. Patch versions only include bug fixes and security updates, so the Kubernetes minor versions remain consistent across all patch versions within the same minor release. -**Starting from 4.1**, each release supports only **one Kubernetes version** for cluster creation. -This ensures consistency and simplifies the upgrade path for new clusters. +Starting from 4.1, each release supports only one Kubernetes version for cluster creation. This keeps new cluster creation consistent and simplifies upgrade planning. ::: -| Version | Supported for Cluster Creation | Compatible Versions | +| Version | Supported for cluster creation | Compatible Versions | | --- | --- | --- | | 4.3 | 1.34 | 1.34, 1.33, 1.32, 1.31 | | 4.2 | 1.33 | 1.33, 1.32, 1.31, 1.30 | | 4.1 | 1.32 | 1.32, 1.31, 1.30, 1.29 | | 4.0 | 1.31, 1.30, 1.29, 1.28 | 1.31, 1.30, 1.29, 1.28 | -## ACP 4.3 Notes +## 4.3 Notes -- ACP 4.3 adds support for Kubernetes 1.34 for platform-managed cluster scenarios. -- For upgrades to ACP 4.3, the workload-cluster compatible versions are 1.34, 1.33, 1.32, and 1.31. -- This means environments upgrading from ACP 4.0 to ACP 4.3 can keep workload clusters on Kubernetes 1.31 through 1.34 while upgrading the global cluster. +- 4.3 supports Kubernetes 1.34 for platform-managed cluster creation. +- Before upgrading the `global` cluster to 4.3, workload clusters must remain within Kubernetes 1.34, 1.33, 1.32, and 1.31. +- Environments upgrading from 4.0 to 4.3 can keep workload clusters on Kubernetes 1.31 through 1.34 while upgrading the `global` cluster, subject to the documented upgrade procedure. -## Third-Party Cluster Management Range +For upgrade planning, see [Upgrade Overview](../upgrade/overview.mdx) and [Pre-Upgrade](../upgrade/pre-upgrade.mdx). -- For third-party clusters, ACP 4.3 accepts Kubernetes versions in the range `>=1.19.0 <1.35.0`. -- This management range is separate from the Compatible Versions column, which is the authoritative prerequisite for upgrading the ACP global cluster. -- 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. +## Third-Party Cluster Accepted Onboarding Range + +For 4.3, third-party Kubernetes clusters are accepted for onboarding only in the range `>=1.19.0 <1.35.0`. Clusters outside that range are blocked from onboarding. + +This range is separate from the Compatible Versions column. Compatible Versions determine whether workload clusters satisfy the prerequisite for upgrading the `global` cluster. The third-party onboarding range determines whether a third-party Kubernetes cluster can be onboarded. + +This range also does not mean every Kubernetes version, provider, operation, capability, or Extension in the range has complete product validation. + +When onboarding third-party clusters, also check: + +- Cluster family or provider prerequisites. +- Connectivity between the `global` cluster and the target cluster. +- Credentials and RBAC scope. +- Required platform components. +- Provider and workflow caveats. +- Extension compatibility for each exact Operator or Cluster Plugin version. + +For model boundaries, see [Cluster Management Models](./cluster-management-models.mdx). + +## Extend Baseline + +For 4.3, product validation for the default Extend baseline covers these capability areas: + +- Installing and using Operators. +- Installing and using Cluster Plugins. +- ClickHouse-based logging. +- VictoriaMetrics-based monitoring. + +This baseline does not mean every specific Operator or Cluster Plugin is validated for every cluster model or every third-party cluster scenario. + +For a specific Operator or Cluster Plugin version, use the Customer Portal `ACP compatible versions` field and the corresponding Extension documentation. For more information, see [Core and Extensions](./core-and-extensions.mdx). ## Upgrade Requirements -For 4.3 and later, workload clusters only need to remain within the documented compatible version range before upgrading the global cluster. For ACP 4.3, this means Kubernetes 1.31 through 1.34. +For 4.3 and later, workload clusters only need to remain within the documented compatible version range before upgrading the `global` cluster. + +In 4.2 and earlier, all workload clusters must be upgraded to the latest Kubernetes version in the compatible versions list before upgrading the `global` cluster. -In 4.2 and earlier, **all** workload clusters must be upgraded to the **latest** Kubernetes version in the compatible versions list **before** upgrading the global cluster. +For upgrade procedures, see [Upgrade](../upgrade/index.mdx). diff --git a/docs/en/overview/learn-more.mdx b/docs/en/overview/learn-more.mdx new file mode 100644 index 000000000..4780ec17d --- /dev/null +++ b/docs/en/overview/learn-more.mdx @@ -0,0 +1,99 @@ +--- +weight: 120 +--- + +# Learn More + +Choose the next documentation path for installation, cluster operations, application delivery, upgrade planning, availability and recovery, security, API, or CLI tasks. + +## Understand The Platform + +| Goal | Start here | +| --- | --- | +| Understand what is and how it relates to Kubernetes. | [Introduction](./introduction.mdx) | +| Understand the hub-and-spoke architecture. | [Architecture](./architecture.mdx) | +| Understand the `global` cluster, workload clusters, third-party clusters, HCP, projects, and namespaces. | [Platform Model](./platform-model.mdx) | +| Understand the three-axis cluster model and responsibility boundaries. | [Cluster Management Models](./cluster-management-models.mdx) | +| Find platform-wide terms. | [Glossary](./glossary.mdx) | + +## Install And Plan + +| Goal | Start here | +| --- | --- | +| Understand what Core installation deploys. | [Install Overview](../install/overview.mdx) | +| Choose Multi-Cluster, Single Cluster, or Single Node. | [Plan](../install/planning.mdx) | +| Prepare resource, network, OS, and load-balancing prerequisites. | [Prerequisites](../install/prepare/prerequisites.mdx) | +| Download the Core Package and choose package architecture. | [Download](../install/prepare/download.mdx) | +| Install Core. | [Installing](../install/installing.mdx) | +| Validate a completed installation. | [Validation](../install/validation.mdx) | +| Decide whether to plan Global Cluster Disaster Recovery. | [Global Cluster Disaster Recovery](../install/global_dr.mdx) | + +## Manage Clusters + +| Goal | Start here | +| --- | --- | +| Create lifecycle-managed workload clusters. | [Clusters Overview](../configure/clusters/overview.mdx) | +| Create on-premises workload clusters. | [Creating an On-Premise Cluster](../configure/clusters/on-premises.mdx) | +| Use Immutable Infrastructure. | [About Immutable Infrastructure](../configure/clusters/immutable-infra.mdx) | +| Evaluate HCP for a non-production 4.3 scenario. | [About Hosted Control Plane](../configure/clusters/about-hcp.mdx) | +| Onboard existing third-party Kubernetes environments by import. | [Import Clusters](../configure/clusters/managed/import/overview.mdx) | +| Onboard existing third-party Kubernetes environments by register. | [Register Cluster](../configure/clusters/managed/register.mdx) | +| Access a cluster with KubeConfig. | [Access a Cluster with KubeConfig](../configure/clusters/how-to/access-cluster-with-kubeconfig.mdx) | + +## Build And Operate Applications + +| Goal | Start here | +| --- | --- | +| Understand developer workflows. | [Developer Overview](../developer/overview.mdx) | +| Create applications from images, charts, YAML, source code, or Operator-backed catalogs. | [Create Applications](../developer/building_application/create_applications/index.mdx) | +| Manage Kubernetes workloads. | [Application Workloads](../developer/building_application/application_workloads/index.mdx) | +| Manage namespaces. | [Namespace Management](../developer/building_application/namespace/index.mdx) | +| View application logs, events, and monitoring dashboards. | [Application Observability](../developer/building_application/application_observability/index.mdx) | +| Work with container images and registries. | [Images](../developer/images/overview.mdx) and [Registry](../developer/registry/intro.mdx) | + +## Install And Use Extensions + +| Goal | Start here | +| --- | --- | +| Understand Core and Extension boundaries. | [Core and Extensions](./core-and-extensions.mdx) | +| Understand the Extension system. | [Extend Overview](../extend/overview.mdx) | +| Install and manage Operators. | [Operator](../extend/operator.mdx) | +| Install and manage Cluster Plugins. | [Cluster Plugin](../extend/cluster_plugin.mdx) | +| Upload Extension packages. | [Upload Packages](../extend/upload_package.mdx) | +| Check version compatibility for a specific Extension. | Use the Customer Portal `ACP compatible versions` field, then read the Extension documentation. | + +## Plan Versions And Upgrades + +| Goal | Start here | +| --- | --- | +| Read Kubernetes version support and the third-party onboarding range. | [Kubernetes Support Matrix](./kubernetes-support-matrix.mdx) | +| Understand version, lifecycle, runtime, OS, and architecture boundaries. | [Version and Lifecycle](./version-and-lifecycle.mdx) | +| Read release changes. | [Release Notes](./release_notes.mdx) | +| Plan cluster upgrades. | [Upgrade Overview](../upgrade/overview.mdx) | +| Prepare before upgrading the `global` cluster. | [Pre-Upgrade](../upgrade/pre-upgrade.mdx) | +| Upgrade workload clusters. | [Upgrade Workload Cluster](../upgrade/upgrade_workload_cluster.mdx) | + +## Plan Availability, Backup, And Recovery + +| Goal | Start here | +| --- | --- | +| Understand topology, HA, Global DR, and recovery boundaries. | [Availability and Recovery](./availability-and-recovery.mdx) | +| Size the `global` cluster. | [Evaluating Resources for Global Cluster](../configure/scalability/evaluating_global.mdx) | +| Size workload cluster control planes. | [Evaluating Resources for Workload Cluster](../configure/scalability/evaluating_workload.mdx) | +| Plan and operate Global Cluster Disaster Recovery. | [Global Cluster Disaster Recovery](../install/global_dr.mdx) | +| Back up and restore etcd, registry, monitoring, logging, or applications. | [Backup Overview](../configure/backup/overview.mdx) | + +## Secure And Integrate + +| Goal | Start here | +| --- | --- | +| Configure identity providers with LDAP or OIDC. | [Identity Provider Introduction](../security/users_and_roles/idp/intro.mdx) | +| Manage users, roles, and Kubernetes RBAC. | [Roles Introduction](../security/users_and_roles/role/intro.mdx) | +| Manage projects and namespaces for tenant isolation. | [Project Introduction](../security/project/intro.mdx) | +| View audit records. | [Audit Introduction](../security/audit/intro.mdx) | +| Configure NetworkPolicy. | [NetworkPolicy](../networking/security/network_policy.mdx) | +| Use API Refiner for API response filtering. | [API Security](../security/security_and_compliance/api_security/intro.mdx) | +| Use compliance features. | [Compliance Service](../security/security_and_compliance/compliance_service.mdx) | +| Use container security capabilities. | [Alauda Container Security](../security/alauda_container_security.mdx) | +| Use platform APIs. | [API Introduction](../apis/overview/intro.mdx) | +| Use CLI tools. | [CLI Tools](../ui/cli_tools/index.mdx) | diff --git a/docs/en/overview/platform-model.mdx b/docs/en/overview/platform-model.mdx new file mode 100644 index 000000000..1d9c79638 --- /dev/null +++ b/docs/en/overview/platform-model.mdx @@ -0,0 +1,75 @@ +--- +weight: 40 +--- + +# Platform Model + + uses a hub-and-spoke model. The `global` cluster provides the central platform management plane, while workload clusters and third-party clusters run or expose Kubernetes workloads under platform governance. + +Use the platform model to understand the main platform objects and how they relate to each other. + +## The `global` Cluster + +The `global` cluster is deployed during Core installation. It provides the central management plane for web console access, platform APIs, users and roles, project governance, cluster management, Extension management, and platform-wide coordination. + +The `global` cluster is not just another workload cluster in the management model. In Multi-Cluster deployments, avoid running non-platform business workloads on the `global` cluster. In Single Cluster deployments, the `global` cluster also carries business workloads, so resource planning must include both platform components and application workloads. + +For installation planning, see [Install Overview](../install/overview.mdx) and [Plan](../install/planning.mdx). + +## Workload Clusters + +A workload cluster is a Kubernetes cluster that runs application workloads and is managed from the `global` cluster. Workload clusters can be created and lifecycle-managed by when the selected infrastructure model supports that lifecycle. + +Workload clusters inherit platform governance and can be associated with projects and namespaces. They can also receive Extensions, observability components, networking components, storage integrations, and application workloads according to the selected cluster model and installed capabilities. + +For cluster creation tasks, see [Clusters Overview](../configure/clusters/overview.mdx) and [Creating an On-Premise Cluster](../configure/clusters/on-premises.mdx). + +## Third-Party Clusters + +A third-party cluster is a Kubernetes environment whose Kubernetes distribution and lifecycle are provided or managed outside . This includes existing Kubernetes environments, external Kubernetes distributions, and public cloud Kubernetes services. + + can onboard third-party clusters for centralized governance, resource visibility, application operations, Extension installation, and observability integration when the required version range, connectivity, credentials, installed components, provider prerequisites, and Extension compatibility are satisfied. + +For third-party clusters, does not own the complete Kubernetes lifecycle, node lifecycle, or provider infrastructure lifecycle unless a specific provider or plugin document states that capability. Kubernetes installation, Kubernetes upgrades, node scaling, and infrastructure operations usually remain the responsibility of the cluster owner, external distribution, or cloud provider. + +`Third-party cluster` is the product-model term for these onboarded environments. `Managed Cluster` is the current UI and navigation label for the interface that manages them. + +For onboarding workflows, see [Managed Clusters Overview](../configure/clusters/managed/overview.mdx), [Import Clusters](../configure/clusters/managed/import/overview.mdx), and [Register Cluster](../configure/clusters/managed/register.mdx). + +## Hosted Control Plane + +Hosted Control Plane (HCP) is a control-plane topology, not a cluster model parallel to Installer-Provisioned Infrastructure (IPI) or User-Provisioned Infrastructure (UPI). In HCP, each hosted cluster has its own hosted control plane, and multiple hosted control planes run as workloads on a management cluster. In , HCP is implemented through Kamaji (`TenantControlPlane`). + +For 4.3, HCP is Technology Preview, is not production-supported, supports disconnected environments, and currently defaults to IPI only. Do not use HCP documentation as production topology, sizing, HA, or backup/restore guidance for 4.3. + +For HCP scope and tasks, see [About Hosted Control Plane](../configure/clusters/about-hcp.mdx). + +## Projects And Namespaces + +A project is a governance unit for tenants, teams, or business systems. It can span multiple associated clusters and provides a boundary for users, quotas, policies, and resource visibility. + +A namespace is a Kubernetes resource isolation unit. In , a namespace can be created in or imported into a project so that project-level governance applies to the namespace and its workloads. + +The relationship is: + +| Object | Relationship in | +| --- | --- | +| `global` cluster | Hosts the central management plane and manages platform governance state. | +| Workload cluster or third-party cluster | Provides Kubernetes capacity and cluster-local APIs where workloads run. | +| Project | Defines a tenant, team, or business-system governance boundary and can be associated with one or more clusters. | +| Namespace | Exists in an associated cluster and can be created in or imported into a project so that project governance applies. | +| Workloads and resources | Run inside namespaces and inherit the applicable project, namespace, and cluster policies. | + +For project and namespace concepts, see [Project Introduction](../security/project/intro.mdx) and [Namespace Management](../developer/building_application/namespace/index.mdx). + +## What Happens Where + +| Area | Usually happens in the `global` cluster | Usually happens in workload or third-party clusters | +| --- | --- | --- | +| Platform access | Web console, platform APIs, central authentication flow, and platform-level controllers | Cluster API endpoints and cluster-local Kubernetes APIs | +| Governance | Users, roles, projects, quotas, policies, and cluster association | Namespace-level Kubernetes resources and workload permissions | +| Cluster lifecycle | Cluster creation, onboarding records, upgrade orchestration for supported cluster models, and Extension management | Kubernetes control plane, nodes, workloads, cluster-local components, and provider-owned lifecycle | +| Observability and audit | Central views, queries, dashboards, and audit interfaces when required services are installed | Metric, log, event, or audit collection components, subject to provider and connectivity boundaries | +| Recovery | Global Cluster Disaster Recovery and platform-state recovery planning | Cluster-level backup/restore, component data recovery, and application backup/restore | + +For the high-level architecture, see [Architecture](./architecture.mdx). For model comparisons and responsibility boundaries, see [Cluster Management Models](./cluster-management-models.mdx). diff --git a/docs/en/overview/release_notes.mdx b/docs/en/overview/release_notes.mdx index 8b836a0a3..f346b8fe1 100644 --- a/docs/en/overview/release_notes.mdx +++ b/docs/en/overview/release_notes.mdx @@ -1,96 +1,97 @@ --- -weight: 20 -title: Release Notes +weight: 100 --- # Release Notes +Review release notes with the [Kubernetes Support Matrix](./kubernetes-support-matrix.mdx), [Version and Lifecycle](./version-and-lifecycle.mdx), and feature-specific documentation to understand release changes and exact support boundaries. + ## 4.3.0 -### Features and Enhancements +### Release Baseline + + 4.3 adds Kubernetes 1.34 support for platform-managed cluster creation and changes the upgrade prerequisite model so workload clusters can remain within the documented compatible-version range before the `global` cluster upgrade. + +For 4.3, the compatible workload-cluster versions are 1.34, 1.33, 1.32, and 1.31. This compatible-version requirement determines whether the `global` cluster can be upgraded and is separate from the third-party cluster accepted onboarding range. + +For more information, see [Kubernetes Support Matrix](./kubernetes-support-matrix.mdx). -#### Support for Kubernetes 1.34 +### Features And Enhancements -ACP 4.3 adds support for **Kubernetes 1.34** for platform-managed cluster scenarios. +#### Kubernetes 1.34 Support -For upgrades to ACP 4.3, the workload-cluster compatible versions are 1.34, 1.33, 1.32, and 1.31. This compatible-version requirement determines whether the `global` cluster can be upgraded and is separate from the third-party cluster management range. + 4.3 supports Kubernetes 1.34 for platform-managed cluster creation. -For more information, see [Kubernetes Support Matrix](/overview/kubernetes-support-matrix.mdx). +For upgrades to 4.3, workload clusters must remain within the compatible versions 1.34, 1.33, 1.32, and 1.31. #### CVO-Based Cluster Upgrade Workflow -ACP 4.3 introduces a Cluster Version Operator (CVO)-based upgrade workflow for both `global` and workload clusters. + 4.3 introduces a Cluster Version Operator (CVO)-based upgrade workflow for both `global` and workload clusters. Key capabilities include: -* Preparing upgrade artifacts and the upgrade controller with `bash upgrade.sh` -* Running preflight checks before execution -* Requesting upgrades from the Web Console or by updating `ClusterVersionShadow.spec.desiredUpdate` -* Inspecting conditions, preflight results, stages, and history from `cvsh.status` +- Preparing upgrade artifacts and the upgrade controller with `bash upgrade.sh`. +- Running preflight checks before execution. +- Requesting upgrades from the Web Console or by updating `ClusterVersionShadow.spec.desiredUpdate`. +- Inspecting conditions, preflight results, stages, and history from `cvsh.status`. -ACP CLI also introduces upgrade-oriented administrator commands such as `ac adm upgrade`, `ac adm upgrade status`, `--to-latest`, `--to`, and `--allow-explicit-upgrade` for requesting and troubleshooting workload cluster upgrades from the current context. +The CLI also introduces upgrade-oriented administrator commands such as `ac adm upgrade`, `ac adm upgrade status`, `--to-latest`, `--to`, and `--allow-explicit-upgrade` for requesting and troubleshooting workload cluster upgrades from the current context. -For operational guidance, see [Upgrade](/upgrade/index.mdx). +For operational guidance, see [Upgrade](../upgrade/index.mdx). #### Standalone Cluster Plugin Upgrade -ACP 4.3 adds standalone upgrade support for cluster plugins that use the `Aligned` or `Agnostic` life cycle. + 4.3 adds standalone upgrade support for Cluster Plugins that use the `Aligned` or `Agnostic` lifecycle. -The **Cluster Plugins** page now shows the plugin life cycle, and eligible plugins can be upgraded independently from the list page or details page. `Core` plugins continue to follow cluster upgrades. +The **Cluster Plugins** page shows the plugin lifecycle, and eligible plugins can be upgraded independently from the list page or details page. `Core` plugins continue to follow cluster upgrades. -#### MicroOS-Based Global Clusters on Huawei DCS +For lifecycle details, see [Core and Extensions](./core-and-extensions.mdx) and [Cluster Plugin](../extend/cluster_plugin.mdx). -ACP 4.3 allows administrators to create the `global` cluster on Huawei DCS with MicroOS-based immutable infrastructure. This extends the immutable operating model from workload clusters to platform installation scenarios on DCS. +#### MicroOS-Based Global Clusters -For more information, see [About Immutable Infrastructure](/configure/clusters/immutable-infra.mdx). + 4.3 allows administrators to create the `global` cluster with MicroOS-based immutable infrastructure in supported provider scenarios. This extends the immutable operating model from workload clusters to platform installation scenarios. -#### Huawei Cloud Stack Support in Immutable Infrastructure +For more information, see [About Immutable Infrastructure](../configure/clusters/immutable-infra.mdx). -ACP 4.3 adds Immutable Infrastructure support for Huawei Cloud Stack (HCS). The HCS provider documentation now covers provider overview, installation, cluster creation, node management, cluster upgrades, and provider APIs in the Immutable Infrastructure documentation set. +#### Immutable Infrastructure Provider Updates -For more information, see [About Immutable Infrastructure](/configure/clusters/immutable-infra.mdx). + 4.3 expands Immutable Infrastructure coverage during the 4.3 cycle. Provider-specific Immutable Infrastructure guidance covers provider overview, installation, cluster creation, node management, cluster upgrades, and provider APIs. -#### VMware vSphere Support in the 4.3 Cycle - -ACP 4.3 begins introducing Immutable Infrastructure support for VMware vSphere. The provider work is now tracked in the Immutable Infrastructure documentation set, while the public installation details and finalized plugin naming are still being published. - -For more information, see [About Immutable Infrastructure](/configure/clusters/immutable-infra.mdx). +For more information, see [About Immutable Infrastructure](../configure/clusters/immutable-infra.mdx). #### New Web Console Preview Entry -ACP Core now provides the top-navigation anchor required by the next-generation Web Console experience. When Alauda Container Platform Web Console Base is installed on the `global` cluster, users in the **Container Platform** and **Administrator** views can open the new console through a **Preview Next-Gen Console** entry in a separate browser tab. + Core provides the top-navigation anchor required by the next-generation Web Console experience. When the Web Console Base plugin is installed on the `global` cluster, users in the **Container Platform** and **Administrator** views can open the new console through a **Preview Next-Gen Console** entry in a separate browser tab. -The experience is designed for gradual migration and works with the Web Console Base plugin on the global cluster and the Web Console Collector plugin on workload clusters. +The experience is designed for gradual migration and works with the Web Console Base plugin on the `global` cluster and the Web Console Collector plugin on workload clusters. #### Containerd 2.0 Baseline -ACP 4.3 upgrades the platform runtime baseline to containerd 2.0. Review runtime-dependent operational procedures before upgrading environments that rely on customized containerd configuration. + 4.3 upgrades the platform runtime baseline to containerd 2.0. Review runtime-dependent operational procedures before upgrading environments that rely on customized containerd configuration. -#### Expanded Third-Party Cluster Management Range +For runtime and architecture boundaries, see [Version and Lifecycle](./version-and-lifecycle.mdx). -For third-party clusters, ACP 4.3 now accepts Kubernetes versions in the range `>=1.19.0 <1.35.0`. +#### Expanded Third-Party Cluster Accepted Onboarding Range -This management range is separate from the compatible Kubernetes versions used to determine whether the `global` cluster can be upgraded. +For third-party clusters, 4.3 accepts Kubernetes versions in the range `>=1.19.0 <1.35.0`. -Product documentation continues to publish only the Kubernetes versions that have passed product validation for third-party cluster support and the default Extend baseline. +This range is separate from the compatible Kubernetes versions used to determine whether the `global` cluster can be upgraded. It is an onboarding gate and does not mean every Kubernetes version, provider, operation, capability, or Extension in the range has complete product validation. -Product validation for the Extend baseline covers the following capability areas: +Product validation for the default Extend baseline covers these capability areas: -* Installing and using Operators -* Installing and using Cluster Plugins -* ClickHouse-based logging -* VictoriaMetrics-based monitoring +- 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 more information, see [Kubernetes Support Matrix](/overview/kubernetes-support-matrix.mdx) and [Import Standard Kubernetes Cluster](/configure/clusters/managed/import/standard-kubernetes.mdx). +For more information, see [Kubernetes Support Matrix](./kubernetes-support-matrix.mdx), [Cluster Management Models](./cluster-management-models.mdx), and [Import Clusters](../configure/clusters/managed/import/overview.mdx). ### Fixed Issues -This section will be updated when the information becomes available. Content is currently under review and will be published in a later revision of the documentation. +No fixed issues are currently published for this release. ### Known Issues -This section will be updated when the information becomes available. Content is currently under review and will be published in a later revision of the documentation. +No known issues are currently published for this release. diff --git a/docs/en/overview/version-and-lifecycle.mdx b/docs/en/overview/version-and-lifecycle.mdx new file mode 100644 index 000000000..c3355ebe3 --- /dev/null +++ b/docs/en/overview/version-and-lifecycle.mdx @@ -0,0 +1,87 @@ +--- +weight: 80 +--- + +# Version and Lifecycle + +Use this guidance to plan version compatibility, Kubernetes support, third-party cluster onboarding, runtime and OS boundaries, and Extension lifecycle checks. + +Use [Kubernetes Support Matrix](./kubernetes-support-matrix.mdx) for the exact Kubernetes version table. + +## Product And Kubernetes Versions + +For 4.3: + +- Platform-managed cluster creation supports Kubernetes 1.34. +- Before upgrading the `global` cluster to 4.3, workload clusters must remain within the compatible versions 1.34, 1.33, 1.32, and 1.31. +- For 4.3 and later, workload clusters only need to remain within the documented compatible-version range before a `global` cluster upgrade. +- In 4.2 and earlier, workload clusters must be upgraded to the latest Kubernetes version in the compatible list before upgrading the `global` cluster. + +For the exact table, see [Kubernetes Support Matrix](./kubernetes-support-matrix.mdx#version-support-matrix). + +## Third-Party Cluster Onboarding Range + +For 4.3, third-party Kubernetes clusters are accepted for onboarding only in the range `>=1.19.0 <1.35.0`. Clusters outside that range are blocked from onboarding. + +This range is separate from: + +- The Kubernetes version supported for platform-managed cluster creation. +- The workload-cluster compatible versions used before upgrading the `global` cluster. +- Product validation for every Kubernetes version, provider, capability, operation, or Extension. + +Clusters in the accepted onboarding range still need to satisfy cluster-family or provider prerequisites, connectivity, credentials, installed components, provider caveats, and Extension compatibility. + +For cluster model boundaries, see [Cluster Management Models](./cluster-management-models.mdx). + +## Runtime, OS, And CPU Architecture + +Read runtime, OS, CRI, and CPU architecture information by responsibility boundary. + +| Environment | How to read support information | +| --- | --- | +| lifecycle-managed environments | Use the documented platform baseline and node prerequisite pages. For 4.3, the release notes identify containerd 2.0 as the platform runtime baseline. | +| HCP environments | Use HCP-specific documentation and release notes. HCP runtime and version information is not replaced by a global platform runtime statement. | +| Third-party clusters | Node OS, container runtime, CRI, and CPU architecture usually remain the responsibility of the external cluster owner, external distribution, or cloud provider. | +| Immutable Infrastructure | Use the Immutable Infrastructure documentation for MicroOS images provided by and provider-specific requirements. | +| Extensions | Use the exact Extension documentation and Customer Portal compatibility metadata. Package availability for x86, ARM, or hybrid architectures is not a universal guarantee for every Extension image or provider scenario. | + +Do not infer complete Docker, CRI-O, MicroOS, mixed-architecture workload cluster, provider architecture, or universal Extension image support unless an explicit support matrix, Extension document, provider document, or release guidance states that support. + +For node prerequisites, see [Node Preprocessing](../install/prepare/node_preprocessing.mdx). For package architecture, see [Download](../install/prepare/download.mdx). For Immutable Infrastructure, see [About Immutable Infrastructure](../configure/clusters/immutable-infra.mdx). + +## Extension Lifecycle + +Operators and Cluster Plugins use the `Core`, `Aligned`, and `Agnostic` lifecycle model. + +| Lifecycle | Compatibility and upgrade meaning | +| --- | --- | +| `Core` | Follows the Core release and cluster Distribution Version. Updated through cluster upgrade. | +| `Aligned` | Follows the release stream but can be upgraded independently when a compatible version is published. | +| `Agnostic` | Released independently from and upgraded independently when a compatible version is published. | + +For a specific Operator or Cluster Plugin version, use the Customer Portal `ACP compatible versions` field as the compatibility authority. Release notes are useful for version changes. The Kubernetes support matrix is not the authority for one exact Extension version. + +For details, see [Core and Extensions](./core-and-extensions.mdx). + +## Feature Maturity + +When reading Overview, release notes, or component documentation, treat maturity labels as support boundaries: + +| Label | Meaning for readers | +| --- | --- | +| GA | The feature is generally available within the documented scope and prerequisites. | +| Technology Preview | The feature is available for evaluation within the documented limits and should not be treated as production-supported unless product documentation explicitly says so. | +| Deprecated | The feature remains available but is planned for removal or replacement. Plan migration according to release guidance. | +| Removed | The feature is no longer available in the documented release. | + +For 4.3, HCP is Technology Preview and is not production-supported. Global Cluster Disaster Recovery is generally available only within the documented `global` control-plane DR scope in [Availability and Recovery](./availability-and-recovery.mdx). + +## Upgrade Reading Path + +Before upgrading: + +1. Read [Kubernetes Support Matrix](./kubernetes-support-matrix.mdx) to confirm compatible workload-cluster versions. +2. Read [Upgrade Overview](../upgrade/overview.mdx) to understand the CVO-based upgrade model. +3. Read [Pre-Upgrade](../upgrade/pre-upgrade.mdx) before upgrading the `global` cluster. +4. Check Extension compatibility in the Customer Portal and the Extension documentation. +5. Review [Release Notes](./release_notes.mdx) for version changes, behavior changes, technical preview status, deprecated features, and known issues. diff --git a/llms.txt b/llms.txt index 45e695c8a..646313e98 100644 --- a/llms.txt +++ b/llms.txt @@ -102,7 +102,7 @@ Includes CRD definitions and comprehensive platform guides. - [docs/en/configure/clusters/nodes/node-monitoring.mdx](docs/en/configure/clusters/nodes/node-monitoring.mdx): How to inspect node monitoring on the node details Monitoring tab when Prometheus/VictoriaMetrics monitoring is configured, with detailed definitions of CPU/Memory usage, request, and limit rates, storage space and inode usage, system load (1/5/15 min), disk throughput and IOPS, and network traffic and packet rates. Includes guidance on exporting PromQL expressions and the storage partition rollup behavior when a node has more than 4 partitions. - [docs/en/configure/clusters/nodes/overview.mdx](docs/en/configure/clusters/nodes/overview.mdx): Concept page defining cluster nodes as VMs or physical servers running Kubelet, Kube-proxy, and a container runtime, and contrasting Control Plane Nodes (kube-apiserver, kube-scheduler, kube-controller-manager, etcd) with Compute Nodes. States the 1/3/5 control-plane HA rule, the prohibition on node add/delete for imported clusters, and points to node availability and OS/kernel/CPU compatibility references. - [docs/en/configure/clusters/on-premises.mdx](docs/en/configure/clusters/on-premises.mdx): End-to-end guide for creating an on-premises workload cluster, including node availability checks, choosing a hardware LoadBalancer vs `Self-built VIP` (keepalived/VRRP) for ports 6443/11780/11781, image registry selection, container-network options (Kube-OVN with Overlay/Underlay and Cluster CIDR / Service CIDR / Join CIDR, Calico, Flannel with Node IP Count, or Custom), node settings (NIC, hostname-vs-IP, monitoring type with Prometheus or VictoriaMetrics/VMStorage/VMAlert/VMAgent), node-add parameters (SSH password or key, SOCKS5 proxy), and extended `kubeletExtraArgs` (including `max-pods`), `controllerManagerExtraArgs`, `schedulerExtraArgs`, `apiServerExtraArgs`, and `publicAlternativeNames`. -- [docs/en/configure/clusters/overview.mdx](docs/en/configure/clusters/overview.mdx): High-level overview of ACP's cluster-management models: Platform-Provisioned Infrastructure (platform provisions machines and immutable OS, currently MicroOS), User-Provisioned Infrastructure (user provides machines and OS, platform manages Kubernetes), Hosted Control Plane (HCP) where a management cluster hosts multiple shared control planes, and Connected Clusters for public-cloud (EKS/AKS/GKE) or CNCF-compliant Kubernetes plus a Tunnel Server/Agent for disconnected environments. Includes the ACP 4.3 version compatibility policy (third-party clusters accepted in range `>=1.19.0 <1.35.0`). +- [docs/en/configure/clusters/overview.mdx](docs/en/configure/clusters/overview.mdx): Serves as the Configure > Clusters path-selection entry for creating platform-managed clusters, evaluating Hosted Control Plane, or onboarding existing Kubernetes environments. It links to the canonical Cluster Management Models concept page, routes readers to IPI, UPI, HCP (Kamaji-based), import, and register workflows, and preserves ACP 4.3 and ACP 4.2 version compatibility guidance. - [docs/en/configure/feature_toggles.mdx](docs/en/configure/feature_toggles.mdx): How to use the Feature Gate page at `{platform-access-address}/console-platform/feature-gate` to control Alpha and Beta feature visibility platform-wide via the Stage Setting section, enable specific features for an individual cluster, or disable specific features globally via System Settings. Gates may affect UI visibility, API behavior, or both depending on the feature implementation. - [docs/en/configure/networking/functions/configure_alb.mdx](docs/en/configure/networking/functions/configure_alb.mdx): Detailed configuration reference for the deprecated ALB load balancer custom resource (ALB2/v2beta1), including the `.spec.config` schema for replicas, nodeSelector, resources, projects, networkMode (host/container), vip.enableLbSvc, and address. Documents the companion Frontend CR (L4 tcp/udp and L7 http/https/grpc/grpcs listener ports with `serviceGroup` and `certificate_name`), Rule CR with DSLX matching (URL/HOST/HEADER/METHOD/PARAM/COOKIE/SRC_IP, priority 0-10), HTTPS termination/re-encrypt modes, ingress sync via IngressClass and `cpaas.io/project` label, plus the `alb.networking.cpaas.io/tls` cross-namespace certificate annotation. Recommends migration to `ingress-nginx-operator` or `envoy-gateway`. - [docs/en/configure/networking/functions/configure_certificate.mdx](docs/en/configure/networking/functions/configure_certificate.mdx): Steps for the platform administrator to import a TLS certificate via Network Management > Certificates, supplying the `tls.crt` public key and `tls.key` private key (binary uploads unsupported) and assigning it to All Projects, a Specified Project, or No Assignment, so developers can later reuse it on ingresses and load balancers. Notes that the feature does not work on public-cloud clusters where a TLS-type Secret must be created in the target namespace instead. @@ -313,11 +313,14 @@ Includes CRD definitions and comprehensive platform guides. ## install - [docs/en/install/global_dr.mdx](docs/en/install/global_dr.mdx): Complete disaster recovery runbook for the `global` control-plane cluster on traditional OS using an active/standby pair synchronized via etcd; covers required network resources (dedicated VIPs per cluster, unified domain, LB forwarding 80/443/6443/2379/11443), strict installer parameters (User-provisioned LB, identical certificate and image-repository credentials, domain-only Platform Access Address), the cross-cluster encryption-provider.conf copy, installing the `etcd Synchronizer` cluster plugin with bearer-token Secret etcd-sync-active-cluster-token, bootstrap Job and lease-based leader verification, sync status checks against the etcd-sync-monitor service, restart commands for Elasticsearch/VictoriaMetrics/cluster-transformer/warlock after failover, and a list of namespaces excluded from sync (cpaas-system, kube-ovn, kubevirt, nativestor-system, etc.). -- [docs/en/install/installing.mdx](docs/en/install/installing.mdx): Step-by-step installation procedure for the `global` cluster on traditional OS: upload and extract the Core Package into /root/cpaas-install, run `bash setup.sh` (with optional `--ip-family ipv6`) to launch the installer Web UI on port 8080, complete parameter configuration (Kubernetes version, cluster network protocol IPv4/IPv6/dual-stack, Cluster Endpoint, Platform Access Address, Certificate, Image Repository Platform Deployment vs External, Container Network with Kube-OVN Overlay restrictions, Node Name and Platform Exclusive isolation, 1 or 3 control plane nodes), post-install verification via `kubectl get apprelease` and pod status checks, mandatory installation of the Alauda Container Platform Product Docs cluster plugin, and forced installer cleanup via `nerdctl rm -f minialauda-control-plane`. -- [docs/en/install/overview.mdx](docs/en/install/overview.mdx): Overview of installing the ACP Core (`global` cluster) on traditional OS, outlining the three-stage process (Preparation: prerequisite check, package download, node preprocessing; Execution: upload/extract, `bash setup.sh`, Web UI parameter configuration; Verification: Web UI and CLI checks), with sidebars on the Alauda Customer Portal (downloads, knowledge base, support tickets, marketplace, license management) and a redirect note for users running on Immutable Infrastructure (MicroOS on Huawei DCS, VMware vSphere, Huawei Cloud Stack). +- [docs/en/install/installing.mdx](docs/en/install/installing.mdx): Step-by-step installation procedure for the `global` cluster on traditional OS: upload and extract the Core Package into /root/cpaas-install, run `bash setup.sh` (with optional `--ip-family ipv6`) to launch the installer Web UI on port 8080, complete parameter configuration (Kubernetes version, cluster network protocol IPv4/IPv6/dual-stack, Cluster Endpoint, Platform Access Address, Certificate, Image Repository Platform Deployment vs External, Container Network with Kube-OVN Overlay restrictions, Node Name and Platform Exclusive isolation, 1 or 3 control plane nodes), a "Common Stalls and Where to Look" troubleshooting table for the typical install symptoms, and forced installer cleanup via `nerdctl rm -f minialauda-control-plane`. Validation and post-install tasks are linked out to dedicated pages. +- [docs/en/install/next_steps.mdx](docs/en/install/next_steps.mdx): Next steps after ACP Core validation. Prioritized post-install task table — Product Docs plugin install, Global Cluster Disaster Recovery, workload cluster onboarding, Extensions, identity and access setup, storage/networking/registry preparation, and backup/upgrade/observability docs — plus the inline Product Docs plugin install procedure. +- [docs/en/install/overview.mdx](docs/en/install/overview.mdx): Overview of installing ACP Core (`global` cluster) on traditional OS. Defines installation as deployment of the `global` cluster, separates Core from workload clusters, imported clusters, Extensions Packages, Operators, and Cluster Plugins, and provides the install route map across planning, preparation, download, installation, validation, and post-install tasks. Includes the Customer Portal sidebar and a redirect note for users running on Immutable Infrastructure (MicroOS on Huawei DCS, VMware vSphere, Huawei Cloud Stack). +- [docs/en/install/planning.mdx](docs/en/install/planning.mdx): Planning guide for ACP Core installation. 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): Instructions for downloading the ACP Core Package from the Alauda Customer Portal, picking between x86, ARM, and hybrid architectures, and the migration procedure for moving from a single-architecture install to hybrid (re-download hybrid Core Package, run `bash upgrade.sh --only-sync-image=true` to sync multi-architecture images to the registry, then remove the `cpaas.io/node-arch-constraint` label from the `cluster.platform.tkestack.io global` resource if present). - [docs/en/install/prepare/node_preprocessing.mdx](docs/en/install/prepare/node_preprocessing.mdx): Comprehensive node preprocessing checklist for all control plane and worker nodes prior to global cluster install: supported OS/kernel matrix (RHEL 7.8/8.0/8.6/8.10/9.6, CentOS 7.6-7.9, Ubuntu 20.04/22.04 LTS, Kylin V10 SP3 for x86 and ARM/Kunpeng 920), the `init.sh` quick-configuration script, mandatory checks (transparent_hugepage=never, ip_vs/nf_conntrack/geneve/openvswitch kernel modules, disable apparmor/selinux/firewall/swap, sudo-without-password root SSH, DefaultTasksMax=infinity, hostname rules, /etc/hosts and /etc/resolv.conf rules, no occupation of control-plane ports 2379/2380/6443/10249-10256 and Kube-OVN 6641/6642 or Calico 179, removal of /var/lib/docker etc.), commands to detect/remove conflicting docker/podman/containerd/runc/kubernetes packages on RHEL/Ubuntu/Kylin, and DNS search-domain constraints (`domainCountLimit - 3`, MaxDNSSearchListChar=2048). - [docs/en/install/prepare/prerequisites.mdx](docs/en/install/prepare/prerequisites.mdx): Pre-installation planning for the global cluster: deployment architecture selection (Multi-Cluster / Single Cluster / Single Node with min 12c24GB for PoC), ARM Kunpeng-920 sizing rule (1.5-2x x86), required network resources (`global` VIP, optional External IP, recommended Domain Name when IPv6 or DR is needed, optional trusted Certificate), network performance requirements (intra-cluster >= 1 Gbps & <= 10ms, cross-cluster >= 100 Mbps & <= 100ms), warning to avoid the 172.17-18 subnet used by nerdctl, and the load balancer forwarding rules table (443 for Web/API/registry HTTPS, 6443 for kube-apiserver, 11443 for the in-cluster image registry, with 2379 added for DR setups). +- [docs/en/install/validation.mdx](docs/en/install/validation.mdx): ACP Core post-install validation guide. Validates Web UI access, runs `kubectl` checks on the `global` cluster for node readiness, `ClusterModule/global` phase, failed AppReleases, and stuck Pods, and links forward to Next Steps when the cluster is healthy. ## networking @@ -388,10 +391,17 @@ Includes CRD definitions and comprehensive platform guides. ## overview -- [docs/en/overview/architecture.mdx](docs/en/overview/architecture.mdx): Architectural reference for Alauda Container Platform (ACP) using a hub-and-spoke model with a `global` cluster (Gateway, Auth, Web Console, OLM, Cluster Plugins, internal Registry, Observability, Cluster Proxy) and workload clusters. Covers ACP Core vs Extensions (Aligned/Agnostic lifecycles via Operator and Cluster Plugin stacks), HA mechanisms for etcd (RAFT, 3/5 nodes), Prometheus with Thanos Query, VictoriaMetrics cluster mode, Kafka/Elasticsearch/Razor/Lanaya for logging, ALB (3 replicas, leader election), Keepalived VIP, Harbor with Patroni/Redis Sentinel, and MinIO erasure-coded storage; plus the Primary/Standby DR model based on etcd sync. -- [docs/en/overview/glossary.mdx](docs/en/overview/glossary.mdx): Canonical glossary of ACP platform-wide terms covering cluster concepts (`global` Cluster, Workload Cluster, Platform-Provisioned vs User-Provisioned Infrastructure, Hosted Control Plane, Managed Cluster, Immutable OS / Immutable Infrastructure, Project, Namespace, Control Plane/Worker Node), identity (IdP, OIDC), extensions (Operator, OLM, OperatorHub, Cluster Plugin via `ModulePlugin`/`ModuleConfig`/`ModuleInfo`), networking (Ingress, Gateway API, Service, LoadBalancer, Platform Access Address, Cluster Endpoint, Self-built VIP) and DR/upgrade terms (Global Cluster DR, Cluster Version Operator). -- [docs/en/overview/kubernetes-support-matrix.mdx](docs/en/overview/kubernetes-support-matrix.mdx): Kubernetes version support matrix per ACP release: ACP 4.3 creates clusters at 1.34 and is compatible with 1.31-1.34; ACP 4.2 at 1.33 (1.30-1.33); ACP 4.1 at 1.32 (1.29-1.32); ACP 4.0 supports creation on 1.28-1.31. Documents the separate third-party cluster management range `>=1.19.0 <1.35.0` for 4.3 and the upgrade rule changes between 4.2 and 4.3+. -- [docs/en/overview/release_notes.mdx](docs/en/overview/release_notes.mdx): Release notes for ACP 4.3.0 covering Kubernetes 1.34 support, the new Cluster Version Operator (CVO)-based upgrade workflow (`bash upgrade.sh`, `ClusterVersionShadow`, `ac adm upgrade` CLI), standalone upgrade of Aligned/Agnostic cluster plugins, MicroOS-based `global` clusters on Huawei DCS, Immutable Infrastructure support for Huawei Cloud Stack and the beginning of VMware vSphere support, the **Preview Next-Gen Console** entry from Web Console Base, the containerd 2.0 baseline, and the expanded third-party cluster management range `>=1.19.0 <1.35.0`. +- [docs/en/overview/introduction.mdx](docs/en/overview/introduction.mdx): Introduces Alauda Container Platform as a Kubernetes-based platform for cloud-native application delivery, cluster operations, project governance, Extensions, observability, security, upgrade planning, and recovery. It explains the relationship to Kubernetes, separates Core and Extension capabilities, and provides a first-reader path through Architecture, Platform Model, Cluster Management Models, Core and Extensions, and Learn More. +- [docs/en/overview/architecture.mdx](docs/en/overview/architecture.mdx): Explains the hub-and-spoke architecture built around the `global` management cluster, workload clusters, third-party clusters, and Hosted Control Plane boundaries. It summarizes access paths, management paths, state and data domains, Core and Extension boundaries, and availability/recovery entry points while keeping the existing architecture diagram. +- [docs/en/overview/platform-model.mdx](docs/en/overview/platform-model.mdx): Describes the ACP platform model, including the `global` cluster, workload clusters, third-party clusters, Hosted Control Plane, projects, and namespaces. It clarifies where platform management, governance, observability, Extension management, and recovery responsibilities usually occur. +- [docs/en/overview/cluster-management-models.mdx](docs/en/overview/cluster-management-models.mdx): Defines the canonical platform-level cluster model through three separate axes: infrastructure responsibility with Installer-Provisioned Infrastructure (IPI) and User-Provisioned Infrastructure (UPI), control-plane topology with dedicated control planes and Hosted Control Plane (HCP, implemented in ACP through Kamaji `TenantControlPlane`), and Kubernetes ownership/onboarding with ACP lifecycle-managed workload clusters and third-party clusters. It summarizes third-party cluster capability boundaries, import/register onboarding methods, version gates, and provider or workflow caveat categories. +- [docs/en/overview/core-and-extensions.mdx](docs/en/overview/core-and-extensions.mdx): Explains ACP Core, Operators, Cluster Plugins, Extension lifecycle types, Customer Portal compatibility metadata, the default Extend baseline, and capability boundaries for registry, observability, audit, security, compliance, and independent products or subsites. +- [docs/en/overview/availability-and-recovery.mdx](docs/en/overview/availability-and-recovery.mdx): Summarizes topology, high availability, Global Cluster Disaster Recovery, and backup/restore paths. It distinguishes Multi-Cluster, Single Cluster, and Single Node scenarios, clarifies Global DR as `global` control-plane DR only, and routes readers to sizing, DR, backup, registry, monitoring, logging, and application recovery docs. +- [docs/en/overview/version-and-lifecycle.mdx](docs/en/overview/version-and-lifecycle.mdx): Explains ACP and Kubernetes version relationships, third-party Kubernetes accepted onboarding range, runtime/OS/CPU architecture responsibility boundaries, Extension lifecycle types, feature maturity labels, and upgrade reading paths. +- [docs/en/overview/kubernetes-support-matrix.mdx](docs/en/overview/kubernetes-support-matrix.mdx): Provides the Kubernetes version support matrix for ACP releases, including versions supported for platform-managed cluster creation, workload-cluster compatible versions before `global` upgrades, the ACP 4.3 third-party Kubernetes accepted onboarding range `>=1.19.0 <1.35.0`, default Extend baseline scope, and upgrade requirements. +- [docs/en/overview/release_notes.mdx](docs/en/overview/release_notes.mdx): Summarizes ACP 4.3.0 release baseline, Kubernetes 1.34 support, CVO-based upgrades, standalone Cluster Plugin upgrades, MicroOS and Immutable Infrastructure updates, next-generation console preview entry, containerd 2.0 baseline, and third-party cluster onboarding range. Fixed issues and known issues use neutral empty-state wording when no issues are currently published. +- [docs/en/overview/glossary.mdx](docs/en/overview/glossary.mdx): Defines platform-wide terms such as ACP Core, `global` cluster, workload cluster, third-party cluster, Managed Cluster as a UI label, Installer-Provisioned Infrastructure (IPI), User-Provisioned Infrastructure (UPI), Hosted Control Plane (HCP, Kamaji-based in ACP), Extensions, lifecycle types, identity and security terms, access terms, and disaster recovery or upgrade terms. +- [docs/en/overview/learn-more.mdx](docs/en/overview/learn-more.mdx): Provides a task-oriented route map for understanding the platform, installing and planning, managing clusters, building and operating applications, installing Extensions, planning versions and upgrades, planning availability and recovery, and finding security, API, and CLI documentation. ## security