Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 7 additions & 12 deletions docs/en/configure/clusters/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 <Term name="productShort" /> 4.3 scenario. | [About Hosted Control Plane](../hosted_control_planes/overview.mdx) | HCP is Technology Preview in <Term name="productShort" /> 4.3 and is not production-supported. |
| Evaluate Hosted Control Plane (HCP). | [About Hosted Control Plane](../hosted_control_planes/overview.mdx) | Check the HCP documentation for current maturity, operating system, connectivity, and production-use boundaries. |
| Onboard an existing Kubernetes environment. | [Third-Party Cluster Onboarding](./managed/overview.mdx) | The external owner, distribution, or provider usually owns Kubernetes, node, and infrastructure lifecycle. |
| Choose between direct platform access and reverse-connect onboarding. | [Import Third-Party Clusters](./managed/import/overview.mdx) and [Register Cluster](./managed/register.mdx) | Import and register are onboarding methods, not separate day-2 capability models. |

Expand Down Expand Up @@ -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 <Term name="productShort" />, HCP is implemented through Kamaji (`TenantControlPlane`). In <Term name="productShort" /> 4.3, HCP is Technology Preview, is not production-supported, supports disconnected environments, and defaults to IPI only. For evaluation details, see [About Hosted Control Plane](../hosted_control_planes/overview.mdx).
In <Term name="productShort" />, 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

Expand All @@ -62,19 +62,14 @@ For onboarding workflows, see [Third-Party Cluster Onboarding](./managed/overvie

## Version Compatibility \{#version-compatibility}

When importing or connecting existing clusters, validate the Kubernetes version against the current <Term name="productShort" /> 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.

### <Term name="productShort" /> 4.3 And Later
### Upgrade Prerequisite Behavior

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

### <Term name="productShort" /> 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.
2 changes: 1 addition & 1 deletion docs/en/configure/hosted_control_planes/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 <Term name="productShort" />, HCP is implemented through Kamaji (`TenantControlPlane`).

In <Term name="productShort" /> 4.3, HCP is Technology Preview, is not production-supported, supports disconnected environments, and defaults to Installer-Provisioned Infrastructure (IPI) only. Use HCP for non-production evaluation only. For installation and operation tasks within that scope, follow the HCP guidance below.
HCP is a Technology Preview intended only for non-production proof-of-concept (POC) evaluation. Disconnected environments are supported. HCP supports only traditional operating systems; Alauda OS is not supported. For installation and operation tasks within that scope, follow the HCP guidance below.

<ExternalSite name="hosted-control-plane" />
2 changes: 1 addition & 1 deletion docs/en/install/global_dr.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ weight: 60
# Global Cluster Disaster Recovery

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

## Overview
Expand Down
2 changes: 1 addition & 1 deletion docs/en/install/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ weight: 20
# Install

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

<Overview overviewHeaders={[]} />
2 changes: 1 addition & 1 deletion docs/en/install/installing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ weight: 30
This section describes how to install <Term name="productShort" /> Core and deploy the `global` cluster.

<Directive type="info" title="Installation Path">
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 <ExternalSiteLink name="immutable-infra" href="/global/install.html" children="Installing the global Cluster on Immutable Infrastructure" /> instead.
This installation path applies to clusters running on a **traditional operating system**. If your environment uses Alauda OS, see <ExternalSiteLink name="immutable-infra" href="/global/install.html" children="Installing the global Cluster on Immutable Infrastructure" /> instead.
</Directive>

Before starting the installation, please ensure that you have completed the prerequisite checks, installation package download and verification, node preprocessing, and other preparatory work.
Expand Down
2 changes: 1 addition & 1 deletion docs/en/install/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Use the Install section to plan and complete **<Term name="productShort" /> Core
<Term name="productShort" /> Core installation provides the foundation for the platform management plane. After <Term name="productShort" /> Core is installed and verified, you can create or connect workload clusters and install Extensions according to your platform scenario.

<Directive type="info" title="Installation Path">
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 <ExternalSiteLink name="immutable-infra" href="/global/install.html" children="Installing the global Cluster on Immutable Infrastructure" /> 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 <ExternalSiteLink name="immutable-infra" href="/global/install.html" children="Installing the global Cluster on Immutable Infrastructure" /> instead.
</Directive>

The following work is outside the <Term name="productShort" /> Core installation flow:
Expand Down
45 changes: 13 additions & 32 deletions docs/en/install/prepare/node_preprocessing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,67 +7,50 @@ 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 <Term name="productShort" /> 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 <ExternalSiteLink name="immutable-infra" href="/global/install.html" children="Installing the global Cluster on Immutable Infrastructure" /> instead.
This page applies to nodes running a **traditional operating system** such as Kylin Linux Advanced Server, RHEL, or Ubuntu, which <Term name="productShort" /> 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 <ExternalSiteLink name="immutable-infra" href="/global/install.html" children="Installing the global Cluster on Immutable Infrastructure" /> in the Immutable Infrastructure documentation instead.
:::

## Supported OS and Kernel Versions \{#supported_os_and_kernels}

The following table lists the supported operating systems, their validated versions, and the corresponding tested kernel versions.

The platform enforces strict version matching policies for official support:
The platform enforces the version-matching granularity declared in the support list:

- **OS Version (x.y.z)**: Patch versions (`z`) can vary, but major and minor versions (`x` and `y`) must strictly match the validated versions. Modifying `x` or `y` is not officially supported.
- **Kernel Version (x.y.z-build)**: The build suffix (`build`) can vary, but the core kernel version (`x.y.z`) must strictly match the tested versions. Modifying `x.y.z` is not officially supported.
- **OS version**: Use the distribution release listed below. A different major or minor release is not officially supported unless it is also listed.
- **Kernel version**: Use an official kernel supplied by the operating system vendor. When the list gives an exact `x.y.z-build` value, the build suffix can vary but `x.y.z` must match. When the list gives a kernel series, use a kernel from that series that is validated for the installed <Term name="productShort" /> patch. Do not assume that an arbitrary newer kernel is supported.

:::info
- Only the kernel version shipped with the official operating system is supported. If the OS, kernel version, or CPU architecture does not meet the requirements, please contact technical support.
- Kylin V10, V10-SP1, and V10-SP2 have known kernel issues that may cause **NodePort network access failures**, it is recommended to upgrade to **Kylin V10-SP3**.
:::

:::info
`x86-64-v2` is a CPU instruction set baseline used by some operating systems, platform images, or optional components. For user-provided operating systems, <Term name="productShort" /> 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 <Term name="productShort" />-provided immutable operating system images or platform images, follow the CPU baseline requirements documented for those images.
- For <Term name="productShort" /> 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 <Term name="productShort" /> patch.
- `x86-64-v2` is a CPU instruction set baseline, but <Term name="productShort" /> 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

<Tabs>
<Tab label="Red Hat Enterprise Linux (RHEL)">
- 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**.
</Tab>

<Tab label="CentOS">
- CentOS 7.6 to 7.9: `3.10.0-1127` and `3.10.0-1160`

**Note:** CentOS does not support **Calico Vxlan IPv6**.
</Tab>

<Tab label="Ubuntu">
- 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.
</Tab>

<Tab label="Kylin Linux Advanced Server">
- 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 <Term name="productShort" /> patch

**Note:** Flannel is not supported on Kylin Linux Advanced Server V11.
</Tab>
</Tabs>

### ARM

<Tabs>
<Tab label="Kylin Linux Advanced Server">
- 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 <Term name="productShort" /> 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.
</Tab>
</Tabs>

Expand Down Expand Up @@ -100,9 +83,7 @@ The following is the list of checks:

- **OS and Kernel**
- ✅ The machine's grub boot configuration must have the `transparent_hugepage=never` parameter.
- ✅ CentOS 7.x system machine's grub boot configuration must have the `cgroup.memory=nokmem` parameter.
- ✅ Check whether the kernel modules `ip_vs`, `ip_vs_rr`, `ip_vs_wrr`, and `ip_vs_sh` are enabled.
- ⚠️ When the kernel version is lower than 4.19.0 (or RHEL is lower than 4.18.0), check whether the kernel modules `nf_conntrack_ipv4` and (for IPv6) `nf_conntrack_ipv6` are enabled.
- ⚠️ If the `global` cluster plans to use `Kube-OVN` CNI, the kernel modules `geneve` and `openvswitch` must be enabled.
- ✅ Disable apparmor/selinux and firewall.
- ✅ Disable `swap` .
Expand All @@ -111,7 +92,7 @@ The following is the list of checks:
- ✅ The node's SSH user has `root` privileges and can use `sudo` without the password.
- ✅ The `UseDNS` parameter in `/etc/ssh/sshd_config` must be set to `no`.
- ✅ Set the `UsePAM` parameter in `/etc/ssh/sshd_config` to `no` before adding the node, then restart `sshd`. PAM session policies (such as a forced password change, `pam_access`, `faillock`, or `pam_limits`) can otherwise block the SSH-based node join. After the node reaches the `Ready` state, you can restore `UsePAM yes`. On SELinux-enforcing systems that use password authentication, `UsePAM no` can itself break SSH login; use key-based authentication in that case.
- ✅ `systemctl show --property=DefaultTasksMax` must return `infinity`; a low limit (such as the `512` default on RHEL 7 / CentOS 7) makes busy containers fail to create threads. If it is not `infinity`, set `DefaultTasksMax=infinity` in `/etc/systemd/system.conf` and run `systemctl daemon-reexec`.
- ✅ `systemctl show --property=DefaultTasksMax` must return `infinity`; a low limit can make busy containers fail to create threads. If it is not `infinity`, set `DefaultTasksMax=infinity` in `/etc/systemd/system.conf` and run `systemctl daemon-reexec`.

- **Node Network**
- ✅ `hostname` must comply with the following rules:
Expand Down Expand Up @@ -165,7 +146,7 @@ Before installation, applications may already be running in the docker/nerdctl/c
The following commands can be used for reference.

<Tabs>
<Tab label="CentOS / RedHat">
<Tab label="RHEL">
**Check:**
```bash
for x in \
Expand Down
2 changes: 1 addition & 1 deletion docs/en/overview/architecture.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ weight: 30

<Term name="productShort" /> 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 <Term name="productShort" /> 4.3 boundaries that are not visible in the diagram.
Use the diagram as a high-level view of this model. The architecture details below clarify boundaries that are not visible in the diagram.

![Architecture overview](./assets/arch-overview.svg)

Expand Down
2 changes: 1 addition & 1 deletion docs/en/overview/availability-and-recovery.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 <Term name="productShort" /> 4.3, Global DR has the following scope:
Global DR has the following scope:

- It uses Primary and Standby `global` clusters.
- It relies on real-time synchronization of resource state stored in the Primary `global` cluster etcd, except excluded namespaces.
Expand Down
Loading