From 6bcd4ae535049de5d42fc35b9d72259220e755eb Mon Sep 17 00:00:00 2001 From: Shaw Ho Date: Fri, 31 Jul 2026 14:15:47 +0800 Subject: [PATCH 01/17] [release-4.4] docs: clarify OCI Connector pull secret requirements (#981) (#984) * docs: clarify OCI Connector pull secret requirements * docs: remove Connector version references --------- (cherry picked from commit 565ca97fccc9ee09511e09ed43b289a9549e12b8) Signed-off-by: Xiaoxi He --- .../application_workloads/cronjob_create.mdx | 8 ++ .../deamonset_create.mdx | 6 ++ .../deployment_create.mdx | 18 +++- .../statefulset_create.mdx | 6 ++ .../create_applications/image_app.mdx | 8 +- .../how_to/sa_imagepullsecret.mdx | 84 +++++++++++++++++++ 6 files changed, 128 insertions(+), 2 deletions(-) diff --git a/docs/en/developer/building_application/application_workloads/cronjob_create.mdx b/docs/en/developer/building_application/application_workloads/cronjob_create.mdx index 7ef27ffe3..f048ff82b 100644 --- a/docs/en/developer/building_application/application_workloads/cronjob_create.mdx +++ b/docs/en/developer/building_application/application_workloads/cronjob_create.mdx @@ -68,6 +68,8 @@ Obtain the image address. Images can be sourced from an image registry integrate - If the image registry requires authentication, you need to configure the corresponding image pull secret. For more information, see [Add ImagePullSecrets to ServiceAccount](../how_to/sa_imagepullsecret.mdx). +- When selecting an image through an OCI Connector, also select an image pull Secret for the Connector proxy, or confirm that the workload ServiceAccount already references that Secret. See [Use an ImagePullSecret with an OCI Connector](../how_to/sa_imagepullsecret.mdx#use-an-imagepullsecret-with-an-oci-connector). + ### Creating CronJobs by using new web console #### Creation entry differences between the Applications and Clusters views @@ -87,6 +89,8 @@ The new web console can expose CronJob creation from different views. Choose the **Note**: Image filtering is available only when using images from the platform's integrated image registry. For example, an integrated project name like containers (registry-projectname) indicates the platform's project name projectname and the image registry's project name containers. + For an OCI Connector image, confirm that the Connector proxy image pull Secret is selected by the Pod template or inherited from its ServiceAccount. Creating the CronJob object does not prove that a later Job can pull the image; the token must still be valid when the Job Pod starts. + 4. In the **Cron Configuration** section, configure the task execution method and associated parameters. **Execute Type**: @@ -149,6 +153,8 @@ The new web console can expose CronJob creation from different views. Choose the kubectl logs job/ -n ``` +For a Job that uses an OCI Connector, inspect the generated Pod rather than relying only on the CronJob or Job status. Verify the Connector annotation, `imagePullSecrets` or ServiceAccount inheritance, the rewritten Connector proxy image, Pod `Running` or `Completed` status, and Events. Treat an expired token as an authentication-material issue and rotate or recreate the Secret before the next execution. + ### Monitor execution status | Status | Description | |--------------|-----------------------------------------------------------------------------| @@ -157,6 +163,8 @@ The new web console can expose CronJob creation from different views. Choose the | **Succeeded**| All Pods associated with the Job completed successfully (exit code 0). | | **Failed** | At least one Pod associated with the Job terminated unsuccessfully (non-zero exit code). | +When updating a CronJob image or OCI Connector, review the Pod template's Connector proxy image pull Secret or ServiceAccount and token validity. Verify these values again on the next generated Job Pod, because an update accepted by the API does not prove that the scheduled Pod can pull its image. + ## Deleting CronJobs ### Deleting CronJobs by using web console diff --git a/docs/en/developer/building_application/application_workloads/deamonset_create.mdx b/docs/en/developer/building_application/application_workloads/deamonset_create.mdx index 5c83da8f8..a48fb4c25 100644 --- a/docs/en/developer/building_application/application_workloads/deamonset_create.mdx +++ b/docs/en/developer/building_application/application_workloads/deamonset_create.mdx @@ -116,6 +116,8 @@ Obtain the image address. The source of the images can be from the image reposit - If the image registry requires authentication, you need to configure the corresponding image pull secret. For more information, see [Add ImagePullSecrets to ServiceAccount](../how_to/sa_imagepullsecret.mdx). +- When selecting an image through an OCI Connector, also select an image pull Secret for the Connector proxy, or confirm that the workload ServiceAccount already references that Secret. See [Use an ImagePullSecret with an OCI Connector](../how_to/sa_imagepullsecret.mdx#use-an-imagepullsecret-with-an-oci-connector). + #### Procedure - Configure Basic Info 1. **Container Platform**, navigate to **Workloads** > **DaemonSets** in the left sidebar. @@ -188,6 +190,8 @@ The new web console can expose DaemonSet creation from different views. Choose t When you modify the **Pod Template** of a DaemonSet (e.g., changing the container image or adding a volume mount), Kubernetes automatically performs a rolling update by default (if `updateStrategy.type` is `RollingUpdate`, which is the default). +Before changing an image or OCI Connector, confirm that the Connector proxy image pull Secret is available directly to the Pod or through its ServiceAccount. Every target node's container runtime must be able to access the Connector proxy address. During the update, verify the Connector annotation, rewritten proxy image, status, and Events for Pods on each node. + - First, edit the YAML file (e.g., `example-daemonset.yaml`) with the desired changes, then apply it: ```bash @@ -222,6 +226,8 @@ kubectl delete daemonset 2. Locate the DaemonSet you wish to update. 3. In the **Actions** drop-down menu, select **Update** to view the Edit DaemonSet page, you can update `Replicas`, `image`, `updateStrategy`, etc. +When changing an image or OCI Connector, also review the Connector proxy image pull Secret, workload ServiceAccount, and token validity. Verify the actual Pod image and Events on every target node during the rollout. + #### Deleting a DaemonSet 1. **Container Platform**, and navigate to **Workloads** > **DaemonSets**. diff --git a/docs/en/developer/building_application/application_workloads/deployment_create.mdx b/docs/en/developer/building_application/application_workloads/deployment_create.mdx index c30d39c92..c854668a2 100644 --- a/docs/en/developer/building_application/application_workloads/deployment_create.mdx +++ b/docs/en/developer/building_application/application_workloads/deployment_create.mdx @@ -95,6 +95,8 @@ Obtain the image address. The source of the images can be from the image reposit - If the image registry requires authentication, you need to configure the corresponding image pull secret. For more information, see [Add ImagePullSecrets to ServiceAccount](../how_to/sa_imagepullsecret.mdx). +- When selecting an image through an OCI Connector, also select an image pull Secret for the Connector proxy, or confirm that the workload ServiceAccount already references that Secret. The two reference methods are alternatives. See [Use an ImagePullSecret with an OCI Connector](../how_to/sa_imagepullsecret.mdx#use-an-imagepullsecret-with-an-oci-connector). + ### Creating a Deployment by using new web console The new web console can expose Deployment creation from different views. Choose the entry based on whether you are working from project scope or from a concrete cluster. @@ -138,7 +140,7 @@ Before proceeding, confirm the following differences: | **Parameters** | **Description** | | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Volumes** | Mount persistent volumes to containers. Supported volume types include `PVC`, `ConfigMap`, `Secret`,`emptyDir`, `hostPath`, and so on. For implementation details, see [Volume Mounting Guide](#pvmount). | - | **Pull Secret** | Required **only** when pulling images from third-party registries (via manual image URL input).
**Note**: Secret for authentication when pulling image from a secured registry. | + | **Pull Secret** | For a private registry image, use the Secret that contains credentials for that registry. For an OCI Connector image, select the Connector proxy image pull Secret or use a ServiceAccount that already references it. Images from a platform Integration continue to use their associated credentials. See [Use an ImagePullSecret with an OCI Connector](../how_to/sa_imagepullsecret.mdx#use-an-imagepullsecret-with-an-oci-connector). | | **Close Grace Period** | Duration (default: `30s`) allowed for a Pod to complete graceful shutdown after receiving termination signal.
- During this period, the Pod completes inflight requests and releases resources.
- Setting `0` forces immediate deletion (SIGKILL), which may cause request interruptions. | @@ -282,6 +284,7 @@ Follow the steps given below to update your Deployment: Run kubectl get rs to see that the Deployment updated the Pods by creating a new ReplicaSet and scaling it up to 3 replicas, as well as scaling down the old ReplicaSet to 0 replicas. + ```bash kubectl get rs ``` @@ -292,6 +295,8 @@ Follow the steps given below to update your Deployment: kubectl get pods ``` +When changing an image or OCI Connector, also review the Pod template's **Pull Secret**, `serviceAccountName`, and token validity. After the update, verify the new ReplicaSet and Pods: check the Connector annotation, confirm that the actual Pod image is rewritten to the Connector proxy, wait for the Pods to become `Running`, and review Events. + #### Scaling a Deployment You can scale a Deployment by using the following command: @@ -344,6 +349,8 @@ Before submitting an update, confirm that changes to images, probes, environment Changes to the Pod template can trigger a new rollout. A successful update request does not by itself mean the rollout is healthy. The real effect appears only after the new Pod revision schedules correctly, becomes ready, and replaces the previous revision without leaving the workload unavailable. +When changing an image or OCI Connector in the web console, also review the **Pull Secret**, workload ServiceAccount, and token validity. Confirm the resulting Pods use the Connector proxy image and complete the rollout; a successful update request alone does not verify image pulling. + #### Deleting a Deployment 1. **Container Platform**, and navigate to **Workloads** > **Deployments**. @@ -356,6 +363,15 @@ After deletion, verify that the Deployment no longer appears in the list and tha When a Deployment encounters issues, here are some common troubleshooting methods. +For an OCI Connector image pull failure, verify the path in this order: + +1. Check the Pod template's `connectors./connectors` annotation. +2. Check `spec.imagePullSecrets` and the `imagePullSecrets` of the workload ServiceAccount. +3. Check that the actual Pod image was rewritten to the Connector proxy. +4. Check Pod status and Events. + +If Events show an HTTPS error for the original HTTP registry, the workload might not have entered the Connector proxy path. Check the Connector proxy Secret, ServiceAccount, and token before changing registry runtime settings. See [Use an ImagePullSecret with an OCI Connector](../how_to/sa_imagepullsecret.mdx#use-an-imagepullsecret-with-an-oci-connector). + ### Check Deployment status ```bash diff --git a/docs/en/developer/building_application/application_workloads/statefulset_create.mdx b/docs/en/developer/building_application/application_workloads/statefulset_create.mdx index e44ba24b6..d12ff6cf2 100644 --- a/docs/en/developer/building_application/application_workloads/statefulset_create.mdx +++ b/docs/en/developer/building_application/application_workloads/statefulset_create.mdx @@ -109,6 +109,8 @@ Obtain the image address. The source of the images can be from the image reposit - If the image registry requires authentication, you need to configure the corresponding image pull secret. For more information, see [Add ImagePullSecrets to ServiceAccount](../how_to/sa_imagepullsecret.mdx). +- When selecting an image through an OCI Connector, also select an image pull Secret for the Connector proxy, or confirm that the workload ServiceAccount already references that Secret. See [Use an ImagePullSecret with an OCI Connector](../how_to/sa_imagepullsecret.mdx#use-an-imagepullsecret-with-an-oci-connector). + ### Creating a StatefulSet by using new web console The new web console can expose StatefulSet creation from different views. Choose the entry based on whether you are working from project scope or from a concrete cluster. @@ -217,6 +219,8 @@ You can view a StatefulSet to get information of your application. When you modify the Pod template of a StatefulSet (e.g., changing the container image), Kubernetes performs a rolling update by default (if updateStrategy is set to RollingUpdate, which is the default). +Before changing an image or OCI Connector, confirm that each new Pod revision can obtain a valid Connector proxy image pull Secret directly or through its ServiceAccount. During the ordered update, verify each Pod's Connector annotation, rewritten proxy image, status, and Events. If an ordinal Pod enters `ImagePullBackOff`, stop the rollout and check the Secret, ServiceAccount, and token validity before continuing. + - First, edit the YAML file (e.g., example-statefulset.yaml) with the desired changes, then apply it: ```bash @@ -259,6 +263,8 @@ Alternatively, if your `volumeClaimTemplates` use a `StorageClass` with a `recla 2. Locate the StatefulSet you wish to update. 3. In the **Actions** drop-down menu, select **Update** to view the Edit StatefulSet page, you can update `Replicas`, `image`, `updateStrategy`, etc. +When changing an image or OCI Connector, also review the Connector proxy image pull Secret, workload ServiceAccount, and token validity. Observe the ordered Pod replacement and verify the actual image rewrite and Events for each new Pod. + #### Deleting a StatefulSet 1. **Container Platform**, and navigate to **Workloads** > **StatefulSets**. diff --git a/docs/en/developer/building_application/create_applications/image_app.mdx b/docs/en/developer/building_application/create_applications/image_app.mdx index b961d468c..6000bacc7 100644 --- a/docs/en/developer/building_application/create_applications/image_app.mdx +++ b/docs/en/developer/building_application/create_applications/image_app.mdx @@ -16,6 +16,8 @@ Obtain the image address. The source of the images can be from the image reposit - If it is a third-party platform's image repository, ensure that images can be pulled directly from it in the current cluster. +- When selecting an image through an OCI Connector, also select an image pull Secret for the Connector proxy, or confirm that the workload ServiceAccount already references that Secret. See [Use an ImagePullSecret with an OCI Connector](../how_to/sa_imagepullsecret.mdx#use-an-imagepullsecret-with-an-oci-connector). + ## Procedure 1 - Workloads 1. **Container Platform**, navigate to **Applications** > **Applications** in the left sidebar. @@ -30,6 +32,8 @@ Obtain the image address. The source of the images can be from the image reposit **Note**: When using images from the image repository integrated into web console, you can filter images by **Already Integrated**. The **Integration Project Name**, for example, images (registry-projectname), which includes the project name projectname in this web console and the project name containers in the image repository. When using images from a private registry, you need to configure the corresponding image pull secret. For more information, see [Add ImagePullSecrets to ServiceAccount](../how_to/sa_imagepullsecret.mdx). + +When using an OCI Connector, use a Connector proxy image pull Secret directly from the Pod template or through the workload ServiceAccount. The Secret must authenticate to the proxy, not the original registry. ::: 6. Refer to the following instructions to configure the related parameters. @@ -53,7 +57,7 @@ In the **Workload** > **Basic Info** section, configure declarative parameters f | **Parameters** | **Description** | | :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Volumes** | Mount persistent volumes to containers. Supported volume types include `PVC`, `ConfigMap`, `Secret`,`emptyDir`, `hostPath`, and so on. For implementation details, see [Storage Volume Mounting Instructions](#pvmount). | - | **Image Credential** | Required **only** when pulling images from third-party registries (via manual image URL input).
**Note**: Images from the platform's integrated registry automatically inherit associated secrets. | + | **Image Credential** | For a private registry image, use the Secret that contains credentials for that registry. For an OCI Connector image, select the Connector proxy image pull Secret or use a ServiceAccount that already references it. Images from the platform's integrated registry continue to inherit associated credentials. See [Use an ImagePullSecret with an OCI Connector](../how_to/sa_imagepullsecret.mdx#use-an-imagepullsecret-with-an-oci-connector). | | **More** > **Close Grace Period** | Duration (default: `30s`) allowed for a Pod to complete graceful shutdown after receiving termination signal.
- During this period, the Pod completes inflight requests and releases resources.
- Setting `0` forces immediate deletion (SIGKILL), which may cause request interruptions. | @@ -132,6 +136,8 @@ To modify application configurations, use one of the following methods: | **Update** |
  • **Update**: Modifies only the target workload using its defined [update strategy](#updatepolicy) (Deployment strategy shown as example). Preserves existing replica count and rollout configuration.
  • **Force Update**: Triggers full application rollout using each component's update strategy.
    1. **Use cases**:
    • Batch configuration changes requiring immediate cluster-wide propagation (e.g., ConfigMap/Secret updates referenced as environment variables).
    • Coordinated component restarts for critical security.
    2. **Warning Caution**:
    • May cause temporary service degradation during mass restarts.
    • Not recommended for production environments without business continuity validation.
  • **Network Implications**:
    • Ingress Rule Deletion: External access remains available via `LB_IP:NodePort` if:
      1) LoadBalancer Service uses default ports.
      2) Surviving routing rules reference application components.
      Full external access termination requires Service deletion.
    • Service Deletion: Irreversible loss of network connectivity to application components. Associated Ingress rules become non-functional despite API object persistence.
| | **Delete** |
  • **Cascading Deletion**:
    1. Removes all child resources including Deployments, Services, and Ingress rules.
    2. Persistent Volume Claims (PVCs) follow retention policy defined in StorageClass
  • **Pre-deletion Checklist**:
    1. Verify no active traffic through associated Services.
    2. Confirm data backup completion for stateful components.
    3. Check dependent resource relationships using `kubectl describe ownerReferences`.
| +When updating a component image or OCI Connector, also review that component Pod template's image pull Secret or ServiceAccount and the token validity. Verify the Connector annotation, actual rewritten proxy image, Pod rollout status, and Events after the update. + ## Reference Information ### Storage Volume Mounting Instructions \{#pvmount} diff --git a/docs/en/developer/building_application/how_to/sa_imagepullsecret.mdx b/docs/en/developer/building_application/how_to/sa_imagepullsecret.mdx index c91597d6c..33ff0379a 100644 --- a/docs/en/developer/building_application/how_to/sa_imagepullsecret.mdx +++ b/docs/en/developer/building_application/how_to/sa_imagepullsecret.mdx @@ -54,3 +54,87 @@ You can verify this by run the command: ```bash kubectl get pod -n -o=jsonpath='{.spec.imagePullSecrets}' ``` + +## Use an ImagePullSecret with an OCI Connector \{#use-an-imagepullsecret-with-an-oci-connector} + +When a workload image is selected through an OCI Connector, the workload still needs an image pull Secret to authenticate to the Connector proxy. The Connector avoids distributing long-lived credentials for the original registry to workload namespaces, but this does not mean that the workload needs no Kubernetes image pull Secret. The Connector proxy Secret uses a ServiceAccount token that is authorized to access the Connector instead of the original registry password. + +You can reference the Secret directly from the Pod template, or attach it to the ServiceAccount used by the workload. Either method is sufficient. + +### Prerequisites + +Before creating the Secret, confirm the following: + +- Alauda DevOps Connectors is installed, the Connector is Ready, and `enable-pod-image-pull-via-connector` is enabled. +- The OCI proxy is exposed through NodePort or Ingress, and every target node's container runtime can access the proxy address. If the proxy uses HTTP, the runtime must allow that proxy address. +- The ServiceAccount used to create the token is authorized to access the Connector. +- The Secret is created in the same namespace as the workload. + +### Create the Connector proxy Secret + +Get the Connector proxy address and create a token for the workload ServiceAccount: + +```bash +kubectl get connector -n \ + -o jsonpath='{.status.proxy.httpAddress.url}' + +kubectl create token \ + -n \ + --duration= +``` + +Create the image pull Secret: + +```bash +kubectl create secret docker-registry \ + --docker-server='' \ + --docker-username='u' \ + --docker-password='' \ + --docker-email='' \ + -n +``` + +The `--docker-server` value must identify the Connector proxy, not the original registry. If `.status.proxy.httpAddress.url` includes a Connector path, use the proxy host and port as the registry server. The command creates a Secret of type `kubernetes.io/dockerconfigjson`. + +The token must come from a ServiceAccount that has permission to access the Connector. A token created without an approved duration is valid for approximately one hour by default. Select `--duration` according to your organization's security policy, and rotate or recreate the Secret before the token expires. Do not treat a manually copied token as a permanent credential or rotation mechanism. + +### Reference the Secret + +To reference the Secret directly from the Pod template, configure: + +```yaml +spec: + imagePullSecrets: + - name: +``` + +Alternatively, attach the Secret to the ServiceAccount used by the workload: + +```bash +kubectl patch serviceaccount \ + -n \ + -p '{"imagePullSecrets":[{"name":""}]}' +``` + +The Pod template reference and ServiceAccount inheritance are alternative valid sources. You do not need to configure both. + +### Verify and troubleshoot + +After creating or updating the workload, verify the Connector path in this order: + +1. Check that the workload Pod template has the expected `connectors./connectors` annotation, including mappings for every container and init container that uses an OCI Connector. +2. Check the image pull Secret selected by the Pod or inherited from its ServiceAccount. +3. Check that the actual Pod image was rewritten to the Connector proxy address. +4. Check that the Pod reaches `Running` (or `Completed` for a completed Job), and then review its Events. + +Run the following commands: + +```bash +kubectl get serviceaccount -n -o yaml +kubectl get pod -n -o jsonpath='{.spec.imagePullSecrets}' +kubectl get pod -n -o jsonpath='{.spec.containers[*].image}' +kubectl get pod -n +kubectl describe pod -n +``` + +If the actual Pod image still points to the original registry, check the Connector annotation, Secret namespace and type, ServiceAccount association, and token validity first. An HTTPS error for the original HTTP registry can indicate that the workload did not enter the Connector proxy path; do not work around it by permanently allowing the original registry as an insecure registry. From 846c2b223c4cc9fe6187ea6bd0185121d2302bb6 Mon Sep 17 00:00:00 2001 From: Xiaolu Zhao Date: Fri, 31 Jul 2026 09:38:46 +0000 Subject: [PATCH 02/17] update aml version --- sites.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sites.yaml b/sites.yaml index 3cf5df27b..5fcd17da0 100644 --- a/sites.yaml +++ b/sites.yaml @@ -31,7 +31,7 @@ en: Alauda AI zh: Alauda AI base: /ai - version: "2.3" + version: "2.7" repo: https://github.com/alauda/aml-docs - name: hyperflux displayName: From 281bb228b22eb5c262e0804bb702458c7845201c Mon Sep 17 00:00:00 2001 From: MeoK Date: Wed, 5 Aug 2026 17:38:06 +0800 Subject: [PATCH 03/17] docs(upgrade): clarify required Aligned plugin packages (#989) * docs(upgrade): clarify required Aligned plugin packages * docs: clarify aligned plugin upgrade workflow --------- Co-authored-by: Chao Zhou --- docs/en/upgrade/overview.mdx | 3 ++- docs/en/upgrade/pre-upgrade.mdx | 10 +++++++++- docs/en/upgrade/upgrade_global_cluster.mdx | 19 ++++++++++++++++--- docs/en/upgrade/upgrade_workload_cluster.mdx | 12 ++++++++---- 4 files changed, 35 insertions(+), 9 deletions(-) diff --git a/docs/en/upgrade/overview.mdx b/docs/en/upgrade/overview.mdx index b0199702d..b3f48552d 100644 --- a/docs/en/upgrade/overview.mdx +++ b/docs/en/upgrade/overview.mdx @@ -34,13 +34,14 @@ A single cluster upgrade window covers four kinds of work: | Work item | Required? | How it is upgraded | If you run immutable OS | |---|---|---|---| | Core (the platform itself) | Required | CVO, driven by `upgrade.sh`-prepared artifacts | Same control flow; the Kubernetes step is handled separately, see below | -| Aligned plugins (cluster plugins and operators released together with the matching ACP version) | Required in the same window | CVO by default; can also be upgraded individually through the cluster plugin or operator workflow when an out-of-band fix is needed | Same | +| Aligned plugins (cluster plugins and operators released together with the matching ACP version) | Required for each installed plugin | Publish the target-version package with `violet` before the cluster upgrade. CVO then upgrades each installed Aligned plugin as part of the cluster upgrade. To upgrade only one plugin, follow that plugin's own upgrade procedure. | Same | | Kubernetes | Required in the same window | On traditional-OS clusters, CVO upgrades Kubernetes in place on the existing nodes as part of the same cluster upgrade; nodes are not replaced. | Kubernetes is rolled out by replacing nodes from a new Alauda OS-based image through Cluster API rolling updates, not upgraded in place. The procedure lives in the immutable infrastructure documentation; see , , or | | Agnostic plugins (independently released cluster plugins and operators) | Optional, per plugin | Upgrade each cluster plugin or operator from **Marketplace > Cluster Plugins** or the operator's own workflow after the cluster reaches the target Distribution Version | Same | A few rules govern when each piece moves: - The platform requires that a cluster's Kubernetes version is upgraded together with its Core and Aligned versions; mixing a new Core release with an old Kubernetes minor version is not validated. +- Before requesting an upgrade, publish the target-version package for every Aligned plugin already installed on that cluster. A missing package for an installed Aligned plugin stalls the CVO upgrade. Packages for Aligned plugins that are not installed on the cluster are not required and do not block the upgrade. - Cluster plugins are global resources. Pushing a cluster plugin to the global tier makes it installable and upgradable on every cluster in the platform; you do not push the same cluster plugin again per workload cluster. - Operators are scoped to each cluster. Pushing operators to the global tier is recommended but not sufficient on its own; the same operator must be available on each workload cluster before the workload upgrade. If you forgot to push an operator during the global window, you can push it again before the workload upgrade as a fallback. - Workload-cluster upgrades are only required when a workload cluster falls outside the target ACP release's [Kubernetes Support Matrix](../overview/kubernetes-support-matrix.html). Workload clusters that stay within the supported range can keep their existing Kubernetes version after the global tier moves; the platform will continue to manage them. diff --git a/docs/en/upgrade/pre-upgrade.mdx b/docs/en/upgrade/pre-upgrade.mdx index b6af43bd7..cdf524ca2 100644 --- a/docs/en/upgrade/pre-upgrade.mdx +++ b/docs/en/upgrade/pre-upgrade.mdx @@ -75,7 +75,7 @@ cgroup2fs ## Download the Packages for Offline Environments -A production maintenance window typically upgrades ** Core**, the **Aligned plugins** (cluster plugins and operators released together with the same ACP version), and the in-use **Agnostic plugins** (independently released cluster plugins and operators) in the same window. Prepare every package the cluster currently uses before the upgrade starts, even when an Agnostic plugin upgrade is technically optional. Holding back an Agnostic plugin during the window often forces a second maintenance window later. +A production maintenance window typically upgrades ** Core**, the **Aligned plugins** (cluster plugins and operators released together with the same ACP version), and the in-use **Agnostic plugins** (independently released cluster plugins and operators) in the same window. Prepare the target-version package for every installed Aligned plugin before the upgrade starts. Also prepare the Agnostic plugins you plan to upgrade in the same window, even though they do not gate the CVO upgrade. Holding back an Agnostic plugin often forces a second maintenance window later. ### Step 1: Download the Core Package @@ -109,6 +109,14 @@ Import the exported `apps.yaml` file into the ** Customer Download every package you will need so they are all available locally before the upgrade window starts. The next page, [Upgrade the global cluster](./upgrade_global_cluster.mdx), describes how `upgrade.sh` and `violet` push these packages into the platform. That push uploads images to the registry and registers the target versions in the platform catalog so they become available to install or upgrade; it does not upgrade any already-running plugin, so it can be completed any time before the maintenance window. +:::warning Required Aligned Plugin Packages +Starting with ACP 4.3, every Aligned plugin installed on a cluster being upgraded must have its target-version package published with `violet` before the upgrade request. Use the package that the Customer Portal provides for the target ACP Distribution Version; the plugin's own version number does not need to match the ACP version string. + +Publish a cluster plugin package once to the global tier. Publish an operator package to every cluster where that operator is installed. CVO does not require target packages for Aligned plugins that are not installed on the cluster. + +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. diff --git a/docs/en/upgrade/upgrade_global_cluster.mdx b/docs/en/upgrade/upgrade_global_cluster.mdx index 4bb9ff3df..0f2e617d8 100644 --- a/docs/en/upgrade/upgrade_global_cluster.mdx +++ b/docs/en/upgrade/upgrade_global_cluster.mdx @@ -29,7 +29,7 @@ A global cluster upgrade is staged across a timeline. Most of the work is comple | Phase | When | What happens | Cluster impact | | --- | --- | --- | --- | -| 1. Sync artifacts | Any time before the window | `upgrade.sh --only-sync-image` uploads images and plugin artifacts to the registry; `violet` pushes Aligned and Agnostic plugins. | None — images and catalog entries are published, but no running plugin is changed; no downtime. | +| 1. Sync artifacts | Any time before the window | `upgrade.sh --only-sync-image` uploads Core artifacts; `violet` publishes the target packages for installed Aligned plugins and any Agnostic plugins planned for the window. | None — images and catalog entries are published, but no running plugin is changed; no downtime. | | 2. Preflight | 1–2 weeks before the window | `upgrade.sh --preflight` validates upgrade readiness. Resolve every blocking item before the window opens. | None — read-only validation. | | 3. Upgrade | During the maintenance window | `upgrade.sh --skip-sync-image` deploys or updates the cluster version operator (CVO); the upgrade is then requested and observed. | The cluster is upgraded. | @@ -61,8 +61,8 @@ bash upgrade.sh --only-sync-image | Lifecycle type | Push tool | Cluster plugins | Operators | | --- | --- | --- | --- | -| Aligned plugins | `violet push` | Push once to the global tier. The pushed cluster plugin becomes installable and upgradable on every cluster in the platform. | Push to the global tier, and also push to each workload cluster that runs the operator. Pushing operators to every cluster during the global window is recommended; it lets the workload upgrade window proceed without an extra push step. | -| Agnostic plugins | `violet push` | Same as above. | Same as above. | +| Aligned plugins | `violet push` | Required for every installed Aligned cluster plugin. Push the package selected for the target ACP Distribution Version once to the global tier; it then becomes available to every cluster. | Required for every installed Aligned operator. Push the target package to the global tier and to each workload cluster that runs the operator. | +| Agnostic plugins | `violet push` | Push when you plan to upgrade the plugin in the same window. Missing Agnostic packages do not block CVO. | Same; push the package to each cluster where you plan to upgrade the operator. | ```bash # Push Aligned plugins (cluster plugins) — global only @@ -79,6 +79,10 @@ violet push \ Pushing every operator package to every cluster from the global window is the recommended pattern. If the global window has already passed and you discover a workload cluster missing an operator package, you can still push to that workload cluster before the workload upgrade — see [Upgrade workload clusters](./upgrade_workload_cluster.mdx#operator-push-fallback). +:::warning +Before requesting the upgrade, publish the target package for every Aligned plugin installed on the cluster. CVO does not require packages for Aligned plugins that are not installed. If an installed Aligned cluster plugin's package is missing or has not become ready, CVO stalls the upgrade and reports a message such as `required ModulePluginConfig "-" not found` or `ModulePluginConfig "-" is not Ready`. +::: + Registry behavior depends on how the environment is configured: | Scenario | Behavior | @@ -351,6 +355,15 @@ kubectl -n cpaas-system get cvsh global \ -o jsonpath='{range .status.history[*]}{.version}{"\t"}{.state}{"\t"}{.startedTime}{"\t"}{.completionTime}{"\n"}{end}' ``` +#### Recover from a missing Aligned cluster plugin package \{#recover-missing-aligned-package} + +If `Stalled=True` and the condition message names a missing or not-ready `ModulePluginConfig`, an installed Aligned cluster plugin does not yet have its target package available: + +1. Identify the component and required version from the `Stalled` condition message. +2. Download the package that the Customer Portal provides for the target ACP Distribution Version. +3. Use `violet push` as described in [Sync upgrade artifacts](#sync-upgrade-artifacts) to publish the cluster plugin package to the global tier. +4. Continue observing the existing upgrade request. CVO watches the package readiness and resumes automatically after the package becomes ready; do not clear or resubmit `desiredUpdate`. + The commands above track the cluster-level (Core and Aligned) upgrade. To observe an individual plugin or operator module — for example while upgrading an Agnostic plugin — read its `ModuleInfo` instead: ```bash diff --git a/docs/en/upgrade/upgrade_workload_cluster.mdx b/docs/en/upgrade/upgrade_workload_cluster.mdx index b8350cf2a..7be481075 100644 --- a/docs/en/upgrade/upgrade_workload_cluster.mdx +++ b/docs/en/upgrade/upgrade_workload_cluster.mdx @@ -34,13 +34,13 @@ Before requesting the upgrade, verify that: * The global tier has already reached the target ACP Distribution Version. * In global DR environments, both the standby and primary global clusters have already reached that target Distribution Version. -### Operator push fallback \{#operator-push-fallback} +### Ensure Aligned operator packages are available \{#operator-push-fallback} The recommended pattern in [Upgrade the global cluster](./upgrade_global_cluster.mdx) pushes operator packages to every cluster during the global upgrade window. If the recommendation was followed, the workload cluster already has every operator package it needs and you can skip this section. Cluster plugins do not need a per-workload-cluster push. A cluster plugin pushed once to the global tier is installable and upgradable on every cluster in the platform. -If the global window did not push operator packages to this workload cluster — for example, the cluster was offline during the global window or was added later — push each in-use operator package to this workload cluster before the upgrade request: +If the global window did not push operator packages to this workload cluster — for example, the cluster was offline during the global window or was added later — push the target-version package for each Aligned operator installed on this workload cluster before the upgrade request: ```bash violet push \ @@ -49,7 +49,9 @@ violet push \ --clusters "" ``` -You only need to push operator packages for operators actually running on the workload cluster. Aligned plugin packages still on the global side are picked up automatically by CVO during the workload upgrade. +You only need to push packages for Aligned operators actually installed on the workload cluster. Aligned cluster plugin packages published to the global tier are available to all workload clusters and do not need a per-cluster push. + +If an installed Aligned operator's target package is missing or is not ready, CVO stalls the workload-cluster upgrade. Publish the missing package with the command above, then continue observing the existing request. CVO detects the newly ready package and resumes automatically; you do not need to submit the upgrade request again. Packages for Aligned operators that are not installed on this workload cluster do not block its upgrade. ### Run preflight checks @@ -131,6 +133,8 @@ ac adm upgrade status For detailed semantics of `ac adm upgrade status` output (preflight and stage interpretation), see [Upgrading Clusters](/ui/cli_tools/ac/upgrading-clusters.md). +If an installed Aligned operator does not advance toward its target version, verify that its target package was pushed to this workload cluster as described in [Ensure Aligned operator packages are available](#operator-push-fallback). If a `Stalled` condition names a missing or not-ready `ModulePluginConfig`, the missing component is a cluster plugin; publish its package once to the global tier as described in [Upgrade the global cluster](./upgrade_global_cluster.mdx#recover-missing-aligned-package). + The commands above track the cluster-level (Core and Aligned) upgrade. To observe an individual plugin or operator module — for example while upgrading an Agnostic plugin — read its `ModuleInfo`: ```bash @@ -152,7 +156,7 @@ For each in-use Agnostic plugin on this workload cluster: Whether each Agnostic plugin needs to be upgraded in this window depends on its own Kubernetes compatibility — see the plugin's release notes for compatibility with the new Kubernetes version that the workload cluster has reached. -If the Marketplace does not offer the target version of an operator on this workload cluster, complete the [Operator push fallback](#operator-push-fallback) for that operator first and then retry the Marketplace upgrade. +If the Marketplace does not offer the target version of an operator on this workload cluster, follow [Ensure Aligned operator packages are available](#operator-push-fallback) for that operator first and then retry the Marketplace upgrade. When troubleshooting, inspect conditions, preflight details, and history first: From 25af6657dd8ba42799416c2cd78295ec184e116c Mon Sep 17 00:00:00 2001 From: Chao Zhou Date: Wed, 5 Aug 2026 22:00:33 +0800 Subject: [PATCH 04/17] docs: align ACP 4.4 version and upgrade guidance --- docs/en/configure/clusters/overview.mdx | 17 ++++----- .../hosted_control_planes/overview.mdx | 2 +- docs/en/install/global_dr.mdx | 2 +- .../en/install/prepare/node_preprocessing.mdx | 37 ++++++------------- docs/en/overview/architecture.mdx | 2 +- .../en/overview/availability-and-recovery.mdx | 2 +- .../en/overview/cluster-management-models.mdx | 4 +- docs/en/overview/core-and-extensions.mdx | 11 ++++-- docs/en/overview/glossary.mdx | 2 +- .../en/overview/kubernetes-support-matrix.mdx | 30 ++++++++------- docs/en/overview/learn-more.mdx | 2 +- docs/en/overview/platform-model.mdx | 2 +- docs/en/overview/version-and-lifecycle.mdx | 14 ++++--- docs/en/upgrade/overview.mdx | 8 ++-- docs/en/upgrade/pre-upgrade.mdx | 23 +++--------- docs/en/upgrade/upgrade_global_cluster.mdx | 16 ++++---- docs/en/upgrade/upgrade_workload_cluster.mdx | 8 ++-- 17 files changed, 83 insertions(+), 99 deletions(-) diff --git a/docs/en/configure/clusters/overview.mdx b/docs/en/configure/clusters/overview.mdx index fed033270..2c4483011 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 HCP for a non-production 4.4 scenario. | [About Hosted Control Plane](../hosted_control_planes/overview.mdx) | HCP remains Technology Preview in 4.4 and is not production-supported. | | 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`). In 4.4, HCP remains 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). ## Third-Party Cluster Onboarding @@ -64,14 +64,13 @@ For onboarding workflows, see [Third-Party Cluster Onboarding](./managed/overvie When importing or connecting existing clusters, validate the Kubernetes version against the current compatibility policy. -### 4.3 And Later +### 4.4 -- 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. +- The current 4.4 release line supports Kubernetes 1.35 for platform-managed cluster scenarios. +- Before a `global` cluster upgrade, workload clusters must remain within the compatible versions 1.35, 1.34, 1.33, and 1.32. +- Kubernetes 1.28 through 1.35 have completed third-party cluster onboarding validation and are product-supported. Provider prerequisites and exact Extension compatibility still apply. +- The third-party onboarding range is separate from the compatible Kubernetes versions used to determine whether the `global` cluster can be upgraded. +- The default Extend baseline validates the Operator and Cluster Plugin mechanisms, with ClickHouse-based logging and VictoriaMetrics-based monitoring as default validated capabilities. - 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. ### 4.2 And Earlier diff --git a/docs/en/configure/hosted_control_planes/overview.mdx b/docs/en/configure/hosted_control_planes/overview.mdx index 6d8f719c9..24a556f67 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. +In 4.4, HCP remains 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. diff --git a/docs/en/install/global_dr.mdx b/docs/en/install/global_dr.mdx index 1e7d11fae..01b69e230 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**. Global Cluster Disaster Recovery is also supported on Immutable Infrastructure with Huawei DCS, VMware vSphere, and Huawei Cloud Stack; use for that path. ## Overview diff --git a/docs/en/install/prepare/node_preprocessing.mdx b/docs/en/install/prepare/node_preprocessing.mdx index 7fef2cb3b..38a51e0a2 100644 --- a/docs/en/install/prepare/node_preprocessing.mdx +++ b/docs/en/install/prepare/node_preprocessing.mdx @@ -7,21 +7,21 @@ 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 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. ::: ## 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**: 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 an official distribution 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**. +- ACP 4.4 requires cgroup v2 and a kernel version of 5.8 or later. Operating systems from earlier ACP release baselines that cannot meet these requirements are not supported for ACP 4.4. ::: :::info @@ -34,30 +34,19 @@ For -provided immutable operating system images or p - - 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 +54,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 +89,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 +98,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 +152,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..7794e529e 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 4.4 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..f0d8eb562 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: +For 4.4, 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..cf493f975 100644 --- a/docs/en/overview/cluster-management-models.mdx +++ b/docs/en/overview/cluster-management-models.mdx @@ -29,7 +29,7 @@ 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 | 4.4 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. | @@ -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. +For 4.4, Kubernetes 1.28 through 1.35 have completed third-party cluster onboarding validation and are product-supported. Provider prerequisites and exact Extension compatibility still apply. 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..886290d66 100644 --- a/docs/en/overview/core-and-extensions.mdx +++ b/docs/en/overview/core-and-extensions.mdx @@ -43,7 +43,7 @@ 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. @@ -51,10 +51,13 @@ For package handling, see [Upload Packages](../extend/upload_package.mdx) and [D ## Default Extend Baseline -For 4.3, product validation for the default Extend baseline covers: +For 4.4, the default Extend baseline validates the platform mechanisms for installing and using: + +- Operators. +- Cluster Plugins. + +The default validated capabilities delivered through those mechanisms include: -- Installing and using Operators. -- Installing and using Cluster Plugins. - ClickHouse-based logging. - VictoriaMetrics-based monitoring. diff --git a/docs/en/overview/glossary.mdx b/docs/en/overview/glossary.mdx index a65d800ea..2d8c6d125 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`). In 4.4, HCP remains Technology Preview and is 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) | diff --git a/docs/en/overview/kubernetes-support-matrix.mdx b/docs/en/overview/kubernetes-support-matrix.mdx index 71f6c77d7..bd81536aa 100644 --- a/docs/en/overview/kubernetes-support-matrix.mdx +++ b/docs/en/overview/kubernetes-support-matrix.mdx @@ -14,40 +14,41 @@ 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-supported onboarding range | The Kubernetes minor versions that have completed third-party cluster onboarding validation and are product-supported. Provider prerequisites and exact Extension compatibility still apply. | ## 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 +## 4.4 Notes -- 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. +- The current 4.4 release line supports Kubernetes 1.35 for platform-managed cluster creation. +- Before upgrading the `global` cluster to 4.4, workload clusters must remain within Kubernetes 1.35, 1.34, 1.33, and 1.32. +- 4.4 can be upgraded directly from supported 4.1.x, 4.2.x, and 4.3.x releases. A 4.0.x environment must first upgrade to a supported intermediate release. See [Pre-Upgrade](../upgrade/pre-upgrade.mdx). For upgrade planning, see [Upgrade Overview](../upgrade/overview.mdx) and [Pre-Upgrade](../upgrade/pre-upgrade.mdx). -## Third-Party Cluster Accepted Onboarding Range +## Third-Party Cluster Product-Supported 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. +For 4.4, third-party Kubernetes clusters have been tested and are product-supported for onboarding from Kubernetes 1.28 through 1.35, inclusive. Kubernetes minors outside this range are not declared product-supported for third-party cluster 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. +Product support for the onboarding range does not override cluster-family or provider prerequisites. Check the compatibility metadata and documentation for each exact Operator or Cluster Plugin version. When onboarding third-party clusters, also check: @@ -62,10 +63,13 @@ For model boundaries, see [Cluster Management Models](./cluster-management-model ## Extend Baseline -For 4.3, product validation for the default Extend baseline covers these capability areas: +For 4.4, the default Extend baseline validates the platform mechanisms for installing and using: + +- Operators. +- Cluster Plugins. + +The default validated capabilities delivered through those Extension mechanisms include: -- Installing and using Operators. -- Installing and using Cluster Plugins. - ClickHouse-based logging. - VictoriaMetrics-based monitoring. diff --git a/docs/en/overview/learn-more.mdx b/docs/en/overview/learn-more.mdx index 81e827a46..d33576c53 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 HCP for a non-production 4.4 scenario. | [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..8dc44caad 100644 --- a/docs/en/overview/platform-model.mdx +++ b/docs/en/overview/platform-model.mdx @@ -40,7 +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 4.4, HCP remains 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.4. For HCP scope and tasks, see [About Hosted Control Plane](../configure/hosted_control_planes/overview.mdx). diff --git a/docs/en/overview/version-and-lifecycle.mdx b/docs/en/overview/version-and-lifecycle.mdx index dfe344afc..8a3308f73 100644 --- a/docs/en/overview/version-and-lifecycle.mdx +++ b/docs/en/overview/version-and-lifecycle.mdx @@ -10,18 +10,20 @@ Use [Kubernetes Support Matrix](./kubernetes-support-matrix.mdx) for the exact K ## Product And Kubernetes Versions -For 4.3: +For the current 4.4 release line: -- 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. +- Platform-managed cluster creation supports Kubernetes 1.35. +- Before upgrading the `global` cluster to 4.4, workload clusters must remain within the compatible versions 1.35, 1.34, 1.33, and 1.32. - 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. +The documentation is maintained for the 4.4 minor release line rather than separately for every 4.4.x patch. If a later patch adds another Kubernetes minor, the 4.4 matrix is updated. Exact Kubernetes builds come from the versions offered by the platform 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. +For 4.4, Kubernetes 1.28 through 1.35 have completed third-party cluster onboarding validation and are product-supported. Kubernetes minors outside this range are not declared product-supported for onboarding. This range is separate from: @@ -39,7 +41,7 @@ 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. | +| 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 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 Alauda OS images provided by and provider-specific requirements. | @@ -74,7 +76,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 4.4, HCP remains 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 diff --git a/docs/en/upgrade/overview.mdx b/docs/en/upgrade/overview.mdx index b3f48552d..bbf471145 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. +ACP 4.4 uses the Cluster Version Operator (CVO)-based workflow for cluster upgrades. 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. This sequencing rule does not replace the Compatible Versions prerequisite: before the global tier is upgraded to ACP 4.4, workload clusters must remain within the ACP 4.4 compatible Kubernetes version range. ## 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..35c0752bc 100644 --- a/docs/en/upgrade/pre-upgrade.mdx +++ b/docs/en/upgrade/pre-upgrade.mdx @@ -6,11 +6,11 @@ weight: 20 **Supported upgrade paths:** -* **From `4.0` → `4.3`** -* **From `4.1` → `4.3`** -* **From `4.2` → `4.3`** +* **From `4.1.x` → `4.4`** +* **From `4.2.x` → `4.4`** +* **From `4.3.x` → `4.4`** -Before starting, ensure your current platform version is within the supported upgrade range. +ACP 4.0.x cannot be upgraded directly to ACP 4.4. Upgrade the environment to a supported 4.1.x, 4.2.x, or 4.3.x release first, and then upgrade to ACP 4.4. :::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. @@ -19,8 +19,8 @@ On Immutable Infrastructure (Huawei DCS, VMware vSphere, Huawei Cloud Stack, and ## 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 to ACP 4.4, all workload clusters must remain within the ACP 4.4 **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.4 compatible 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} @@ -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..c3d7fdee3 100644 --- a/docs/en/upgrade/upgrade_global_cluster.mdx +++ b/docs/en/upgrade/upgrade_global_cluster.mdx @@ -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. +ACP 4.4 uses the CVO-based workflow for cluster upgrades. 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 to ACP 4.4, verify that every workload cluster is on a compatible Kubernetes version. For the current ACP 4.4 release line, the compatible versions are 1.35, 1.34, 1.33, and 1.32. 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 ``` @@ -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..18b907120 100644 --- a/docs/en/upgrade/upgrade_workload_cluster.mdx +++ b/docs/en/upgrade/upgrade_workload_cluster.mdx @@ -10,7 +10,7 @@ This page covers the **traditional operating system** path for workload clusters 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: +ACP 4.4 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: - 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 From 0de41116ea566d382eaebcb4277162d350dafbbd Mon Sep 17 00:00:00 2001 From: Chao Zhou Date: Thu, 6 Aug 2026 11:42:57 +0800 Subject: [PATCH 05/17] docs: clarify Alauda OS preprocessing scope --- docs/en/install/prepare/node_preprocessing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/install/prepare/node_preprocessing.mdx b/docs/en/install/prepare/node_preprocessing.mdx index 38a51e0a2..89e1600f9 100644 --- a/docs/en/install/prepare/node_preprocessing.mdx +++ b/docs/en/install/prepare/node_preprocessing.mdx @@ -7,7 +7,7 @@ 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 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 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} From bd2e9545292ae9439e211132cac5e6a7e91c3740 Mon Sep 17 00:00:00 2001 From: SuJinpei Date: Thu, 6 Aug 2026 03:51:05 +0000 Subject: [PATCH 06/17] docs: point cnpg subsite at the 1.29 release docs (#995) sites.yaml resolved the CloudNativePG subsite to the cnpg-docs main branch (version: "main"), so ExternalSite links landed on the in-development docs instead of the released ones. Point it at the released version 1.29, matching the convention used by the other data-service subsites. Co-authored-by: Claude Opus 5 (1M context) --- sites.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sites.yaml b/sites.yaml index 5fcd17da0..fec4643c5 100644 --- a/sites.yaml +++ b/sites.yaml @@ -115,7 +115,7 @@ en: Alauda support for CloudNativePG zh: Alauda support for CloudNativePG base: /cnpg - version: "main" + version: "1.29" repo: https://github.com/alauda/cnpg-docs - name: costmanagement displayName: From c71c6b0f59b460d98d3e870edd9388b242738cdb Mon Sep 17 00:00:00 2001 From: Chao Zhou Date: Thu, 6 Aug 2026 11:56:50 +0800 Subject: [PATCH 07/17] docs: correct HCP OS support boundary --- docs/en/configure/clusters/overview.mdx | 4 ++-- docs/en/configure/hosted_control_planes/overview.mdx | 2 +- docs/en/overview/cluster-management-models.mdx | 2 +- docs/en/overview/glossary.mdx | 2 +- docs/en/overview/learn-more.mdx | 2 +- docs/en/overview/platform-model.mdx | 2 +- docs/en/overview/version-and-lifecycle.mdx | 4 ++-- 7 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/en/configure/clusters/overview.mdx b/docs/en/configure/clusters/overview.mdx index 2c4483011..cf39ea43e 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.4 scenario. | [About Hosted Control Plane](../hosted_control_planes/overview.mdx) | HCP remains Technology Preview in 4.4 and is not production-supported. | +| Evaluate HCP in a 4.4 non-production proof-of-concept (POC) scenario. | [About Hosted Control Plane](../hosted_control_planes/overview.mdx) | HCP remains Technology Preview and supports only traditional operating systems; Alauda OS is not supported. | | 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.4, HCP remains 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`). In 4.4, HCP remains Technology Preview and is intended only for non-production proof-of-concept (POC) evaluation. Disconnected environments are supported. The HCP POC supports only traditional operating systems; Alauda OS is not supported. For evaluation details, see [About Hosted Control Plane](../hosted_control_planes/overview.mdx). ## Third-Party Cluster Onboarding diff --git a/docs/en/configure/hosted_control_planes/overview.mdx b/docs/en/configure/hosted_control_planes/overview.mdx index 24a556f67..7539edbde 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.4, HCP remains 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. +In 4.4, HCP remains Technology Preview and is intended only for non-production proof-of-concept (POC) evaluation. Disconnected environments are supported. The HCP POC 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/overview/cluster-management-models.mdx b/docs/en/overview/cluster-management-models.mdx index cf493f975..c5e98aee7 100644 --- a/docs/en/overview/cluster-management-models.mdx +++ b/docs/en/overview/cluster-management-models.mdx @@ -32,7 +32,7 @@ Control-plane topology explains where Kubernetes control plane components run. | Topology | Meaning | 4.4 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`). | Technology Preview; non-production proof-of-concept (POC) evaluation only; disconnected environments are supported; traditional operating systems only; Alauda OS is not supported. | 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. diff --git a/docs/en/overview/glossary.mdx b/docs/en/overview/glossary.mdx index 2d8c6d125..8a0a7a881 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.4, HCP remains Technology Preview and is 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`). In 4.4, HCP remains Technology Preview, is limited to non-production proof-of-concept (POC) evaluation on traditional operating systems, and does not support Alauda OS. | [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) | diff --git a/docs/en/overview/learn-more.mdx b/docs/en/overview/learn-more.mdx index d33576c53..75e773792 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.4 scenario. | [About Hosted Control Plane](../configure/hosted_control_planes/overview.mdx) | +| Evaluate HCP in a 4.4 non-production proof-of-concept (POC) scenario. | [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 8dc44caad..5f785263d 100644 --- a/docs/en/overview/platform-model.mdx +++ b/docs/en/overview/platform-model.mdx @@ -40,7 +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.4, HCP remains 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.4. +For 4.4, HCP remains Technology Preview and is intended only for non-production proof-of-concept (POC) evaluation. Disconnected environments are supported. The HCP POC supports only traditional operating systems; Alauda OS is not supported. Do not use HCP documentation as production topology, sizing, HA, or backup/restore guidance for 4.4. For HCP scope and tasks, see [About Hosted Control Plane](../configure/hosted_control_planes/overview.mdx). diff --git a/docs/en/overview/version-and-lifecycle.mdx b/docs/en/overview/version-and-lifecycle.mdx index 8a3308f73..5c3f32cac 100644 --- a/docs/en/overview/version-and-lifecycle.mdx +++ b/docs/en/overview/version-and-lifecycle.mdx @@ -42,7 +42,7 @@ Read runtime, OS, CRI, and CPU architecture information by responsibility bounda | Environment | How to read support information | | --- | --- | | 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 HCP-specific documentation and release notes. HCP runtime and version information is not replaced by a global platform runtime statement. | +| HCP environments | For 4.4, HCP is limited to non-production proof-of-concept (POC) evaluation on traditional operating systems; Alauda OS is not supported. Use HCP-specific documentation and release notes for runtime and version information. | | 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. | @@ -76,7 +76,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.4, HCP remains 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 4.4, HCP remains Technology Preview and is limited to non-production proof-of-concept (POC) evaluation on traditional operating systems; Alauda OS is not 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 From 3de1e2733ce0902e5a253ff45439b1bd7ecc7e9f Mon Sep 17 00:00:00 2001 From: fyuan1316 Date: Thu, 6 Aug 2026 12:51:27 +0800 Subject: [PATCH 08/17] point to npu v26.6 (#1000) Signed-off-by: Yuan Fang --- sites.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sites.yaml b/sites.yaml index fec4643c5..38652df33 100644 --- a/sites.yaml +++ b/sites.yaml @@ -59,7 +59,7 @@ en: Alauda Ascend NPU zh: Alauda Ascend NPU base: /npu - version: "main" + version: "26.6" repo: https://github.com/alauda/ascend-docs - name: mysql-pxc displayName: From 5b916b8b913127a9ece9ea4c74eca003884dd68d Mon Sep 17 00:00:00 2001 From: Alan Wang Date: Thu, 6 Aug 2026 13:57:18 +0800 Subject: [PATCH 09/17] feat: remove servicemeshv1 from sites.yaml (#998) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 王然 --- sites.yaml | 7 ------- 1 file changed, 7 deletions(-) diff --git a/sites.yaml b/sites.yaml index 38652df33..8d091d5d7 100644 --- a/sites.yaml +++ b/sites.yaml @@ -1,10 +1,3 @@ -- name: servicemeshv1 - displayName: - en: Alauda Service Mesh v1 - zh: Alauda Service Mesh v1 - base: /servicemeshv1 - version: "4.3" - repo: https://github.com/alauda/asm-docs - name: servicemesh displayName: en: Alauda Service Mesh v2 From 8531e7a17c5a2d21b915d94794e8a2f0ba4ff4d5 Mon Sep 17 00:00:00 2001 From: Seer Date: Thu, 6 Aug 2026 02:14:41 -0400 Subject: [PATCH 10/17] chore: updated kafka/rabbitmq site version (#1002) --- sites.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sites.yaml b/sites.yaml index 8d091d5d7..8138720d7 100644 --- a/sites.yaml +++ b/sites.yaml @@ -80,7 +80,7 @@ en: Alauda Streaming Service for Kafka zh: Alauda Streaming Service for Kafka base: /kafka - version: "4.2" + version: "4.3" repo: https://github.com/alauda/kafka-docs - name: keycloak displayName: @@ -94,7 +94,7 @@ en: Alauda Streaming Service for RabbitMQ zh: Alauda Streaming Service for RabbitMQ base: /rabbitmq - version: "4.1" + version: "4.3" repo: https://github.com/alauda/rabbitmq-docs - name: postgresql displayName: From f955d82240445516dc5eba8b7c305ac30d4bd7ac Mon Sep 17 00:00:00 2001 From: Chao Zhou Date: Thu, 6 Aug 2026 14:49:53 +0800 Subject: [PATCH 11/17] docs: simplify OS compatibility guidance --- docs/en/install/index.mdx | 2 +- docs/en/install/installing.mdx | 2 +- docs/en/install/overview.mdx | 2 +- docs/en/install/prepare/node_preprocessing.mdx | 12 +++--------- docs/en/upgrade/index.mdx | 2 +- docs/en/upgrade/upgrade_global_cluster.mdx | 2 +- docs/en/upgrade/upgrade_workload_cluster.mdx | 2 +- 7 files changed, 9 insertions(+), 15 deletions(-) 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 89e1600f9..eb4850670 100644 --- a/docs/en/install/prepare/node_preprocessing.mdx +++ b/docs/en/install/prepare/node_preprocessing.mdx @@ -17,17 +17,11 @@ The following table lists the supported operating systems, their validated versi The platform enforces the version-matching granularity declared in the support list: - **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**: 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 an official distribution kernel from that series that is validated for the installed patch. Do not assume that an arbitrary newer kernel is supported. +- **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. - ACP 4.4 requires cgroup v2 and a kernel version of 5.8 or later. Operating systems from earlier ACP release baselines that cannot meet these requirements are not supported for ACP 4.4. -::: - -:::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. +- `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 @@ -152,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/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/upgrade_global_cluster.mdx b/docs/en/upgrade/upgrade_global_cluster.mdx index c3d7fdee3..22ae4e4d7 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 diff --git a/docs/en/upgrade/upgrade_workload_cluster.mdx b/docs/en/upgrade/upgrade_workload_cluster.mdx index 18b907120..ecd558608 100644 --- a/docs/en/upgrade/upgrade_workload_cluster.mdx +++ b/docs/en/upgrade/upgrade_workload_cluster.mdx @@ -5,7 +5,7 @@ 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. From 1bb156157dcda13d0d37d34f3739ce9b28c57333 Mon Sep 17 00:00:00 2001 From: Chao Zhou Date: Thu, 6 Aug 2026 16:36:41 +0800 Subject: [PATCH 12/17] docs: centralize upgrade and support boundaries --- docs/en/configure/clusters/overview.mdx | 18 +++++------- .../hosted_control_planes/overview.mdx | 2 +- .../en/overview/cluster-management-models.mdx | 6 ++-- docs/en/overview/core-and-extensions.mdx | 16 +---------- docs/en/overview/glossary.mdx | 2 +- .../en/overview/kubernetes-support-matrix.mdx | 28 ++----------------- docs/en/overview/learn-more.mdx | 2 +- docs/en/overview/platform-model.mdx | 4 +-- docs/en/overview/version-and-lifecycle.mdx | 15 ++++------ docs/en/ui/cli_tools/ac/upgrading-clusters.md | 4 +-- docs/en/upgrade/overview.mdx | 2 +- docs/en/upgrade/pre-upgrade.mdx | 14 +++++----- docs/en/upgrade/upgrade_global_cluster.mdx | 13 ++++----- docs/en/upgrade/upgrade_workload_cluster.mdx | 2 +- 14 files changed, 40 insertions(+), 88 deletions(-) diff --git a/docs/en/configure/clusters/overview.mdx b/docs/en/configure/clusters/overview.mdx index cf39ea43e..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 in a 4.4 non-production proof-of-concept (POC) scenario. | [About Hosted Control Plane](../hosted_control_planes/overview.mdx) | HCP remains Technology Preview and supports only traditional operating systems; Alauda OS is not 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.4, HCP remains Technology Preview and is intended only for non-production proof-of-concept (POC) evaluation. Disconnected environments are supported. The HCP POC supports only traditional operating systems; Alauda OS is not supported. 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,18 +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.4 +### Upgrade Prerequisite Behavior -- The current 4.4 release line supports Kubernetes 1.35 for platform-managed cluster scenarios. -- Before a `global` cluster upgrade, workload clusters must remain within the compatible versions 1.35, 1.34, 1.33, and 1.32. -- Kubernetes 1.28 through 1.35 have completed third-party cluster onboarding validation and are product-supported. Provider prerequisites and exact Extension compatibility still apply. -- The third-party onboarding range is separate from the compatible Kubernetes versions used to determine whether the `global` cluster can be upgraded. -- The default Extend baseline validates the Operator and Cluster Plugin mechanisms, with ClickHouse-based logging and VictoriaMetrics-based monitoring as default validated capabilities. -- 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 7539edbde..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.4, HCP remains Technology Preview and is intended only for non-production proof-of-concept (POC) evaluation. Disconnected environments are supported. The HCP POC supports only traditional operating systems; Alauda OS is not supported. 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/overview/cluster-management-models.mdx b/docs/en/overview/cluster-management-models.mdx index c5e98aee7..87de3230b 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.4 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; non-production proof-of-concept (POC) evaluation only; disconnected environments are supported; traditional operating systems only; Alauda OS is not supported. | +| 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.4, Kubernetes 1.28 through 1.35 have completed third-party cluster onboarding validation and are product-supported. Provider prerequisites and exact Extension compatibility still apply. +Use the product-supported onboarding range in the [Kubernetes Support Matrix](./kubernetes-support-matrix.mdx). The documented range does not override provider prerequisites or exact Extension compatibility. 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 886290d66..1e18f11b8 100644 --- a/docs/en/overview/core-and-extensions.mdx +++ b/docs/en/overview/core-and-extensions.mdx @@ -45,24 +45,10 @@ For Cluster Plugin details, see [Cluster Plugin](../extend/cluster_plugin.mdx). 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; 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.4, the default Extend baseline validates the platform mechanisms for installing and using: - -- Operators. -- Cluster Plugins. - -The default validated capabilities delivered through those mechanisms include: - -- 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 8a0a7a881..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.4, HCP remains Technology Preview, is limited to non-production proof-of-concept (POC) evaluation on traditional operating systems, and does not support Alauda OS. | [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 bd81536aa..0a6c5523d 100644 --- a/docs/en/overview/kubernetes-support-matrix.mdx +++ b/docs/en/overview/kubernetes-support-matrix.mdx @@ -34,15 +34,7 @@ At any point in the release line, create clusters only with a Kubernetes target | 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.4 Notes - -- The current 4.4 release line supports Kubernetes 1.35 for platform-managed cluster creation. -- Before upgrading the `global` cluster to 4.4, workload clusters must remain within Kubernetes 1.35, 1.34, 1.33, and 1.32. -- 4.4 can be upgraded directly from supported 4.1.x, 4.2.x, and 4.3.x releases. A 4.0.x environment must first upgrade to a supported intermediate release. See [Pre-Upgrade](../upgrade/pre-upgrade.mdx). - -For upgrade planning, see [Upgrade Overview](../upgrade/overview.mdx) and [Pre-Upgrade](../upgrade/pre-upgrade.mdx). - -## Third-Party Cluster Product-Supported Onboarding Range +## Third-Party Cluster Product-Supported Onboarding Range \{#third-party-cluster-product-supported-onboarding-range} For 4.4, third-party Kubernetes clusters have been tested and are product-supported for onboarding from Kubernetes 1.28 through 1.35, inclusive. Kubernetes minors outside this range are not declared product-supported for third-party cluster onboarding. @@ -59,23 +51,7 @@ When onboarding third-party clusters, also check: - 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.4, the default Extend baseline validates the platform mechanisms for installing and using: - -- Operators. -- Cluster Plugins. - -The default validated capabilities delivered through those Extension mechanisms include: - -- 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 75e773792..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 in a 4.4 non-production proof-of-concept (POC) 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 5f785263d..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.4, HCP remains Technology Preview and is intended only for non-production proof-of-concept (POC) evaluation. Disconnected environments are supported. The HCP POC supports only traditional operating systems; Alauda OS is not supported. Do not use HCP documentation as production topology, sizing, HA, or backup/restore guidance for 4.4. - -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 5c3f32cac..f75e38776 100644 --- a/docs/en/overview/version-and-lifecycle.mdx +++ b/docs/en/overview/version-and-lifecycle.mdx @@ -10,20 +10,17 @@ Use [Kubernetes Support Matrix](./kubernetes-support-matrix.mdx) for the exact K ## Product And Kubernetes Versions -For the current 4.4 release line: +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.35. -- Before upgrading the `global` cluster to 4.4, workload clusters must remain within the compatible versions 1.35, 1.34, 1.33, and 1.32. -- 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. -The documentation is maintained for the 4.4 minor release line rather than separately for every 4.4.x patch. If a later patch adds another Kubernetes minor, the 4.4 matrix is updated. Exact Kubernetes builds come from the versions offered by the platform and release-specific artifacts, not from this lifecycle overview. +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.4, Kubernetes 1.28 through 1.35 have completed third-party cluster onboarding validation and are product-supported. Kubernetes minors outside this range are not declared product-supported for onboarding. +Use the [Third-Party Cluster Product-Supported Onboarding Range](./kubernetes-support-matrix.mdx#third-party-cluster-product-supported-onboarding-range) in the Kubernetes support matrix for the current numerical range. This range is separate from: @@ -42,7 +39,7 @@ Read runtime, OS, CRI, and CPU architecture information by responsibility bounda | Environment | How to read support information | | --- | --- | | 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 | For 4.4, HCP is limited to non-production proof-of-concept (POC) evaluation on traditional operating systems; Alauda OS is not supported. Use HCP-specific documentation and release notes for runtime and version information. | +| 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. | @@ -76,7 +73,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.4, HCP remains Technology Preview and is limited to non-production proof-of-concept (POC) evaluation on traditional operating systems; Alauda OS is not 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..fb68c827e 100644 --- a/docs/en/ui/cli_tools/ac/upgrading-clusters.md +++ b/docs/en/ui/cli_tools/ac/upgrading-clusters.md @@ -282,9 +282,9 @@ 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 offered ACP 4.4 target upgrades the cluster to Kubernetes 1.35 and `admin-gates` contains `ack-4.4-kubernetes-1.35-kernel-update`, complete the [Kubernetes 1.35 node readiness checks](/upgrade/pre-upgrade.mdx#kubernetes-135-node-readiness) on every production node in the target cluster. -3. Write the acknowledgement to the global-side `admin-acks` ConfigMap: +3. After completing the gate requirements, write the applicable acknowledgement to the global-side `admin-acks` ConfigMap. For the Kubernetes 1.35 gate: ```bash kubectl -n cpaas-system patch configmap admin-acks --type merge \ diff --git a/docs/en/upgrade/overview.mdx b/docs/en/upgrade/overview.mdx index bbf471145..3efeebb8f 100644 --- a/docs/en/upgrade/overview.mdx +++ b/docs/en/upgrade/overview.mdx @@ -3,7 +3,7 @@ weight: 10 --- # Overview -ACP 4.4 uses the 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. diff --git a/docs/en/upgrade/pre-upgrade.mdx b/docs/en/upgrade/pre-upgrade.mdx index 35c0752bc..bd5efaf83 100644 --- a/docs/en/upgrade/pre-upgrade.mdx +++ b/docs/en/upgrade/pre-upgrade.mdx @@ -6,14 +6,14 @@ weight: 20 **Supported upgrade paths:** -* **From `4.1.x` → `4.4`** -* **From `4.2.x` → `4.4`** -* **From `4.3.x` → `4.4`** +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. -ACP 4.0.x cannot be upgraded directly to ACP 4.4. Upgrade the environment to a supported 4.1.x, 4.2.x, or 4.3.x release first, and then upgrade to ACP 4.4. +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 @@ -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 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 offered ACP 4.4 target upgrades the cluster to Kubernetes 1.35 and reports the corresponding administrator acknowledgement gate, 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: diff --git a/docs/en/upgrade/upgrade_global_cluster.mdx b/docs/en/upgrade/upgrade_global_cluster.mdx index 22ae4e4d7..9dc1e5cdf 100644 --- a/docs/en/upgrade/upgrade_global_cluster.mdx +++ b/docs/en/upgrade/upgrade_global_cluster.mdx @@ -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.4 uses the 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.4, verify that every workload cluster is on a compatible Kubernetes version. For the current ACP 4.4 release line, the compatible versions are 1.35, 1.34, 1.33, and 1.32. This prerequisite is separate from the third-party cluster onboarding 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. @@ -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,13 +189,13 @@ 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 offered ACP 4.4 target upgrades the cluster to Kubernetes 1.35 and `admin-gates` contains the following key, complete the Kubernetes 1.35 readiness checks before acknowledging it: ```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. +Complete the [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: @@ -217,7 +217,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 +229,6 @@ data: preflight: | disabled: - ResourcePatchUpgradeable - - VersionUpgradePath ``` ### Deploy the cluster version operator \{#deploy-the-cluster-version-operator} diff --git a/docs/en/upgrade/upgrade_workload_cluster.mdx b/docs/en/upgrade/upgrade_workload_cluster.mdx index ecd558608..3f53090b5 100644 --- a/docs/en/upgrade/upgrade_workload_cluster.mdx +++ b/docs/en/upgrade/upgrade_workload_cluster.mdx @@ -10,7 +10,7 @@ This page covers the **traditional operating system** path for workload clusters 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.4 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. From dd6f4ee2c390bcd0afbaabbe38122824a2f5feec Mon Sep 17 00:00:00 2001 From: Chao Zhou Date: Fri, 7 Aug 2026 12:25:23 +0800 Subject: [PATCH 13/17] docs: address remaining ACP 4.4 review feedback --- docs/en/install/global_dr.mdx | 2 +- docs/en/overview/architecture.mdx | 2 +- docs/en/overview/availability-and-recovery.mdx | 2 +- docs/en/overview/cluster-management-models.mdx | 2 +- docs/en/overview/kubernetes-support-matrix.mdx | 12 ++++++------ docs/en/overview/release_notes.mdx | 17 ++++------------- docs/en/overview/version-and-lifecycle.mdx | 8 +++++--- docs/en/ui/cli_tools/ac/upgrading-clusters.md | 7 ++++--- docs/en/upgrade/overview.mdx | 2 +- docs/en/upgrade/pre-upgrade.mdx | 8 ++++---- docs/en/upgrade/upgrade_global_cluster.mdx | 11 ++++++----- 11 files changed, 34 insertions(+), 39 deletions(-) diff --git a/docs/en/install/global_dr.mdx b/docs/en/install/global_dr.mdx index 01b69e230..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 page documents disaster recovery for `global` clusters running on a **traditional operating system**. Global Cluster Disaster Recovery is also supported on Immutable Infrastructure with Huawei DCS, VMware vSphere, and Huawei Cloud Stack; use for that path. +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/overview/architecture.mdx b/docs/en/overview/architecture.mdx index 7794e529e..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.4 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 f0d8eb562..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.4, 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 87de3230b..bd3b7df53 100644 --- a/docs/en/overview/cluster-management-models.mdx +++ b/docs/en/overview/cluster-management-models.mdx @@ -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. -Use the product-supported onboarding range in the [Kubernetes Support Matrix](./kubernetes-support-matrix.mdx). The documented range does not override provider prerequisites or exact Extension compatibility. +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/kubernetes-support-matrix.mdx b/docs/en/overview/kubernetes-support-matrix.mdx index 0a6c5523d..c311e2a10 100644 --- a/docs/en/overview/kubernetes-support-matrix.mdx +++ b/docs/en/overview/kubernetes-support-matrix.mdx @@ -14,7 +14,7 @@ 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 product-supported onboarding range | The Kubernetes minor versions that have completed third-party cluster onboarding validation and are product-supported. Provider prerequisites and exact Extension compatibility still apply. | +| Third-party cluster product-supported onboarding range | The Kubernetes minor versions for which third-party cluster onboarding has completed product validation. | ## Version Support Matrix \{#version-support-matrix} @@ -36,20 +36,20 @@ At any point in the release line, create clusters only with a Kubernetes target ## Third-Party Cluster Product-Supported Onboarding Range \{#third-party-cluster-product-supported-onboarding-range} -For 4.4, third-party Kubernetes clusters have been tested and are product-supported for onboarding from Kubernetes 1.28 through 1.35, inclusive. Kubernetes minors outside this range are not declared product-supported for third-party cluster onboarding. +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. -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. +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. -Product support for the onboarding range does not override cluster-family or provider prerequisites. Check the compatibility metadata and documentation for each exact Operator or Cluster Plugin version. +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. -When onboarding third-party clusters, also check: +This range answers only whether the Kubernetes minor has been tested for third-party cluster onboarding. Before onboarding a cluster, also verify: - 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. +- Compatibility metadata and documentation for each exact Operator or Cluster Plugin version. 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). diff --git a/docs/en/overview/release_notes.mdx b/docs/en/overview/release_notes.mdx index 3a1a6a825..1c50a8a9f 100644 --- a/docs/en/overview/release_notes.mdx +++ b/docs/en/overview/release_notes.mdx @@ -12,7 +12,7 @@ Review release notes with the [Kubernetes Support Matrix](./kubernetes-support-m 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 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 product-supported onboarding range. For more information, see [Kubernetes Support Matrix](./kubernetes-support-matrix.mdx). @@ -71,20 +71,11 @@ The experience is designed for gradual migration and works with the Web Console For runtime and architecture boundaries, see [Version and Lifecycle](./version-and-lifecycle.mdx). -#### Expanded Third-Party Cluster Accepted Onboarding Range +#### Expanded Third-Party Cluster Onboarding -For third-party clusters, 4.3 accepts Kubernetes versions in the range `>=1.19.0 <1.35.0`. + 4.3 expanded third-party cluster onboarding to a broader product-tested Kubernetes range. For the current tested range, see [Third-Party Cluster Product-Supported Onboarding Range](./kubernetes-support-matrix.mdx#third-party-cluster-product-supported-onboarding-range). -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 default Extend baseline covers these 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. +The onboarding range is separate from the Compatible Versions used to determine whether the `global` cluster can be upgraded. It answers Kubernetes-version eligibility only; provider prerequisites and exact Extension compatibility must be checked separately. 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). diff --git a/docs/en/overview/version-and-lifecycle.mdx b/docs/en/overview/version-and-lifecycle.mdx index f75e38776..254f10269 100644 --- a/docs/en/overview/version-and-lifecycle.mdx +++ b/docs/en/overview/version-and-lifecycle.mdx @@ -20,15 +20,17 @@ For the exact table, see [Kubernetes Support Matrix](./kubernetes-support-matrix ## Third-Party Cluster Onboarding Range -Use the [Third-Party Cluster Product-Supported Onboarding Range](./kubernetes-support-matrix.mdx#third-party-cluster-product-supported-onboarding-range) in the Kubernetes support matrix for the current numerical range. +Use the [Third-Party Cluster Product-Supported Onboarding Range](./kubernetes-support-matrix.mdx#third-party-cluster-product-supported-onboarding-range) in the Kubernetes support matrix for the current tested range. + +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 range answers Kubernetes-version validation only. Before onboarding, check cluster-family or provider prerequisites, connectivity, credentials, installed components, provider caveats, and exact Extension compatibility separately. For cluster model boundaries, see [Cluster Management Models](./cluster-management-models.mdx). diff --git a/docs/en/ui/cli_tools/ac/upgrading-clusters.md b/docs/en/ui/cli_tools/ac/upgrading-clusters.md index fb68c827e..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. If the offered ACP 4.4 target upgrades the cluster to Kubernetes 1.35 and `admin-gates` contains `ack-4.4-kubernetes-1.35-kernel-update`, complete the [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. After completing the gate requirements, write the applicable acknowledgement to the global-side `admin-acks` ConfigMap. For the Kubernetes 1.35 gate: +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/overview.mdx b/docs/en/upgrade/overview.mdx index 3efeebb8f..2abc567b1 100644 --- a/docs/en/upgrade/overview.mdx +++ b/docs/en/upgrade/overview.mdx @@ -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.4, workload clusters must remain within the ACP 4.4 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 diff --git a/docs/en/upgrade/pre-upgrade.mdx b/docs/en/upgrade/pre-upgrade.mdx index bd5efaf83..6536c2e33 100644 --- a/docs/en/upgrade/pre-upgrade.mdx +++ b/docs/en/upgrade/pre-upgrade.mdx @@ -19,8 +19,8 @@ For clusters that use Alauda OS, the ACP Distribution Version must follow the sa ## 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.4, all workload clusters must remain within the ACP 4.4 **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.4 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. -## Kubernetes 1.35 Node Readiness \{#kubernetes-135-node-readiness} +## Kubernetes 1.35 or Later Node Readiness \{#kubernetes-135-node-readiness} -If the offered ACP 4.4 target upgrades the cluster to Kubernetes 1.35 and reports the corresponding administrator acknowledgement gate, verify every production node that will run the target cluster before acknowledging the gate. +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: diff --git a/docs/en/upgrade/upgrade_global_cluster.mdx b/docs/en/upgrade/upgrade_global_cluster.mdx index 9dc1e5cdf..e03f52958 100644 --- a/docs/en/upgrade/upgrade_global_cluster.mdx +++ b/docs/en/upgrade/upgrade_global_cluster.mdx @@ -189,19 +189,20 @@ Inspect the current gates: kubectl -n cpaas-system get configmap admin-gates -o yaml ``` -If the offered ACP 4.4 target upgrades the cluster to Kubernetes 1.35 and `admin-gates` contains the following key, complete the Kubernetes 1.35 readiness checks before acknowledging it: +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 ``` -Complete the [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: From e21807ed9c1e8835b165a30493868cdde7d4aaa2 Mon Sep 17 00:00:00 2001 From: Chao Zhou Date: Fri, 7 Aug 2026 12:32:15 +0800 Subject: [PATCH 14/17] Revert "Merge remote-tracking branch 'origin/master' into chao/ait-73302-acp-44-doc-alignment" This reverts commit f28310b4520481ab093fcada2ef5f7ff0b5eb02c, reversing changes made to dd6f4ee2c390bcd0afbaabbe38122824a2f5feec. --- docs/en/upgrade/pre-upgrade.mdx | 11 ----------- sites.yaml | 17 ++++++++++++----- 2 files changed, 12 insertions(+), 16 deletions(-) diff --git a/docs/en/upgrade/pre-upgrade.mdx b/docs/en/upgrade/pre-upgrade.mdx index 4628491fb..6536c2e33 100644 --- a/docs/en/upgrade/pre-upgrade.mdx +++ b/docs/en/upgrade/pre-upgrade.mdx @@ -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/sites.yaml b/sites.yaml index 8138720d7..3cf5df27b 100644 --- a/sites.yaml +++ b/sites.yaml @@ -1,3 +1,10 @@ +- name: servicemeshv1 + displayName: + en: Alauda Service Mesh v1 + zh: Alauda Service Mesh v1 + base: /servicemeshv1 + version: "4.3" + repo: https://github.com/alauda/asm-docs - name: servicemesh displayName: en: Alauda Service Mesh v2 @@ -24,7 +31,7 @@ en: Alauda AI zh: Alauda AI base: /ai - version: "2.7" + version: "2.3" repo: https://github.com/alauda/aml-docs - name: hyperflux displayName: @@ -52,7 +59,7 @@ en: Alauda Ascend NPU zh: Alauda Ascend NPU base: /npu - version: "26.6" + version: "main" repo: https://github.com/alauda/ascend-docs - name: mysql-pxc displayName: @@ -80,7 +87,7 @@ en: Alauda Streaming Service for Kafka zh: Alauda Streaming Service for Kafka base: /kafka - version: "4.3" + version: "4.2" repo: https://github.com/alauda/kafka-docs - name: keycloak displayName: @@ -94,7 +101,7 @@ en: Alauda Streaming Service for RabbitMQ zh: Alauda Streaming Service for RabbitMQ base: /rabbitmq - version: "4.3" + version: "4.1" repo: https://github.com/alauda/rabbitmq-docs - name: postgresql displayName: @@ -108,7 +115,7 @@ en: Alauda support for CloudNativePG zh: Alauda support for CloudNativePG base: /cnpg - version: "1.29" + version: "main" repo: https://github.com/alauda/cnpg-docs - name: costmanagement displayName: From 84dc3b66e452b56cb43c6c50a5738e26b5ab3fc4 Mon Sep 17 00:00:00 2001 From: Chao Zhou Date: Fri, 7 Aug 2026 13:08:20 +0800 Subject: [PATCH 15/17] docs: scope node baseline to Kubernetes 1.35 and later --- docs/en/install/prepare/node_preprocessing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/install/prepare/node_preprocessing.mdx b/docs/en/install/prepare/node_preprocessing.mdx index eb4850670..9ab2fb064 100644 --- a/docs/en/install/prepare/node_preprocessing.mdx +++ b/docs/en/install/prepare/node_preprocessing.mdx @@ -20,7 +20,7 @@ The platform enforces the version-matching granularity declared in the support l - **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 -- ACP 4.4 requires cgroup v2 and a kernel version of 5.8 or later. Operating systems from earlier ACP release baselines that cannot meet these requirements are not supported for ACP 4.4. +- 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. ::: From 6277ff2e389f5ad6706652eeff9004b15f5e3c40 Mon Sep 17 00:00:00 2001 From: Chao Zhou Date: Fri, 7 Aug 2026 13:22:30 +0800 Subject: [PATCH 16/17] docs: restore third-party validation scope --- docs/en/overview/core-and-extensions.mdx | 2 +- .../en/overview/kubernetes-support-matrix.mdx | 27 ++++++++++++++++--- docs/en/overview/version-and-lifecycle.mdx | 2 +- 3 files changed, 25 insertions(+), 6 deletions(-) diff --git a/docs/en/overview/core-and-extensions.mdx b/docs/en/overview/core-and-extensions.mdx index 1e18f11b8..402150fad 100644 --- a/docs/en/overview/core-and-extensions.mdx +++ b/docs/en/overview/core-and-extensions.mdx @@ -45,7 +45,7 @@ For Cluster Plugin details, see [Cluster Plugin](../extend/cluster_plugin.mdx). 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, 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; it is not an Extension compatibility matrix. +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). diff --git a/docs/en/overview/kubernetes-support-matrix.mdx b/docs/en/overview/kubernetes-support-matrix.mdx index c311e2a10..20e508a70 100644 --- a/docs/en/overview/kubernetes-support-matrix.mdx +++ b/docs/en/overview/kubernetes-support-matrix.mdx @@ -14,7 +14,7 @@ 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 product-supported onboarding range | The Kubernetes minor versions for which third-party cluster onboarding has completed product validation. | +| 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} @@ -34,22 +34,41 @@ At any point in the release line, create clusters only with a Kubernetes target | 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 | -## Third-Party Cluster Product-Supported Onboarding Range \{#third-party-cluster-product-supported-onboarding-range} +## Product-Tested Scope for Third-Party Clusters \{#third-party-cluster-product-supported-onboarding-range} + +### Product-Supported Kubernetes Range 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. 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. +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 answers only whether the Kubernetes minor has been tested for third-party cluster onboarding. Before onboarding a cluster, also verify: +### Default Validation Scope + +For third-party clusters within the published Kubernetes range, default product validation covers: + +- 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. + +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. + +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. + +### Additional Compatibility Checks + +Before onboarding a cluster, also verify: - 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. -- Compatibility metadata and documentation for each exact Operator or Cluster Plugin version. +- Compatibility metadata and documentation for each exact Operator or Cluster Plugin version that you plan to install. 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). diff --git a/docs/en/overview/version-and-lifecycle.mdx b/docs/en/overview/version-and-lifecycle.mdx index 254f10269..4a75381d3 100644 --- a/docs/en/overview/version-and-lifecycle.mdx +++ b/docs/en/overview/version-and-lifecycle.mdx @@ -20,7 +20,7 @@ For the exact table, see [Kubernetes Support Matrix](./kubernetes-support-matrix ## Third-Party Cluster Onboarding Range -Use the [Third-Party Cluster Product-Supported Onboarding Range](./kubernetes-support-matrix.mdx#third-party-cluster-product-supported-onboarding-range) in the Kubernetes support matrix for the current tested range. +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. From e8a09c8f2195cb27a9e3e3e1751995a104496ee0 Mon Sep 17 00:00:00 2001 From: Chao Zhou Date: Fri, 7 Aug 2026 13:35:22 +0800 Subject: [PATCH 17/17] docs: route onboarding prerequisites to workflow guides --- docs/en/overview/kubernetes-support-matrix.mdx | 11 +---------- docs/en/overview/version-and-lifecycle.mdx | 2 +- 2 files changed, 2 insertions(+), 11 deletions(-) diff --git a/docs/en/overview/kubernetes-support-matrix.mdx b/docs/en/overview/kubernetes-support-matrix.mdx index 20e508a70..49c4f29f8 100644 --- a/docs/en/overview/kubernetes-support-matrix.mdx +++ b/docs/en/overview/kubernetes-support-matrix.mdx @@ -59,16 +59,7 @@ Extend is included in the default validation scope because the validated logging 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. -### Additional Compatibility Checks - -Before onboarding a cluster, also verify: - -- 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. -- Compatibility metadata and documentation for each exact Operator or Cluster Plugin version that you plan to install. +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. 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). diff --git a/docs/en/overview/version-and-lifecycle.mdx b/docs/en/overview/version-and-lifecycle.mdx index 4a75381d3..56e08b22d 100644 --- a/docs/en/overview/version-and-lifecycle.mdx +++ b/docs/en/overview/version-and-lifecycle.mdx @@ -30,7 +30,7 @@ This range is separate from: - The workload-cluster compatible versions used before upgrading the `global` cluster. - Support for every provider, capability, operation, or Extension. -The range answers Kubernetes-version validation only. Before onboarding, check cluster-family or provider prerequisites, connectivity, credentials, installed components, provider caveats, and exact Extension compatibility separately. +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).