Skip to content

[codex] update HCS provider documentation #42

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
chinameok merged 6 commits into from
Apr 16, 2026
Merged

[codex] update HCS provider documentation #42

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
67cd480
docs: update HCS provider documentation
chinameok Apr 10, 2026
2e814ba
docs: fix HCS PSA example
chinameok Apr 10, 2026
5dba9bd
docs: clarify HCS upgrade limitations
chinameok Apr 13, 2026
2e5dc2a
docs: update HCS control plane rollout guidance
chinameok Apr 14, 2026
e578c53
Merge remote-tracking branch 'origin/master' into AIT-68208
chinameok Apr 16, 2026
701d42d
docs: clarify HCS subnet selector guidance
chinameok Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
180 changes: 155 additions & 25 deletions docs/en/create-cluster/huawei-cloud-stack.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ HCS authentication information is stored in a Secret resource.
apiVersion: v1
kind: Secret
metadata:
name: <cluster-name>
name: <credential-secret-name>
namespace: cpaas-system
type: Opaque
data:
Expand All @@ -100,6 +100,8 @@ data:
| `.data.region` | HCS region such as `cn-global-1` (base64-encoded) |
| `.data.externalGlobalDomain` | HCS domain name (base64-encoded) |

You can reuse an existing HCS credential Secret. Its name does not need to match the cluster name, but `HCSCluster.spec.identityRef.name` must reference this Secret.

### Configure Machine Configuration Pool

The `HCSMachineConfigPool` defines pre-configured hostnames and static IP addresses for VMs.
Expand All @@ -110,6 +112,8 @@ The `HCSMachineConfigPool` defines pre-configured hostnames and static IP addres
The configuration pool must include at least as many entries as the number of control plane nodes you plan to deploy.
:::

Use one subnet selector per `networks[]` entry. For new manifests, set either `subnetName` or `subnetId`, but not both. Existing manifests may keep the deprecated `subenetName` field; if you also add `subnetName` while updating that manifest, its value must exactly match `subenetName`. Do not supply conflicting values across `subenetName`, `subnetName`, and `subnetId`.

```yaml
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: HCSMachineConfigPool
Expand All @@ -134,9 +138,16 @@ spec:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `.spec.configs[].hostname` | string | Yes | VM hostname |
| `.spec.configs[].networks[].subnetName` | string | Yes | Subnet name in HCS |
| `.spec.configs[].networks[].ipAddress` | string | Yes | Static IP address |
| `.spec.configs[]` | array | Yes | Non-empty list of machine configurations |
| `.spec.configs[].hostname` | string | Yes | VM hostname. Use lowercase letters, numbers, hyphens (`-`), or dots (`.`); the value must start and end with a lowercase letter or number and must not exceed 253 characters |
| `.spec.configs[].networks[]` | array | Yes | Non-empty list of network configurations for the VM |
| `.spec.configs[].networks[].subnetName` | string | No* | Recommended subnet name field for new manifests |
| `.spec.configs[].networks[].subnetId` | string | No* | Subnet ID. Use this field instead of `subnetName` when the subnet name is ambiguous |
| `.spec.configs[].networks[].ipAddress` | string | Yes | Static IP address for the VM |

*For new manifests, set either `subnetName` or `subnetId`. Existing manifests may continue to use `subenetName`, and may add `subnetName` only if both fields use the same value. Do not provide conflicting subnet selector values.

**Note:** The CRD schema lists `subnetName`, `subenetName`, and `subnetId` as optional fields and does not express their allowed combinations. Follow the provider-level rules above when writing manifests.

### Configure Machine Template

Expand All @@ -149,6 +160,7 @@ The following data disk mount points are recommended for control plane nodes:
- `/var/lib/etcd` - etcd data (10GB+)
- `/var/lib/kubelet` - kubelet data (100GB+)
- `/var/lib/containerd` - container runtime data (100GB+)
- `/var/cpaas` - platform data and logs (40GB+)
:::

```yaml
Expand Down Expand Up @@ -181,6 +193,10 @@ spec:
type: SSD
mountPath: /var/lib/containerd
format: xfs
- size: 40
type: SSD
mountPath: /var/cpaas
format: xfs
```

| Parameter | Type | Required | Description |
Expand All @@ -199,6 +215,8 @@ spec:

*Required when dataVolumes is specified.

**Note:** Do not set runtime identity fields such as `providerID` or `serverId` in `HCSMachineTemplate` manifests. The provider assigns these values when it creates HCS instances.

### Configure KubeadmControlPlane

The `KubeadmControlPlane` defines the Kubernetes control plane configuration.
Expand All @@ -212,20 +230,118 @@ metadata:
spec:
replicas: 3
version: <kubernetes-version>
rolloutStrategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 0
kubeadmConfigSpec:
files:
- path: /etc/kubernetes/admission/psa-config.yaml
owner: root:root
permissions: "0644"
content: |
apiVersion: apiserver.config.k8s.io/v1
kind: AdmissionConfiguration
plugins:
- name: PodSecurity
configuration:
apiVersion: pod-security.admission.config.k8s.io/v1
kind: PodSecurityConfiguration
defaults:
enforce: "privileged"
enforce-version: "latest"
audit: "baseline"
audit-version: "latest"
warn: "baseline"
warn-version: "latest"
exemptions:
usernames: []
runtimeClasses: []
namespaces:
- kube-system
- cpaas-system
- path: /etc/kubernetes/patches/kubeletconfiguration0+strategic.json
owner: root:root
permissions: "0644"
content: |
{
"apiVersion": "kubelet.config.k8s.io/v1beta1",
"kind": "KubeletConfiguration",
"protectKernelDefaults": true,
"tlsCertFile": "/etc/kubernetes/pki/kubelet.crt",
"tlsPrivateKeyFile": "/etc/kubernetes/pki/kubelet.key",
"streamingConnectionIdleTimeout": "5m",
"clientCAFile": "/etc/kubernetes/pki/ca.crt"
}
- path: /etc/kubernetes/encryption-provider.conf
owner: root:root
permissions: "0600"
content: |
apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
- resources:
- secrets
providers:
- aescbc:
keys:
- name: key1
secret: bootstrap-placeholder
- path: /etc/kubernetes/audit/policy.yaml
owner: root:root
permissions: "0644"
content: |
apiVersion: audit.k8s.io/v1
kind: Policy
rules:
- level: Metadata
clusterConfiguration:
imageRepository: <image-repository>
dns:
imageTag: <dns-image-tag>
etcd:
local:
imageTag: <etcd-image-tag>
apiServer:
extraArgs:
audit-log-format: json
audit-log-mode: batch
audit-log-path: /etc/kubernetes/audit/audit.log
audit-policy-file: /etc/kubernetes/audit/policy.yaml
admission-control-config-file: /etc/kubernetes/admission/psa-config.yaml
encryption-provider-config: /etc/kubernetes/encryption-provider.conf
kubelet-certificate-authority: /etc/kubernetes/pki/ca.crt
profiling: "false"
tls-min-version: VersionTLS12
extraVolumes:
- name: vol-dir-0
hostPath: /etc/kubernetes
mountPath: /etc/kubernetes
pathType: Directory
controllerManager:
extraArgs:
bind-address: "::"
flex-volume-plugin-dir: "/opt/libexec/kubernetes/kubelet-plugins/volume/exec/"
profiling: "false"
tls-min-version: VersionTLS12
scheduler:
extraArgs:
bind-address: "::"
profiling: "false"
tls-min-version: VersionTLS12
postKubeadmCommands:
- chmod 600 /var/lib/kubelet/config.yaml
initConfiguration:
patches:
directory: /etc/kubernetes/patches
nodeRegistration:
kubeletExtraArgs:
node-labels: "kube-ovn/role=master"
protect-kernel-defaults: "true"
volume-plugin-dir: "/opt/libexec/kubernetes/kubelet-plugins/volume/exec/"
joinConfiguration:
patches:
directory: /etc/kubernetes/patches
nodeRegistration:
kubeletExtraArgs:
node-labels: "kube-ovn/role=master"
Expand All @@ -239,12 +355,24 @@ spec:
name: <cluster-name>-control-plane
```

The HCS controller also injects files while resolving cloud-init data. It writes `/etc/kubernetes/pki/kubelet.crt`, `/etc/kubernetes/pki/kubelet.key`, and `/etc/kubernetes/encryption-provider.conf` for control plane machines. For the first control plane machine, the controller generates the encryption provider configuration. After the control plane is initialized, it tries to reuse the existing `kube-apiserver` encryption provider configuration. If you include a bootstrap file at `/etc/kubernetes/encryption-provider.conf`, treat it as a placeholder because the controller-generated or synchronized file takes precedence.

**Note:** Configure `apiServer.extraArgs` and `apiServer.extraVolumes` together. If the volume is not mounted, `kube-apiserver` cannot read the files written under `/etc/kubernetes`.

**Note:** For HCS control planes that use a fixed-size static IP pool, keep `rolloutStrategy.rollingUpdate.maxSurge: 0` so replacements happen in a scale-down-then-scale-up order. This default upgrade path usually does not require additional control plane IPs. If you plan to increase control plane replicas or set `maxSurge` greater than `0`, first extend the referenced `HCSMachineConfigPool` with additional hostname and static IP entries.

For component versions (DNS image tag, etcd image tag), refer to the [OS Support Matrix](../overview/os-support-matrix.mdx).

### Configure HCSCluster

The `HCSCluster` resource defines the HCS infrastructure configuration.

The HCS provider creates an ELB on the HCS platform for the Kubernetes API server. This ELB must use mixed load balancing so cluster nodes can also reach the API server through the ELB address.

If you want all ELB-related addresses to be fixed, provide `vipAddress`, `elbVirsubnetL4Ips`, and `elbVirsubnetL7Ips`. Each `elbVirsubnetL4Ips[].ips` and `elbVirsubnetL7Ips[].ips` entry must contain two IPs. If you omit the L4 or L7 virtual subnet IPs, HCS allocates them randomly.

If you set `vipDomainName`, maintain DNS so that the domain resolves to `vipAddress`.

```yaml
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: HCSCluster
Expand All @@ -253,19 +381,19 @@ metadata:
namespace: cpaas-system
spec:
controlPlaneLoadBalancer:
vipAddress: <vip-address>
vipSubnetName: <elb-subnet-name>
vipDomainName: <vip-domain-name>
vipAddress: <control-plane-vip-address>
vipSubnetName: <vip-subnet-name>
vipDomainName: <control-plane-vip-domain-name>
elbVirsubnetL4Ips:
- subnetName: <subnet-name>
ips:
- 192.168.15.101
- 192.168.15.102
- <l4-ip-1>
- <l4-ip-2>
elbVirsubnetL7Ips:
- subnetName: <subnet-name>
ips:
- 192.168.15.103
- 192.168.15.104
- <l7-ip-1>
- <l7-ip-2>
networkType: kube-ovn
network:
vpc:
Expand All @@ -275,10 +403,7 @@ spec:
securityGroup:
name: <security-group-name>
identityRef:
name: <cluster-name>
controlPlaneEndpoint:
host: <vip-address>
port: 6443
name: <credential-secret-name>
```

| Parameter | Type | Required | Description |
Expand All @@ -287,16 +412,21 @@ spec:
| `.spec.network.vpc.name` | string | Yes | VPC name |
| `.spec.network.subnets[].name` | string | Yes | Subnet name list |
| `.spec.network.securityGroup.name` | string | Yes | Security group name |
| `.spec.identityRef.name` | string | Yes | Reference to credential Secret name |
| `.spec.controlPlaneEndpoint.host` | string | No | API server host (VIP address or domain name) |
| `.spec.controlPlaneEndpoint.port` | int | No | API server port (default: 6443) |
| `.spec.controlPlaneLoadBalancer.vipAddress` | string | No* | Control plane VIP address |
| `.spec.controlPlaneLoadBalancer.vipSubnetName` | string | No* | ELB subnet name |
| `.spec.controlPlaneLoadBalancer.vipDomainName` | string | No | VIP domain name with DNS configured |
| `.spec.controlPlaneLoadBalancer.elbVirsubnetL4Ips` | array | No | L4 load balancer IP configuration |
| `.spec.controlPlaneLoadBalancer.elbVirsubnetL7Ips` | array | No | L7 load balancer IP configuration |

*Required when configuring VIP address.
| `.spec.identityRef.name` | string | Yes | Non-empty credential Secret name referenced by `HCSCluster`; this value does not need to match the cluster name |
| `.spec.controlPlaneLoadBalancer` | object | Yes | ELB settings for exposing the control plane API server |
| `.spec.controlPlaneLoadBalancer.vipAddress` | string | Yes | Fixed VIP for the control plane ELB |
| `.spec.controlPlaneLoadBalancer.vipSubnetName` | string | Yes | Subnet name that contains the ELB VIP |
| `.spec.controlPlaneLoadBalancer.vipDomainName` | string | No | Domain name for the VIP; you must maintain DNS so it resolves to `vipAddress` |
| `.spec.controlPlaneLoadBalancer.elbVirsubnetL4Ips[]` | array | No* | L4 virtual subnet IP groups used by mixed load balancing |
| `.spec.controlPlaneLoadBalancer.elbVirsubnetL4Ips[].subnetName` | string | Yes* | Subnet name for the L4 virtual subnet IPs |
| `.spec.controlPlaneLoadBalancer.elbVirsubnetL4Ips[].ips[]` | string | Yes* | Two fixed L4 virtual subnet IPs |
| `.spec.controlPlaneLoadBalancer.elbVirsubnetL7Ips[]` | array | No* | L7 virtual subnet IP groups used by mixed load balancing |
| `.spec.controlPlaneLoadBalancer.elbVirsubnetL7Ips[].subnetName` | string | Yes* | Subnet name for the L7 virtual subnet IPs |
| `.spec.controlPlaneLoadBalancer.elbVirsubnetL7Ips[].ips[]` | string | Yes* | Two fixed L7 virtual subnet IPs |

*Required when you want to fix all ELB-related addresses. If you omit the L4 or L7 virtual subnet IPs, HCS allocates them randomly.

Do not include `spec.controlPlaneEndpoint` in the create manifest. In the HCS create flow, the controller derives and populates this field from `spec.controlPlaneLoadBalancer` after the `HCSCluster` is created. Do not set `controlPlaneEndpoint` manually, and do not add an empty `controlPlaneEndpoint` object. If `controlPlaneEndpoint` is explicitly present in the manifest, it must include both `host` and `port`.

### Configure Cluster

Expand Down
Loading