diff --git a/docs/en/configure/clusters/overview.mdx b/docs/en/configure/clusters/overview.mdx index fed033270..ffe931f17 100644 --- a/docs/en/configure/clusters/overview.mdx +++ b/docs/en/configure/clusters/overview.mdx @@ -12,7 +12,7 @@ Start here to choose whether to create a platform-managed cluster, evaluate Host | --- | --- | --- | | 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](../hosted_control_planes/overview.mdx) | HCP is Technology Preview in 4.3 and is not production-supported. | +| Evaluate Hosted Control Plane (HCP). | [About Hosted Control Plane](../hosted_control_planes/overview.mdx) | Check the HCP documentation for current maturity, operating system, connectivity, and production-use boundaries. | | Onboard an existing Kubernetes environment. | [Third-Party Cluster Onboarding](./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 Third-Party Clusters](./managed/import/overview.mdx) and [Register Cluster](./managed/register.mdx) | Import and register are onboarding methods, not separate day-2 capability models. | @@ -43,7 +43,7 @@ To create and manage User-Provisioned Infrastructure clusters through APIs, see 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. -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](../hosted_control_planes/overview.mdx). +In , HCP is implemented through Kamaji (`TenantControlPlane`). For current support scope and evaluation details, see [About Hosted Control Plane](../hosted_control_planes/overview.mdx). ## Third-Party Cluster Onboarding @@ -62,19 +62,14 @@ For onboarding workflows, see [Third-Party Cluster Onboarding](./managed/overvie ## Version Compatibility \{#version-compatibility} -When importing or connecting existing clusters, validate the Kubernetes version against the current compatibility policy. +Use the [Kubernetes Support Matrix](../../overview/kubernetes-support-matrix.mdx) to choose platform-managed cluster creation targets, verify workload-cluster upgrade prerequisites, and validate third-party cluster onboarding versions. These are separate ranges for separate decisions. -### 4.3 And Later +### Upgrade Prerequisite Behavior -- 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. +- For 4.3 and later, workload clusters only need to remain within the Compatible Versions before the `global` cluster upgrade. +- The third-party onboarding range is independent from the Compatible Versions used for this upgrade prerequisite. ### 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. +- Use the Kubernetes Support Matrix as the numerical authority for the documented version mapping. diff --git a/docs/en/configure/hosted_control_planes/overview.mdx b/docs/en/configure/hosted_control_planes/overview.mdx index 6d8f719c9..e13cd72ae 100644 --- a/docs/en/configure/hosted_control_planes/overview.mdx +++ b/docs/en/configure/hosted_control_planes/overview.mdx @@ -6,6 +6,6 @@ weight: 10 Hosted Control Plane (HCP) 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. In , HCP is implemented through Kamaji (`TenantControlPlane`). -In 4.3, HCP is Technology Preview, is not production-supported, supports disconnected environments, and defaults to Installer-Provisioned Infrastructure (IPI) only. Use HCP for non-production evaluation only. For installation and operation tasks within that scope, follow the HCP guidance below. +HCP is a Technology Preview intended only for non-production proof-of-concept (POC) evaluation. Disconnected environments are supported. HCP supports only traditional operating systems; Alauda OS is not supported. For installation and operation tasks within that scope, follow the HCP guidance below. diff --git a/docs/en/install/global_dr.mdx b/docs/en/install/global_dr.mdx index 1e7d11fae..aec408a20 100644 --- a/docs/en/install/global_dr.mdx +++ b/docs/en/install/global_dr.mdx @@ -5,7 +5,7 @@ weight: 60 # Global Cluster Disaster Recovery -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 . +This page documents disaster recovery for `global` clusters running on a **traditional operating system**. If the `global` cluster uses Alauda OS, follow instead. ## Overview diff --git a/docs/en/install/index.mdx b/docs/en/install/index.mdx index c840b4588..0c2ab558b 100644 --- a/docs/en/install/index.mdx +++ b/docs/en/install/index.mdx @@ -5,7 +5,7 @@ weight: 20 # Install -This section documents installation onto a **traditional operating system** such as Ubuntu or RHEL. If your environment runs on Immutable Infrastructure (Alauda OS on Huawei DCS, VMware vSphere, or Huawei Cloud Stack), see instead. +This section documents installation onto a **traditional operating system** such as Ubuntu or RHEL. If your environment uses Alauda OS, see instead. diff --git a/docs/en/install/installing.mdx b/docs/en/install/installing.mdx index 282478206..60d1f9f13 100644 --- a/docs/en/install/installing.mdx +++ b/docs/en/install/installing.mdx @@ -7,7 +7,7 @@ weight: 30 This section describes how to install Core and deploy the `global` cluster. -This installation path applies to clusters running on a **traditional operating system**. For environments on Immutable Infrastructure (Alauda OS on Huawei DCS, VMware vSphere, or Huawei Cloud Stack), see instead. +This installation path applies to clusters running on a **traditional operating system**. If your environment uses Alauda OS, 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. diff --git a/docs/en/install/overview.mdx b/docs/en/install/overview.mdx index b73881393..3842aac6f 100644 --- a/docs/en/install/overview.mdx +++ b/docs/en/install/overview.mdx @@ -19,7 +19,7 @@ Use the Install section to plan and complete ** Core 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 (Alauda OS on Huawei DCS, VMware vSphere, or Huawei Cloud Stack), see instead. +The procedure described in this section installs the `global` cluster onto a **traditional operating system** such as Ubuntu or RHEL. If the `global` cluster uses Alauda OS, see instead. The following work is outside the Core installation flow: diff --git a/docs/en/install/prepare/node_preprocessing.mdx b/docs/en/install/prepare/node_preprocessing.mdx index 7fef2cb3b..9ab2fb064 100644 --- a/docs/en/install/prepare/node_preprocessing.mdx +++ b/docs/en/install/prepare/node_preprocessing.mdx @@ -7,57 +7,40 @@ weight: 30 Before installing the `global` cluster, all nodes (control plane nodes and worker nodes) must complete preprocessing. :::info -This page applies to nodes running a **traditional operating system** such as RHEL, CentOS, or Ubuntu, which provisions over SSH. Several of the checks below — for example the SSH user and the `/etc/ssh/sshd_config` settings — exist to keep the SSH-based node join working. If your environment runs on Immutable Infrastructure (Alauda OS on Huawei DCS, VMware vSphere, or Huawei Cloud Stack), node provisioning is image-based and this preprocessing does not apply; see instead. +This page applies to nodes running a **traditional operating system** such as Kylin Linux Advanced Server, RHEL, or Ubuntu, which provisions over SSH. Several of the checks below — for example the SSH user and the `/etc/ssh/sshd_config` settings — exist to keep the SSH-based node join working. If your cluster uses Alauda OS, the node preprocessing steps on this page do not apply. Follow in the Immutable Infrastructure documentation instead. ::: ## Supported OS and Kernel Versions \{#supported_os_and_kernels} The following table lists the supported operating systems, their validated versions, and the corresponding tested kernel versions. -The platform enforces strict version matching policies for official support: +The platform enforces the version-matching granularity declared in the support list: -- **OS Version (x.y.z)**: Patch versions (`z`) can vary, but major and minor versions (`x` and `y`) must strictly match the validated versions. Modifying `x` or `y` is not officially supported. -- **Kernel Version (x.y.z-build)**: The build suffix (`build`) can vary, but the core kernel version (`x.y.z`) must strictly match the tested versions. Modifying `x.y.z` is not officially supported. +- **OS version**: Use the distribution release listed below. A different major or minor release is not officially supported unless it is also listed. +- **Kernel version**: Use an official kernel supplied by the operating system vendor. When the list gives an exact `x.y.z-build` value, the build suffix can vary but `x.y.z` must match. When the list gives a kernel series, use a kernel from that series that is validated for the installed patch. Do not assume that an arbitrary newer kernel is supported. :::info -- Only the kernel version shipped with the official operating system is supported. If the OS, kernel version, or CPU architecture does not meet the requirements, please contact technical support. -- Kylin V10, V10-SP1, and V10-SP2 have known kernel issues that may cause **NodePort network access failures**, it is recommended to upgrade to **Kylin V10-SP3**. -::: - -:::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, 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 -provided immutable operating system images or platform images, follow the CPU baseline requirements documented for those images. +- For clusters running Kubernetes 1.35 or later, nodes must use cgroup v2 and Linux kernel 5.8 or later. Use only the OS and kernel combinations listed below that are validated for the installed patch. +- `x86-64-v2` is a CPU instruction set baseline, but does not impose it as a universal requirement on x86 nodes running a user-provided traditional operating system. The CPU must still meet the requirements of the selected operating system and the components to be deployed. If compatibility cannot be confirmed, contact technical support. ::: ### x86 - - RHEL 7.8: `3.10.0-1127.el7.x86_64` - - RHEL 8.0: `4.18.0-80.el8.x86_64` - - RHEL 8.6: `4.18.0-372.9.1.el8.x86_64` - - RHEL 8.10: `4.18.0-553` - RHEL 9.6: `5.14.0-570.12.1` - - **Note:** RHEL 7.8 does not support **Calico Vxlan IPv6**. - - - - - CentOS 7.6 to 7.9: `3.10.0-1127` and `3.10.0-1160` - - **Note:** CentOS does not support **Calico Vxlan IPv6**. - - Ubuntu 20.04 LTS: `5.4.0-135-generic` - Ubuntu 22.04 LTS: `5.15.0-56-generic` **Note:** Ubuntu HWE (Hardware Enablement) versions are not supported. - - Kylin V10 SP3: `4.19.90-52.22.v2207.ky10.x86_64` + - Kylin Linux Advanced Server V11: official kernel from the 6.6 series validated for the installed patch + + **Note:** Flannel is not supported on Kylin Linux Advanced Server V11. @@ -65,9 +48,9 @@ For -provided immutable operating system images or p - - Kylin V10 SP3: `4.19.90-52.22.v2207.ky10.aarch64` + - Kylin Linux Advanced Server V11: official kernel from the 6.6 series validated for the installed patch - **Note:** ARM architecture only supports `Kunpeng 920`. For other models, please contact technical support. + **Note:** ARM architecture only supports `Kunpeng 920`, and Flannel is not supported. For other CPU models, please contact technical support. @@ -100,9 +83,7 @@ The following is the list of checks: - **OS and Kernel** - ✅ The machine's grub boot configuration must have the `transparent_hugepage=never` parameter. - - ✅ CentOS 7.x system machine's grub boot configuration must have the `cgroup.memory=nokmem` parameter. - ✅ Check whether the kernel modules `ip_vs`, `ip_vs_rr`, `ip_vs_wrr`, and `ip_vs_sh` are enabled. - - ⚠️ When the kernel version is lower than 4.19.0 (or RHEL is lower than 4.18.0), check whether the kernel modules `nf_conntrack_ipv4` and (for IPv6) `nf_conntrack_ipv6` are enabled. - ⚠️ If the `global` cluster plans to use `Kube-OVN` CNI, the kernel modules `geneve` and `openvswitch` must be enabled. - ✅ Disable apparmor/selinux and firewall. - ✅ Disable `swap` . @@ -111,7 +92,7 @@ The following is the list of checks: - ✅ The node's SSH user has `root` privileges and can use `sudo` without the password. - ✅ The `UseDNS` parameter in `/etc/ssh/sshd_config` must be set to `no`. - ✅ Set the `UsePAM` parameter in `/etc/ssh/sshd_config` to `no` before adding the node, then restart `sshd`. PAM session policies (such as a forced password change, `pam_access`, `faillock`, or `pam_limits`) can otherwise block the SSH-based node join. After the node reaches the `Ready` state, you can restore `UsePAM yes`. On SELinux-enforcing systems that use password authentication, `UsePAM no` can itself break SSH login; use key-based authentication in that case. - - ✅ `systemctl show --property=DefaultTasksMax` must return `infinity`; a low limit (such as the `512` default on RHEL 7 / CentOS 7) makes busy containers fail to create threads. If it is not `infinity`, set `DefaultTasksMax=infinity` in `/etc/systemd/system.conf` and run `systemctl daemon-reexec`. + - ✅ `systemctl show --property=DefaultTasksMax` must return `infinity`; a low limit can make busy containers fail to create threads. If it is not `infinity`, set `DefaultTasksMax=infinity` in `/etc/systemd/system.conf` and run `systemctl daemon-reexec`. - **Node Network** - ✅ `hostname` must comply with the following rules: @@ -165,7 +146,7 @@ Before installation, applications may already be running in the docker/nerdctl/c The following commands can be used for reference. - + **Check:** ```bash for x in \ diff --git a/docs/en/overview/architecture.mdx b/docs/en/overview/architecture.mdx index 29a3c7ca5..276a44826 100644 --- a/docs/en/overview/architecture.mdx +++ b/docs/en/overview/architecture.mdx @@ -6,7 +6,7 @@ weight: 30 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. -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. +Use the diagram as a high-level view of this model. The architecture details below clarify boundaries that are not visible in the diagram. ![Architecture overview](./assets/arch-overview.svg) diff --git a/docs/en/overview/availability-and-recovery.mdx b/docs/en/overview/availability-and-recovery.mdx index bc2d3095d..71fc0c15a 100644 --- a/docs/en/overview/availability-and-recovery.mdx +++ b/docs/en/overview/availability-and-recovery.mdx @@ -74,7 +74,7 @@ For topology-level planning, see [High Availability Baseline](#high-availability 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: +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. diff --git a/docs/en/overview/cluster-management-models.mdx b/docs/en/overview/cluster-management-models.mdx index 24a5ac1d3..bd3b7df53 100644 --- a/docs/en/overview/cluster-management-models.mdx +++ b/docs/en/overview/cluster-management-models.mdx @@ -29,10 +29,10 @@ Existing third-party Kubernetes environments are covered under [Kubernetes Owner Control-plane topology explains where Kubernetes control plane components run. -| Topology | Meaning | 4.3 boundary | +| Topology | Meaning | Support 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. | +| 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`). | See [About Hosted Control Plane](../configure/hosted_control_planes/overview.mdx) for current maturity, operating system, connectivity, and production-use boundaries. | 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. @@ -70,7 +70,7 @@ After onboarding, expected day-2 management is treated as the same at the Overvi 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. Treat this range as an onboarding gate, not as a complete product validation matrix for every Kubernetes version, provider, operation, or Extension. +Use the product-supported onboarding range in the [Kubernetes Support Matrix](./kubernetes-support-matrix.mdx) to confirm Kubernetes-version eligibility. Check provider prerequisites and exact Extension compatibility separately. For the exact matrix and upgrade relationship, see [Kubernetes Support Matrix](./kubernetes-support-matrix.mdx) and [Version and Lifecycle](./version-and-lifecycle.mdx). diff --git a/docs/en/overview/core-and-extensions.mdx b/docs/en/overview/core-and-extensions.mdx index a77db4c46..402150fad 100644 --- a/docs/en/overview/core-and-extensions.mdx +++ b/docs/en/overview/core-and-extensions.mdx @@ -43,23 +43,12 @@ 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. +For a specific Operator or Cluster Plugin version, use the Customer Portal `ACP compatible versions` field as the compatibility authority. The exact Extension version must list the target release as compatible. -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. +Use product documentation for each Extension to understand capabilities, installation steps, upgrade steps, limitations, known issues, supported Kubernetes versions, architectures, providers, and cluster models. Release notes are useful for version changes, but they are not the primary compatibility source for every specific Extension version. The Kubernetes support matrix describes platform and Kubernetes version relationships and the [default product-validation scope for third-party clusters](./kubernetes-support-matrix.mdx#third-party-cluster-product-supported-onboarding-range); it is not an Extension compatibility matrix. 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: diff --git a/docs/en/overview/glossary.mdx b/docs/en/overview/glossary.mdx index a65d800ea..a51ad5d78 100644 --- a/docs/en/overview/glossary.mdx +++ b/docs/en/overview/glossary.mdx @@ -23,7 +23,7 @@ Use this glossary to interpret platform-wide terms in . F | 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) | +| 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`). | [About Hosted Control Plane](../configure/hosted_control_planes/overview.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) | diff --git a/docs/en/overview/kubernetes-support-matrix.mdx b/docs/en/overview/kubernetes-support-matrix.mdx index 71f6c77d7..49c4f29f8 100644 --- a/docs/en/overview/kubernetes-support-matrix.mdx +++ b/docs/en/overview/kubernetes-support-matrix.mdx @@ -14,64 +14,54 @@ For the conceptual lifecycle guidance, see [Version and Lifecycle](./version-and | --- | --- | | 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. | +| Third-party cluster product-tested scope | The product-supported Kubernetes onboarding range and the default capabilities covered by product validation on third-party clusters. | ## Version Support Matrix \{#version-support-matrix} The following table shows the Kubernetes version support for each release. :::info -The table lists 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. +This documentation is maintained for a minor release line and does not publish a separate documentation set for each patch release. The table reflects the Kubernetes minors supported by the current documented state of that release line. If a later patch release adds another Kubernetes minor, the same row and its compatible-version range are updated. Use the target versions offered by the platform and release-specific artifacts for exact Kubernetes builds. -Starting from 4.1, each release supports only one Kubernetes version for cluster creation. This keeps new cluster creation consistent and simplifies upgrade planning. +At any point in the release line, create clusters only with a Kubernetes target offered and validated by the installed patch. The minor-level row can expand when a later patch adds another validated Kubernetes minor. ::: | Version | Supported for cluster creation | Compatible Versions | | --- | --- | --- | +| 4.4 | 1.35 | 1.35, 1.34, 1.33, 1.32 | | 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 | -## 4.3 Notes +## Product-Tested Scope for Third-Party Clusters \{#third-party-cluster-product-supported-onboarding-range} -- 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. +### Product-Supported Kubernetes Range -For upgrade planning, see [Upgrade Overview](../upgrade/overview.mdx) and [Pre-Upgrade](../upgrade/pre-upgrade.mdx). +Third-party Kubernetes clusters have completed product onboarding validation for Kubernetes 1.28 through 1.35, inclusive. Kubernetes minors outside this range are not declared product-supported for third-party cluster onboarding. -## Third-Party Cluster Accepted Onboarding Range +The current product-tested range applies to 4.3 and later releases that provide third-party cluster onboarding. It is maintained as one shared range instead of being copied into each release row, and is updated when product validation covers additional Kubernetes minors. -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. +The product validation program continues to test additional Kubernetes minor versions. A version that is planned for testing or still being evaluated is not product-supported. After a version completes product validation, the range on this page is updated. Use the currently published range as the authority for product support. 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. +### Default Validation Scope -When onboarding third-party clusters, also check: +For third-party clusters within the published Kubernetes range, default product validation covers: -- 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. +- Core Kubernetes workload and resource operations, such as creating and managing Deployments. +- [Extend](../extend/index.mdx) workflows used to install and upgrade Operators and Cluster Plugins. +- ClickHouse-based logging installed and upgraded through Extend. +- VictoriaMetrics-based monitoring installed and upgraded through Extend. -For model boundaries, see [Cluster Management Models](./cluster-management-models.mdx). +Extend is included in the default validation scope because the validated logging and monitoring capabilities depend on Extend for installation and upgrade. Customers can also use Extend to install other capabilities when the exact Operator or Cluster Plugin declares compatibility with the target environment. -## Extend Baseline +Default product validation does not mean that every specific Operator or Cluster Plugin is validated. For any other Operator or Cluster Plugin, check its product documentation and Customer Portal compatibility metadata, or contact technical support. -For 4.3, product validation for the default Extend baseline covers these capability areas: +The published Kubernetes range and default validation scope do not replace the prerequisites of the selected onboarding method. Follow [Third-Party Cluster Onboarding](../configure/clusters/managed/overview.mdx) and the applicable Import, Register, or provider-specific procedure to verify connectivity, credentials, and environment-specific preparation. -- 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). +For model boundaries, see [Cluster Management Models](./cluster-management-models.mdx). For upgrade planning, see [Upgrade Overview](../upgrade/overview.mdx) and [Pre-Upgrade](../upgrade/pre-upgrade.mdx). ## Upgrade Requirements diff --git a/docs/en/overview/learn-more.mdx b/docs/en/overview/learn-more.mdx index 81e827a46..0b28c4855 100644 --- a/docs/en/overview/learn-more.mdx +++ b/docs/en/overview/learn-more.mdx @@ -35,7 +35,7 @@ Choose the next task path for installation, cluster operations, application deli | 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/hosted_control_planes/overview.mdx) | +| Evaluate Hosted Control Plane (HCP). | [About Hosted Control Plane](../configure/hosted_control_planes/overview.mdx) | | Onboard existing third-party Kubernetes environments by import. | [Import Third-Party 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) | diff --git a/docs/en/overview/platform-model.mdx b/docs/en/overview/platform-model.mdx index 51eecced2..2b438200c 100644 --- a/docs/en/overview/platform-model.mdx +++ b/docs/en/overview/platform-model.mdx @@ -40,9 +40,7 @@ For onboarding workflows, see [Third-Party Cluster Onboarding](../configure/clus 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/hosted_control_planes/overview.mdx). +For current HCP maturity, operating system, connectivity, production-use boundaries, and tasks, see [About Hosted Control Plane](../configure/hosted_control_planes/overview.mdx). ## Projects And Namespaces diff --git a/docs/en/overview/version-and-lifecycle.mdx b/docs/en/overview/version-and-lifecycle.mdx index dfe344afc..56e08b22d 100644 --- a/docs/en/overview/version-and-lifecycle.mdx +++ b/docs/en/overview/version-and-lifecycle.mdx @@ -10,26 +10,27 @@ Use [Kubernetes Support Matrix](./kubernetes-support-matrix.mdx) for the exact K ## Product And Kubernetes Versions -For 4.3: +The Kubernetes support matrix separates three decisions: which Kubernetes targets can be used for platform-managed cluster creation, which workload-cluster versions satisfy the `global` cluster upgrade prerequisite, and which Kubernetes minors are product-supported for third-party cluster onboarding. Do not infer one range from another. -- 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 4.3 and later, workload clusters only need to remain within the documented Compatible Versions 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. + +Exact Kubernetes builds and creation targets come from versions offered by the installed platform patch and release-specific artifacts, not from this lifecycle overview. 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. +Use [Product-Tested Scope for Third-Party Clusters](./kubernetes-support-matrix.mdx#third-party-cluster-product-supported-onboarding-range) for the current product-supported Kubernetes range, the ongoing validation policy, and the default validation scope. + +The product-tested onboarding range is shared by 4.3 and later releases that provide third-party cluster onboarding. It is maintained independently from the release-specific creation and Compatible Versions rows, and the shared range is updated when product validation expands. 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. +- Support for every 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. +The published Kubernetes range establishes version eligibility. Follow [Third-Party Cluster Onboarding](../configure/clusters/managed/overview.mdx) and the selected Import, Register, or provider-specific procedure for connectivity, credentials, and environment-specific preparation. For cluster model boundaries, see [Cluster Management Models](./cluster-management-models.mdx). @@ -39,8 +40,8 @@ Read runtime, OS, CRI, and CPU architecture information by responsibility bounda | 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. | +| lifecycle-managed environments | The platform installs and manages containerd. The exact runtime build follows the installed patch and is not a stable minor-release documentation value. For immutable nodes, use the patch-specific OS Support Matrix. | +| HCP environments | Use [About Hosted Control Plane](../configure/hosted_control_planes/overview.mdx) for the current maturity, runtime, operating system, connectivity, and production-use boundaries. | | 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 Alauda OS 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. | @@ -74,7 +75,7 @@ When reading Overview, release notes, or component documentation, treat maturity | 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). +For current HCP maturity and evaluation boundaries, see [About Hosted Control Plane](../configure/hosted_control_planes/overview.mdx). 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 diff --git a/docs/en/ui/cli_tools/ac/upgrading-clusters.md b/docs/en/ui/cli_tools/ac/upgrading-clusters.md index f3dea2e5b..0285e86fb 100644 --- a/docs/en/ui/cli_tools/ac/upgrading-clusters.md +++ b/docs/en/ui/cli_tools/ac/upgrading-clusters.md @@ -282,13 +282,14 @@ When `ac adm upgrade status --cluster=` shows `AdminAckRequired` in `Fa kubectl -n cpaas-system get configmap admin-gates -o yaml ``` -2. For ACP 4.4 upgrades to Kubernetes 1.35, complete the [ACP 4.4 Kubernetes 1.35 node readiness checks](/upgrade/pre-upgrade.mdx#kubernetes-135-node-readiness) on every production node in the target cluster. +2. If the target release is ACP 4.4 or later, upgrades the cluster to Kubernetes 1.35 or later, and `admin-gates` reports a node-readiness acknowledgement key, complete the [Kubernetes 1.35 or later node readiness checks](/upgrade/pre-upgrade.mdx#kubernetes-135-node-readiness) on every production node in the target cluster. The first gate introduced for this requirement is `ack-4.4-kubernetes-1.35-kernel-update`; treat it as an example because a later target release can provide a different key. -3. Write the acknowledgement to the global-side `admin-acks` ConfigMap: +3. After completing the gate requirements, copy the applicable key from `admin-gates` and write it to the global-side `admin-acks` ConfigMap: ```bash + ACK_KEY='' kubectl -n cpaas-system patch configmap admin-acks --type merge \ - -p '{"data":{"ack-4.4-kubernetes-1.35-kernel-update":"true"}}' + -p "{\"data\":{\"${ACK_KEY}\":\"true\"}}" ``` 4. Confirm that the preflight check passes: diff --git a/docs/en/upgrade/index.mdx b/docs/en/upgrade/index.mdx index c88d89164..f5f49d068 100644 --- a/docs/en/upgrade/index.mdx +++ b/docs/en/upgrade/index.mdx @@ -7,7 +7,7 @@ weight: 20 This document will provide all the information regarding the upgrading of . -This section documents upgrades for environments running on a **traditional operating system**. If your environment runs on Immutable Infrastructure (Alauda OS on Huawei DCS, VMware vSphere, or Huawei Cloud Stack): +This section documents upgrades for environments running on a **traditional operating system**. If your environment uses Alauda OS: - Upgrade the `global` cluster: - Upgrade workload clusters: diff --git a/docs/en/upgrade/overview.mdx b/docs/en/upgrade/overview.mdx index b3f48552d..2abc567b1 100644 --- a/docs/en/upgrade/overview.mdx +++ b/docs/en/upgrade/overview.mdx @@ -3,7 +3,7 @@ weight: 10 --- # Overview -ACP 4.3 uses a Cluster Version Operator (CVO)-based workflow for cluster upgrades. +Starting with ACP 4.3, cluster upgrades use the Cluster Version Operator (CVO)-based workflow. In the Web Console, the upgrade request now follows a two-step flow: review RPCH items first, and then submit the upgrade request in a separate confirmation step. @@ -12,7 +12,7 @@ When moving the platform to a new ACP Distribution Version, the upgrade normally 1. Upgrade the global tier to the target Distribution Version by following the validated global-cluster procedure, including artifact preparation and preflight checks. 2. After the global tier reaches the target Distribution Version, upgrade workload clusters from the supported workload-cluster entry point and observe cluster status until each target cluster reaches the same Distribution Version. -A workload cluster can be upgraded only to a Distribution Version that the global tier has already reached. In environments with **global disaster recovery (DR)**, this means both the standby and primary global clusters must reach the target Distribution Version before workload clusters are upgraded to that Distribution Version. This sequencing rule does not replace the Compatible Versions prerequisite: before the global tier is upgraded to ACP 4.3, workload clusters must remain within the ACP 4.3 compatible Kubernetes version range. +A workload cluster can be upgraded only to a Distribution Version that the global tier has already reached. In environments with **global disaster recovery (DR)**, this means both the standby and primary global clusters must reach the target Distribution Version before workload clusters are upgraded to that Distribution Version. Before upgrading the global tier, verify that every workload cluster is within the target Distribution Version's **Compatible Versions** in the [Kubernetes Support Matrix](../overview/kubernetes-support-matrix.mdx#version-support-matrix). This prerequisite is separate from the sequencing rule. ## Key Concepts @@ -73,9 +73,9 @@ On **Immutable Infrastructure** clusters (DCS, vSphere, HCS), Kube-OVN is driven ## Post-upgrade Security Hardening -After the global cluster and all workload clusters have reached ACP 4.3, complete PKCE security hardening by following [Disabling the PKCE Plain Method](/security/platform_security_configurations/disable_pkce_plain_method.mdx). +If the environment is upgrading from a release earlier than ACP 4.3 and has not completed PKCE security hardening, complete [Disabling the PKCE Plain Method](/security/platform_security_configurations/disable_pkce_plain_method.mdx) after the global cluster and all workload clusters reach ACP 4.4. -After the global cluster reaches ACP 4.3, complete the required L5 plugin compatibility upgrades in [Upgrade the global cluster](./upgrade_global_cluster.mdx). +If the environment is upgrading from a release earlier than ACP 4.3, complete the required L5 plugin compatibility upgrades in [Upgrade the global cluster](./upgrade_global_cluster.mdx). ## Related Documentation diff --git a/docs/en/upgrade/pre-upgrade.mdx b/docs/en/upgrade/pre-upgrade.mdx index cdf524ca2..6536c2e33 100644 --- a/docs/en/upgrade/pre-upgrade.mdx +++ b/docs/en/upgrade/pre-upgrade.mdx @@ -6,21 +6,21 @@ weight: 20 **Supported upgrade paths:** -* **From `4.0` → `4.3`** -* **From `4.1` → `4.3`** -* **From `4.2` → `4.3`** +At the minor-release policy level, ACP 4.1, 4.2, and 4.3 are within the n-3 direct-upgrade window for the ACP 4.4 release line. This policy does not make every source patch eligible for every target patch. -Before starting, ensure your current platform version is within the supported upgrade range. +Upgrade only to a target 4.4.x version that the platform offers for the current source patch. After the target `ProductManifest` is registered, confirm that the target appears in `availableUpdates` in the Web Console or `ac adm upgrade`, and confirm that the `VersionUpgradePath` preflight check passes. If no 4.4.x target is offered, use a later 4.4.x target that includes the current source patch or first follow an intermediate target offered by the platform. Do not use an explicit upgrade request or disable `VersionUpgradePath` to bypass an unsupported source-to-target combination. + +ACP 4.0.x is outside the direct-upgrade window for ACP 4.4. Follow the intermediate upgrade chain offered by the platform, and verify `availableUpdates` and `VersionUpgradePath` at every hop. :::info -On Immutable Infrastructure (Huawei DCS, VMware vSphere, Huawei Cloud Stack, and bare-metal immutable OS), the supported upgrade paths above apply to the ACP Distribution Version, which still moves directly to the target version through the Cluster Version Operator. When the target ACP version is more than one Kubernetes minor above the cluster's current version, the Kubernetes upgrade requires additional pre-staging of intermediate-version artifacts. See before starting the upgrade window. +For clusters that use Alauda OS, the ACP Distribution Version must follow the same CVO-offered source-to-target path. When the target ACP version is more than one Kubernetes minor above the cluster's current version, the Kubernetes upgrade requires additional pre-staging of intermediate-version artifacts. See before starting the upgrade window. ::: ## Important Notes * Ensure the directory `/cpaas/minio` on the control plane nodes of global cluster has at least **120 GB** of free disk space. -* Before upgrading the global tier to ACP 4.3, all workload clusters must remain within the ACP 4.3 **Compatible Versions** documented in [Kubernetes Support Matrix](/overview/kubernetes-support-matrix.html). -* If any workload cluster is outside that compatible range, upgrade that workload cluster first until it enters the ACP 4.3 compatible range before upgrading the global tier. +* Before upgrading the global tier, verify that all workload clusters remain within the target Distribution Version's **Compatible Versions** documented in [Kubernetes Support Matrix](/overview/kubernetes-support-matrix.html). +* If any workload cluster is outside the target compatible range, upgrade that workload cluster first until it enters the range before upgrading the global tier. * A workload cluster can be upgraded only to a Distribution Version that the global tier has already reached. ## Verify Module Stability Before You Upgrade \{#module-stability-self-check} @@ -42,9 +42,9 @@ kubectl get clustermodule -o jsonpath='{.status.base.deployStatus}{"\n Every module `PHASE` must be `Running`, and `deployStatus` must not be `Upgrading`, `DeployFailed`, or `UpgradeFailed`. If a module is still upgrading, wait for it to reach `Running`; if a module is `Failed` or `Blocked`, resolve it before you request the cluster upgrade. -## ACP 4.4 Kubernetes 1.35 Node Readiness \{#kubernetes-135-node-readiness} +## Kubernetes 1.35 or Later Node Readiness \{#kubernetes-135-node-readiness} -ACP 4.4 upgrades clusters to Kubernetes 1.35. Before you acknowledge the Kubernetes 1.35 administrator gate, verify every production node that will run the target cluster. +If the target release is ACP 4.4 or later, upgrades the cluster to Kubernetes 1.35 or later, and reports an administrator acknowledgement gate for node readiness, verify every production node that will run the target cluster before acknowledging the gate. Run the checks through SSH on each node, or use an approved node shell. For example: @@ -117,17 +117,6 @@ Publish a cluster plugin package once to the global tier. Publish an operator pa If a required package is missing or is not ready, CVO stalls the cluster upgrade. You can publish the package after the block occurs; CVO detects the newly available package and continues the existing upgrade request automatically. ::: -:::warning -If you are upgrading **from ACP 4.0 to ACP 4.3** and ** Build of TopoLVM** is installed on any target clusters, upload the TopoLVM package to those clusters before you proceed with the upgrade. This step is not required when upgrading from ACP 4.1 or ACP 4.2. You can specify multiple target clusters in `--clusters`, separated by commas. - -```bash -violet push \ - --platform-address "https://example.com" \ - --platform-token "" \ - --clusters "cluster-a,cluster-b" -``` -::: - :::warning Starting with v4.2, we introduced a new plugin named **Alauda Container Platform Log Essentials**. If you previously installed the log storage plugin, you also have to upload that plugin before starting the upgrade. ::: diff --git a/docs/en/upgrade/upgrade_global_cluster.mdx b/docs/en/upgrade/upgrade_global_cluster.mdx index 0f2e617d8..e03f52958 100644 --- a/docs/en/upgrade/upgrade_global_cluster.mdx +++ b/docs/en/upgrade/upgrade_global_cluster.mdx @@ -5,7 +5,7 @@ weight: 30 # Upgrade the global cluster -This page covers the **traditional operating system** path for the `global` cluster. If your `global` cluster runs on Immutable Infrastructure (Alauda OS on Huawei DCS, VMware vSphere, or Huawei Cloud Stack), the Kubernetes step lives in the immutable infrastructure documentation — see . The Core, Aligned, and Agnostic steps described on this page still apply to immutable-OS clusters; only the way Kubernetes is rolled out differs. +This page covers the **traditional operating system** path for the `global` cluster. If your `global` cluster uses Alauda OS, the Kubernetes step lives in the Immutable Infrastructure documentation — see . The Core, Aligned, and Agnostic steps described on this page still apply to immutable-OS clusters; only the way Kubernetes is rolled out differs. consists of a **global** cluster and one or more @@ -13,9 +13,9 @@ workload clusters. To move the platform to a new ACP Distribution Version, upgrade the global tier to the target Distribution Version first, and then upgrade workload clusters to that same Distribution Version. -ACP 4.3 uses a CVO-based workflow for cluster upgrades. A typical `global` cluster upgrade includes artifact preparation, preflight checks, upgrade request, and status observation. +Cluster upgrades use the CVO-based workflow. A typical `global` cluster upgrade includes artifact preparation, preflight checks, upgrade request, and status observation. -Before upgrading the `global` cluster to ACP 4.3, verify that every workload cluster is on a compatible Kubernetes version. For ACP 4.3, the compatible versions are 1.34, 1.33, 1.32, and 1.31. This prerequisite is separate from the broader third-party cluster management range. +Before upgrading the `global` cluster, verify that every workload cluster is within the target release's **Compatible Versions** in the [Kubernetes Support Matrix](/overview/kubernetes-support-matrix.html). This prerequisite is separate from the third-party cluster onboarding range. This Compatible Versions prerequisite applies whether or not the environment uses global DR. Global DR changes the procedure used to upgrade the global tier, but it does not change the requirement that workload clusters must remain within the compatible Kubernetes version range before the global tier is upgraded to the target Distribution Version. @@ -158,7 +158,7 @@ The default annotation key is `config.cpaas.io/exempt-for-ver`. ```bash kubectl annotate resourcepatches \ - config.cpaas.io/exempt-for-ver=4.3.0 \ + config.cpaas.io/exempt-for-ver= \ --overwrite ``` @@ -174,7 +174,7 @@ kubectl -n cpaas-system get cvsh global \ | Check | What it validates | How to resolve | | --- | --- | --- | | `KubernetesVersionSupported` | The cluster's Kubernetes version is within the target release's supported range. | If it is below the supported range, upgrade the cluster's Kubernetes into that range first — see [Kubernetes Support Matrix](/overview/kubernetes-support-matrix.html). | -| `VersionUpgradePath` | The current version can reach the requested target through a supported upgrade path. | Confirm the current version is a supported source for the target release; upgrade to an intermediate supported version first if it is not. | +| `VersionUpgradePath` | The current patch can reach the requested target patch through a supported upgrade edge. | Use only a target listed in `availableUpdates`. If no suitable target is offered, choose a later target that includes the current source patch or first follow an intermediate target offered by the platform. Do not disable this check to force the upgrade. | | `ClusterRunning` | The cluster is healthy and reconciled. | Check the cluster with `kubectl get clusterview global` and resolve any unhealthy node or component before retrying. | | `DockerRuntimeUnsupported` | No node still uses the unsupported Docker runtime. | Migrate the affected nodes to `containerd` before upgrading. | | `ClusterModuleStable`, `ModuleInfoStable` | Installed Core and Aligned modules are stable (`Running`), not mid-deploy or mid-upgrade. | See [Verify Module Stability Before You Upgrade](./pre-upgrade.mdx#module-stability-self-check). | @@ -189,19 +189,20 @@ Inspect the current gates: kubectl -n cpaas-system get configmap admin-gates -o yaml ``` -For ACP 4.4 upgrades to Kubernetes 1.35, the built-in gate key is: +If the target release is ACP 4.4 or later, upgrades the cluster to Kubernetes 1.35 or later, and `admin-gates` reports a node-readiness acknowledgement key, complete the [Kubernetes 1.35 or later node readiness checks](./pre-upgrade.mdx#kubernetes-135-node-readiness) on every production node. + +Use the acknowledgement key provided by the target release. The first gate introduced for this requirement, for the ACP 4.4 and Kubernetes 1.35 target, is: ```text ack-4.4-kubernetes-1.35-kernel-update ``` -Before acknowledging this gate, complete the [ACP 4.4 Kubernetes 1.35 node readiness checks](./pre-upgrade.mdx#kubernetes-135-node-readiness) on every production node. - -After the node checks pass, write the acknowledgement: +Treat this key as an example; a later target release can provide a different key. After the node checks pass, copy the applicable key from `admin-gates` and write it to `admin-acks`: ```bash +ACK_KEY='' kubectl -n cpaas-system patch configmap admin-acks --type merge \ - -p '{"data":{"ack-4.4-kubernetes-1.35-kernel-update":"true"}}' + -p "{\"data\":{\"${ACK_KEY}\":\"true\"}}" ``` Run preflight again: @@ -217,7 +218,7 @@ kubectl -n cpaas-system get cvsh global \ -o jsonpath='{range .status.preflight.checks[?(@.name=="AdminAckRequired")]}{.state}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}' ``` -If temporary troubleshooting requires specific checks to be disabled, configure `cpaas-system/cvo-config`: +Do not disable `VersionUpgradePath`, `KubernetesVersionSupported`, or `AdminAckRequired` to force an unsupported upgrade. If technical support instructs you to disable a non-version check temporarily, configure only the specified check in `cpaas-system/cvo-config`. For example: ```yaml apiVersion: v1 @@ -229,7 +230,6 @@ data: preflight: | disabled: - ResourcePatchUpgradeable - - VersionUpgradePath ``` ### Deploy the cluster version operator \{#deploy-the-cluster-version-operator} @@ -272,7 +272,7 @@ After the cluster version operator is deployed, request the upgrade through one ac adm upgrade --cluster=global --to-latest # Request upgrade to a specific target version - ac adm upgrade --cluster=global --to=4.3.0 + ac adm upgrade --cluster=global --to= # Show summary, preflight, and stage progress for the global cluster upgrade ac adm upgrade status --cluster=global @@ -290,7 +290,7 @@ After the cluster version operator is deployed, request the upgrade through one kubectl patch cvsh global -n cpaas-system --type merge -p '{ "spec": { "desiredUpdate": { - "version": "4.3.0" + "version": "" } } }' @@ -307,7 +307,7 @@ After the cluster version operator is deployed, request the upgrade through one ```yaml spec: desiredUpdate: - version: 4.3.0 + version: ``` @@ -406,9 +406,9 @@ If you skipped pushing an Agnostic plugin during pre-upgrade and the Marketplace children="Upgrade Alauda DevOps" /> -- After all workload clusters have also reached ACP 4.3, complete PKCE hardening by following [Disabling the PKCE Plain Method](/security/platform_security_configurations/disable_pkce_plain_method.mdx). +- If the source release is earlier than ACP 4.3 and PKCE hardening has not already been completed, wait until all workload clusters reach ACP 4.4, then follow [Disabling the PKCE Plain Method](/security/platform_security_configurations/disable_pkce_plain_method.mdx). -- ACP 4.3 fixes an API authentication issue where specific APIs could previously be accessed without authentication. After the global cluster reaches ACP 4.3, upgrade the following L5 plugins to ACP v4.3-compatible versions. Otherwise, their UI pages may fail to open: +- When upgrading from a release earlier than ACP 4.3, an API authentication change introduced in ACP 4.3 requires the following L5 plugins to be upgraded to versions compatible with the target ACP 4.4 release. Otherwise, their UI pages may fail to open: - `Alauda DevOps v3` - `Alauda AI Essentials` - `Alauda Hyperflux` diff --git a/docs/en/upgrade/upgrade_workload_cluster.mdx b/docs/en/upgrade/upgrade_workload_cluster.mdx index 7be481075..3f53090b5 100644 --- a/docs/en/upgrade/upgrade_workload_cluster.mdx +++ b/docs/en/upgrade/upgrade_workload_cluster.mdx @@ -5,12 +5,12 @@ weight: 30 # Upgrade Workload Clusters -This page covers the **traditional operating system** path for workload clusters. For workload clusters that run on Immutable Infrastructure (Alauda OS on Huawei DCS, VMware vSphere, or Huawei Cloud Stack), the Kubernetes step lives in the immutable infrastructure documentation — see . The Core, Aligned, and Agnostic steps described on this page still apply to immutable-OS clusters; only the way Kubernetes is rolled out differs. +This page covers the **traditional operating system** path for workload clusters. For workload clusters that use Alauda OS, the Kubernetes step lives in the Immutable Infrastructure documentation — see . The Core, Aligned, and Agnostic steps described on this page still apply to immutable-OS clusters; only the way Kubernetes is rolled out differs. Workload clusters can be upgraded after the global tier has already reached the target ACP Distribution Version. The global tier does not need to be upgraded again if it is already at that Distribution Version. -ACP 4.3 uses the same CVO-based workflow for workload clusters as for the `global` cluster: confirm prerequisites, run preflight checks, request the upgrade, and observe execution. This workflow has two additional rules: +Workload cluster upgrades use the same CVO-based workflow as the `global` cluster: confirm prerequisites, run preflight checks, request the upgrade, and observe execution. This workflow has two additional rules: - If the platform uses **global DR**, both the standby and primary global clusters must reach the target Distribution Version before any workload cluster is upgraded to that Distribution Version. - The target version normally becomes available for a workload cluster only after the global tier has already reached that same Distribution Version. @@ -105,7 +105,7 @@ Request the upgrade through one of the following entry points. The two entry poi ac adm upgrade --cluster= --to-latest # Request upgrade to a specific target version - ac adm upgrade --cluster= --to=4.3.0 + ac adm upgrade --cluster= --to= ``` ACP CLI submits the requested target for the specified workload cluster. Whether the upgrade can proceed is still determined by the cluster's available upgrade targets and the upgrade controller's preflight checks. @@ -173,9 +173,9 @@ kubectl -n cpaas-system get cvsh \ -## After All Workload Clusters Reach ACP 4.3 +## Complete Security Hardening When Upgrading From Before ACP 4.3 -After all workload clusters reach ACP 4.3, complete PKCE security hardening by following [Disabling the PKCE Plain Method](/security/platform_security_configurations/disable_pkce_plain_method.mdx). +If the source release is earlier than ACP 4.3 and PKCE hardening has not already been completed, wait until all workload clusters reach ACP 4.4, then follow [Disabling the PKCE Plain Method](/security/platform_security_configurations/disable_pkce_plain_method.mdx). ## Related Documentation