在 Huawei Cloud Stack 上创建集群

本文档介绍如何在 Huawei Cloud Stack 平台上创建 Kubernetes 集群。任何受支持的 provider 版本都可以通过 Cluster API manifests 使用基于 YAML 的方式创建集群。如果已安装 Fleet Essentials 1.0.2 或更高版本，并且 Alauda Container Platform HCS Infrastructure Provider 版本为 v1.0.3 或更高版本，也可以通过引导式 Web UI 创建集群。

INFO

Web UI 提供引导式工作流和内置校验，而 YAML 则提供更灵活的自动化能力。

前提条件

在创建集群之前，请确保满足以下所有前提条件：

1. 安装所需插件

在的 global 集群上安装以下插件：

Alauda Container Platform Kubeadm Provider
Alauda Container Platform HCS Infrastructure Provider

有关详细安装说明，请参阅安装指南。

2. 准备 HCS 基础设施输入

在编写本文档中的任何 YAML 之前，请先准备所有 HCS 特定输入：

HCS 凭证 Secret 值
provider 可识别的计算值，例如 imageName、flavorName 和 availabilityZone
集群网络清单，包括集群使用的子网和空闲 IP 范围
控制平面 ELB 地址规划，包括 vipAddress、vipSubnetName 以及固定的 L4 和 L7 IP
控制平面和工作节点的静态 IP 池规划

完整清单、来源信息和限制条件请参阅 Huawei Cloud Stack 的基础设施资源。

3. OS Release 注册

此前提条件仅适用于 Web UI 工作流。基于 YAML 的创建会直接设置 OS 镜像及其组件版本，因此不需要此步骤。

Web UI 不会要求你手动输入 OS 镜像及其 Kubernetes 和组件版本。它会从你为每个 Alauda OS 镜像注册一次的 OS-release ConfigMap 中读取这些信息。向导会从 global 集群解析平台 Distribution 版本，找到 supportedACPVersions 包含该 Distribution 的已注册 OS 镜像，并据此派生节点镜像和控制平面组件版本。

如果当前 Distribution 找不到匹配的已注册 OS 镜像，向导会阻止创建并报错，例如：

当前平台 Distribution v4.3.2 没有注册 OS。请先注册 OS-release ConfigMap。

在打开向导之前，请先在 global 集群上注册 OS 镜像：

apiVersion: v1
kind: ConfigMap
metadata:
  # Any DNS-1123 name. The name is not a lookup key.
  # Do not copy the image version verbatim: it contains "_" (for example, x86_64), which is invalid in a ConfigMap name.
  name: alaudaos-43-m55-x86-64
  namespace: cpaas-system
  labels:
    cpaas.io/os-release: ""
data:
  osImageVersion: "alaudaos-43.m55.202606251459-0.x86_64"
  supportedACPVersions: "v4.3.2"
  osVariant: "m55"
  architecture: "x86_64"
  osBuild: "202606251459-0"
  kubernetesVersion: "v1.34.5-3"
  containerdVersion: "2.2.1-5"
  coreDNSImageTag: "1.14.2-v4.3.11"
  etcdImageTag: "v3.5.28-260625"
  pauseImageTag: "3.10"

使用 kubectl apply -f os-release.yaml 应用它。

字段来源：

字段	值来源
`cpaas.io/os-release` label	空值的固定标记。向导通过此 label 发现 ConfigMap。
`osImageVersion`	上传到 HCS 平台的 Alauda OS 镜像的准确名称。provider 会用它查找 ECS 镜像，并将其作为节点池默认镜像。对于标准版本，它与 OS 支持矩阵中的镜像名称一致。
`supportedACPVersions`	该 OS 镜像支持的 ACP Distribution 版本，以逗号分隔（例如 `v4.3.2`，或 `v4.3.0,v4.3.1`）。向导会将 `global` 集群的 Distribution 与此列表进行匹配。
`architecture`	`x86_64` 或 `aarch64`。必须与计划使用的节点 flavor 架构一致。
`osVariant`, `osBuild`	仅用于参考说明的描述字段；不用于匹配。
`kubernetesVersion`, `containerdVersion`, `coreDNSImageTag`, `etcdImageTag`, `pauseImageTag`	此 OS 镜像的组件版本，取自 OS 支持矩阵中匹配行。向导会将这些版本注入新集群的控制平面，因此它们必须存在于你的 air-gap registry 中。

INFO

不要在此 ConfigMap 中添加 Kube-OVN 版本。向导会从 global 集群的 Kube-OVN 配置中读取 Kube-OVN 版本，而不是从 OS 镜像中读取。

osImageVersion 必须指定一个已存在于 HCS 平台上的镜像。若要读取已有集群环境中使用的准确名称，请列出现有 machine template：

kubectl -n cpaas-system get hcsmachinetemplate \
  -o custom-columns=NAME:.metadata.name,IMAGE:.spec.template.spec.imageName

使用 Web UI

版本要求：此工作流需要 Fleet Essentials 1.0.2 或更高版本，以及 Alauda Container Platform HCS Infrastructure Provider v1.0.3 或更高版本。如果 provider 版本早于 v1.0.3，请使用使用 YAML 中描述的 YAML manifests 创建集群。

Web UI 会使用你选择的 Infrastructure Credential，从 HCS 平台加载 VPC、子网、安全组、flavor 以及可分配 IP 地址。开始前请确保已满足上述前提条件，并且在 cpaas-system 命名空间中已存在 HCS 凭证 Secret。

创建工作流

集群创建流程遵循一个 6 步向导：

Step 1: Basic Info
  ↓
Step 2: Networking
  ↓
Step 3: Infrastructure
  ↓
Step 4: Control Plane Node Pool
  ↓
Step 5: Worker Node Pools
  ↓
Step 6: Review

导航路径：Clusters → Clusters → Create Cluster → Select Huawei Cloud Stack

INFO

IP 选择方式

此向导中的每个 IP 字段——第 3 步中的控制平面 ELB 地址，以及第 4 步和第 5 步中的节点 IP 地址——都是选择器，而不是自由文本框。请先选择子网，选择器只会列出该子网中可分配的 IP 地址。HCS 集群使用静态 IP 地址，因此必须从列表中选择地址；不支持手动输入和 DHCP。更改子网会清除你已选择的地址。同一子网中已在其他位置选中的 IP 地址会从列表中移除，因此同一地址不会被分配两次。当某个子网有很多空闲地址时，列表只显示第一批；你可以输入内容来筛选特定地址。

第 1 步：基本信息

字段	类型	必需	描述
Infrastructure Credential	dropdown	是	现有的 HCS 凭证 Secret。用于加载 VPC、子网、安全组、flavor 和可分配 IP 地址。如果下拉列表为空，请在 `cpaas-system` 命名空间中创建一个带有 `capi.cpaas.io/provider=cluster-api-provider-hcs` label 的 Secret。
Name	text	是	唯一的集群标识符（小写字母、数字和连字符），最长 63 个字符。不能为 `global`。
Display Name	text	否	便于识别的自定义描述，最长 256 个字符。
Distribution Version	readonly	-	平台 Distribution 版本，继承自 `global` 集群。
Kubernetes Version	readonly	-	由 Distribution Version 决定。
OS Version	readonly	-	根据与 Distribution Version 匹配的已注册 OS-release ConfigMap 派生出的 Alauda OS 镜像版本。

第 2 步：网络

字段	类型	必需	描述
Kube-OVN Version	readonly	-	从 `global` 集群检测。
Pod CIDR	CIDR	是	Pod 网络地址范围。
Service CIDR	CIDR	是	Service 网络地址范围。不得与 Pod CIDR 重叠。
Join CIDR	CIDR	是	Kube-OVN join 网络地址范围。

第 3 步：基础设施

此步骤分为两部分：HCS 基础设施资源和控制平面负载均衡器。

基础设施资源：

字段	类型	必需	描述
VPC Name	dropdown	是	从所选凭证加载的现有 VPC。
Security Group Name	dropdown	是	现有安全组。
Subnets	dropdown list	是	一个或多个现有子网。负载均衡器或节点池引用到的每个子网都必须在此处添加。

控制平面负载均衡器：HCS provider 会为 Kubernetes API server 创建一个 Elastic Load Balance (ELB)，并拥有其 VIP。Hybrid Load Balancing 需要固定的 L4 和 L7 虚拟子网 IP。

字段	类型	必需	描述
VIP Subnet Name	dropdown	是	承载 ELB VIP 的子网。必须是上面添加的子网之一。
VIP Address	IP picker	是	控制平面 ELB 的固定 VIP。
VIP Domain Name	text	否	VIP 的可选域名。如果设置，请配置 HCS Cloud DNS Private Zones，使该域名解析到该 VIP；集群不会创建此记录。
L4 Virtual Subnet Name	dropdown	是	L4 Hybrid Load Balancing IP 所在的子网。
L4 Virtual Subnet IP 1 / IP 2	IP picker	是	两个固定的 L4 IP 地址。
L7 Virtual Subnet Name	dropdown	是	L7 Hybrid Load Balancing IP 所在的子网。
L7 Virtual Subnet IP 1 / IP 2	IP picker	是	两个固定的 L7 IP 地址。

第 4 步：控制平面节点池

为保证高可用，控制平面节点池固定为 3 个副本。

字段	类型	必需	描述
Control Plane Node Pool Name	text	是	节点池名称，自动添加 `<cluster-name>-` 前缀。
Flavor	dropdown	是	HCS flavor；列表会显示每个选项的 vCPU 和内存。
Availability Zone	dropdown	否	目标可用区。无容量的可用区会被禁用。
Machine Configs	list	是	每个控制平面节点一条配置。至少需要 3 条。参见下方的 Machine Config 条目。
System Disk	number	是	根磁盘大小，单位 GB；类型固定为 SSD。
Data Volumes	list	否	挂载到该池中每个节点上的固定数据盘；只有大小可调整。控制平面包含 etcd 数据卷。
Replicas	readonly	-	固定为 3。
Control Plane High Availability	toggle	否	默认开启。使用由 provider 管理的 HCS server group，将控制平面节点分散到不同物理主机上。
Placement Policy	radio	Conditional	在启用 High Availability 时显示。Preferred (soft anti-affinity)（默认）按最佳努力方式分散节点。Required (strict anti-affinity) 强制每个节点落到不同主机上；如果主机数量不足则创建失败。
SSH Authorized Keys	list	否	用于节点访问的公钥。

Machine Config 条目

Machine Configs 中的每一条配置描述一个节点：

Hostname（必需）：小写字母、数字、连字符和点，最长 253 个字符（例如 master-1 或 master-1.example.org）。关于带点的 hostname 如何影响节点，请参阅节点上的 hostname 行为。
Networks（必需）：每个 NIC 一行。每行包含一个 IP Address 选择器和一个 Subnet Name。多 NIC 节点请添加多行。
Persistent Disks：平台要求的 /var/cpaas 磁盘已预填；其大小可调整，但该行不能删除。仅在需要额外的、必须在节点重建后仍保留的宿主机绑定数据时添加条目。

第 5 步：工作节点池

点击 Add Worker Node Pool 打开节点池对话框。你可以添加多个节点池。

字段	类型	必需	描述
Worker Node Pool Name	text	是	节点池名称，自动添加 `<cluster-name>-` 前缀。必须在集群内唯一。
Flavor	dropdown	是	HCS flavor；列表会显示每个选项的 vCPU 和内存。
Availability Zone	dropdown	否	目标可用区。
Machine Configs	list	是	每个工作节点一条配置。布局与控制平面的 Machine Config 条目相同。
System Disk	number	是	根磁盘大小，单位 GB；类型固定为 SSD。
Data Volumes	list	否	挂载到该池中每个节点上的固定数据盘。
Replicas	number	是	节点池中的节点数量。不得超过 machine configs 的数量。
Rollout Strategy	number	否	Max Surge 和 Max Unavailable。当 Max Surge 为 `0` 时，Max Unavailable 必须大于等于 `1` 且小于等于 Replicas。
SSH Authorized Keys	list	否	用于节点访问的公钥。

第 6 步：审查

检查 Basic Info、Infrastructure、Control Plane Load Balancer、Control Plane Node Pool、Worker Node Pools 和 Networking 各部分。点击 View YAML 查看将要创建的确切资源。点击 Create 开始创建集群。

使用 YAML

集群创建概览

从高层次来看，你需要在的 global 集群中创建以下 Cluster API resources，以便配置基础设施并引导出一个可运行的 Kubernetes 集群。

在编写本页中的任何 YAML 之前，请先完成 Huawei Cloud Stack 的基础设施资源中的准备清单。该清单涵盖了 provider 预期的值、这些值的获取方式，以及在填写 manifests 之前必须提前规划的值。

WARNING

重要的命名空间要求

为确保与以业务集群方式正确集成，所有资源都必须部署在 cpaas-system 命名空间中。将资源部署到其他命名空间可能会导致集成问题。

WARNING

工作负载集群命名

工作负载 cluster-name 不能为 global。该名称保留给 global 集群，重复使用会导致工作负载集群的资源与 cpaas-system 中的 global 集群资源冲突。global- 前缀保留给 global 集群的 DR 工作流所拥有的资源；请参阅常见前提条件。不要将 global- 用于工作负载集群资源，因为故障切换操作可能会将这些资源当作属于 global 集群来选择。

作为约定，请将 CAPI Cluster 和 provider cluster resource（HCSCluster）名称保持为精确的 <cluster-name>，并将非根 CAPI 和 provider 资源（KubeadmControlPlane、KubeadmConfigTemplate、MachineDeployment、machine templates、machine config pools 等）以前缀 <cluster-name>- 命名——例如，示例 manifests 使用 <cluster-name>-kcp。这是一项建议，而不是 controller 强制的规则，但它可以避免多个工作负载集群共存于 cpaas-system 时发生同名冲突，并使运维过程中资源归属更加清晰。

集群创建过程按以下顺序进行：

配置 HCS 身份认证（Secret）
创建 machine configuration pool（HCSMachineConfigPool）
配置 machine template（HCSMachineTemplate）
配置 KubeadmControlPlane
配置 HCSCluster
创建 Cluster

控制平面配置

控制平面负责管理集群状态、调度以及 Kubernetes API。此部分说明如何配置高可用控制平面。

WARNING

配置参数指南

在配置资源时，请谨慎修改参数：

仅替换用 <> 包裹的值为你的环境特定值
保留所有其他参数，因为它们表示经过优化或必需的配置
修改非占位符参数可能导致集群不稳定或集成问题

配置 HCS 身份认证

HCS 身份认证信息存储在 Secret 资源中。

apiVersion: v1
kind: Secret
metadata:
  name: <credential-secret-name>
  namespace: cpaas-system
type: Opaque
data:
  accessKey: <base64-encoded-access-key>
  secretKey: <base64-encoded-secret-key>
  projectID: <base64-encoded-project-id>
  region: <base64-encoded-region>
  externalGlobalDomain: <base64-encoded-domain>
  schema: <base64-encoded-schema>

参数	描述
`.data.accessKey`	来自 My Settings > Access Keys 的 HCS access key ID（base64 编码）
`.data.secretKey`	来自 My Settings > Access Keys 的 HCS secret access key（base64 编码）
`.data.projectID`	来自 My Settings > Resource Spaces 的 Resource Space ID（base64 编码）
`.data.region`	provider 使用的 HCS region API 值（base64 编码）。租户管理员无法从 HCS UI 中获取该值；请从 HCS 管理员处获取
`.data.externalGlobalDomain`	provider 使用的 HCS 平台访问域名（base64 编码）
`.data.schema`	HCS IAM endpoint 的可选 API scheme，通常为 `https`（base64 编码）。如果省略，provider 将使用 `https`

现有的、未设置 schema 的凭证 Secret 仍可正常使用。只有当你的 HCS IAM endpoint 使用 http 而不是默认的 https 时，才需要设置 schema。

你可以复用现有的 HCS 凭证 Secret。其名称不必与集群名称一致，但 HCSCluster.spec.identityRef.name 必须引用该 Secret。

配置 Machine Configuration Pool

HCSMachineConfigPool 定义了预配置的 hostname、静态 IP 地址，以及适用于 VM 的、由节点池管理的持久化磁盘。

WARNING

节点池大小要求

配置池必须至少包含你计划部署的控制平面节点数量相同的条目数。

每个 networks[] 条目使用一个 subnet selector。对于新 manifests，请设置 subnetName 或 subnetId 其中之一，但不要同时设置两者。现有 manifests 可以保留已废弃的 subenetName 字段；如果你在更新该 manifest 时还添加了 subnetName，其值必须与 subenetName 完全一致。不要在 subenetName、subnetName 和 subnetId 之间提供冲突值。

如果你在 machine configuration pool 中使用 subnetName，请在 HCSCluster.spec.network.subnets 中包含相同的子网名称。

对于初始集群创建流程，仅按名称列出现有子网即可，因为 controller 会在集群变为 Ready 之前解析子网元数据。如果你之后要向一个已存在且处于 Ready 状态的 HCSCluster 添加另一个子网，不要只追加 name。请将完整的子网对象 patch 到父级 HCSCluster.spec.network.subnets 条目中，以便后续的 machine 或 ELB 操作可以复用已解析的子网元数据。

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: HCSMachineConfigPool
metadata:
  name: <cluster-name>-cp-pool
  namespace: cpaas-system
  labels:
    cluster.x-k8s.io/cluster-name: <cluster-name>
spec:
  configs:
    - hostname: master-1
      networks:
        - subnetName: <subnet-name>
          ipAddress: 192.168.1.11
      persistentDisks:
        - slot: 0
          size: 100
          type: SSD
          mountPath: /var/cpaas
          format: xfs
    - hostname: master-2
      networks:
        - subnetName: <subnet-name>
          ipAddress: 192.168.1.12
      persistentDisks:
        - slot: 0
          size: 100
          type: SSD
          mountPath: /var/cpaas
          format: xfs
    - hostname: master-3
      networks:
        - subnetName: <subnet-name>
          ipAddress: 192.168.1.13
      persistentDisks:
        - slot: 0
          size: 100
          type: SSD
          mountPath: /var/cpaas
          format: xfs

参数	类型	必需	描述
`.spec.configs[]`	array	是	非空的 machine 配置列表
`.spec.configs[].hostname`	string	是	VM hostname。可使用小写字母、数字、连字符（`-`）或点（`.`）；值必须以小写字母或数字开头和结尾，且不能超过 253 个字符（遵循 RFC 1035 中 DNS 名称长度限制）。前导或尾随点、全由点组成的字符串以及大写字母都会被拒绝，controller 会在所属 `Machine` 和 `Cluster` 状态中暴露该错误。有关当该值包含点时 `hostname` 和 `hostname -f` 的返回结果，请参见下面的节点上的 hostname 行为小节。
`.spec.configs[].networks[]`	array	是	VM 的非空网络配置列表
`.spec.configs[].networks[].subnetName`	string	否*	新 manifests 推荐使用的 subnet 名称字段
`.spec.configs[].networks[].subnetId`	string	否*	子网 ID。当子网名称有歧义时，请使用此字段代替 `subnetName`
`.spec.configs[].networks[].ipAddress`	string	是	VM 的静态 IP 地址
`.spec.configs[].persistentDisks[]`	array	否	在 HCSMachine 删除后重新创建替换过程中仍可保留的 EVS 磁盘
`.spec.configs[].persistentDisks[].slot`	int	是*	单个 machine 配置内的磁盘槽位。同一 hostname 下，槽位必须唯一且从 `0` 开始连续
`.spec.configs[].persistentDisks[].size`	int	是*	EVS 磁盘大小，单位 GB。对于新创建的 EVS 数据盘，请使用 `10` 到 `32768` GB。已有的已声明磁盘必须与其当前大小一致
`.spec.configs[].persistentDisks[].type`	string	是*	目标可用区中可用的 EVS 磁盘类型名称
`.spec.configs[].persistentDisks[].mountPath`	string	否	Guest 挂载路径。对于必须在 VM 替换后仍然存在的平台状态，请使用 `/var/cpaas`
`.spec.configs[].persistentDisks[].format`	string	否	文件系统格式。如果省略，provider 将使用 `xfs`
`.spec.configs[].persistentDisks[].mountOptions`	array	否	挂载选项。如果省略，provider 将使用 `defaults,noatime`

*对于新 manifests，请设置 subnetName 或 subnetId 其中之一。现有 manifests 可以继续使用 subenetName，并且只有在两个字段值相同的情况下才可以添加 subnetName。不要提供冲突的 subnet selector 值。

如果指定了 persistentDisks，则持久化磁盘字段为必需。

对于必须在 VM 替换后仍保留的节点本地状态，请使用 persistentDisks[]。不要在 HCSMachineTemplate.spec.template.spec.dataVolumes[] 中声明相同的挂载路径。

注意： CRD schema 将 subnetName、subenetName 和 subnetId 列为可选字段，但未表达它们允许的组合关系。编写 manifests 时，请遵循上述 provider 级规则。

注意： 若要为单个节点挂载多个 NIC，请添加多个 networks[] 条目。provider 仅使用这些条目来挂载 NIC，并分配 subnet selectors 和静态 IP。它不支持声明每个 NIC 的角色、默认网关、静态路由或每个 NIC 的 DNS 设置。

节点上的 hostname 行为

provider 会按如下方式从 hostname 派生节点的 POSIX hostname 和 FQDN：

节点池 `hostname` 值	节点 `hostname`	节点 `hostname -f`	写入的 `/etc/hosts` 条目
`master-1`（无点）	`master-1`	`master-1`（resolver 返回短名称）	provider 不添加
`master-1.example.org`（带点）	`master-1`（短标签，点及其后内容会被截断）	`master-1.example.org`	`<node-ip> master-1.example.org master-1`

带点格式适用于需要依赖 FQDN 解析的应用（hostname -f、带 SAN 条目的证书、日志标签）。当提供带点的 hostname 时，provider 会设置 prefer_fqdn_over_hostname: false 并启用 cloud-init manage_etc_hosts，因此 POSIX 工具仍然看到短名称，而 hostname -f 返回完整 FQDN。

无效 hostname（前导点、尾随点、全由点组成的字符串、大写字母，或任何违反字段约束的内容）会在 VM 启动前被拒绝。错误会设置在所属的 Machine.status 上，并在 Cluster.status.conditions 中显现，因此你可以通过 kubectl describe cluster <name> 和 kubectl get machines -n cpaas-system -o wide 查看。

配置 Machine Template

HCSMachineTemplate 定义了控制平面节点的 VM 规格。

WARNING

存储要求

建议控制平面节点使用以下数据盘挂载点：

/var/lib/etcd - etcd 数据（10GB+）
/var/lib/kubelet - kubelet 数据（100GB+）
/var/lib/containerd - container runtime 数据（100GB+）

/var/cpaas 路径用于存储平台状态和日志。当它必须在 VM 替换后仍然保留时，请将其声明在 HCSMachineConfigPool.spec.configs[].persistentDisks[] 中。

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: HCSMachineTemplate
metadata:
  name: <cluster-name>-control-plane
  namespace: cpaas-system
spec:
  template:
    spec:
      imageName: <vm-image-name>
      flavorName: <instance-flavor>
      availabilityZone: <availability-zone>
      rootVolume:
        type: SSD
        size: 100
      configPoolRef:
        name: <cluster-name>-cp-pool
      dataVolumes:
        - size: 10
          type: SSD
          mountPath: /var/lib/etcd
          format: xfs
        - size: 100
          type: SSD
          mountPath: /var/lib/kubelet
          format: xfs
        - size: 100
          type: SSD
          mountPath: /var/lib/containerd
          format: xfs

参数	类型	必需	描述
`.spec.template.spec.imageName`	string	是	HCS 镜像名称。使用当前版本 OS support matrix 中发布的镜像标识；上面的 manifest 中将占位符显示为 `<alaudaos-version>`。准确名称会随每个 Alauda OS 版本变化，因此不要在不同版本之间硬编码示例值。
`.spec.template.spec.flavorName`	string	是	provider 可识别的 HCS API 值，需与 `Flavor.Name` 匹配。不要使用租户 UI 的显示名称
`.spec.template.spec.availabilityZone`	string	否	provider 可识别的 HCS API 值，需与 `ZoneName` 匹配。不要使用租户 UI 的显示名称
`.spec.template.spec.rootVolume.type`	string	是	卷类型（`SSD` 或 `SATA`）
`.spec.template.spec.rootVolume.size`	int	是	系统盘大小，单位 GB
`.spec.template.spec.configPoolRef.name`	string	是	被引用的 HCSMachineConfigPool 名称
`.spec.template.spec.dataVolumes[]`	array	否	数据卷配置
`.spec.template.spec.dataVolumes[].size`	int	是*	数据盘大小，单位 GB
`.spec.template.spec.dataVolumes[].type`	string	是*	卷类型
`.spec.template.spec.dataVolumes[].mountPath`	string	是*	挂载路径
`.spec.template.spec.dataVolumes[].format`	string	是*	文件系统格式（`xfs` 或 `ext4`）

*在指定 dataVolumes 时必需。

dataVolumes[] 会随 ECS 一起重新创建。不要将其用于 /var/cpaas 或任何其他必须在滚动替换后仍然保留的路径。请将这些路径放入 HCSMachineConfigPool.spec.configs[].persistentDisks[]。

注意： 不要在 HCSMachineTemplate manifests 中设置诸如 providerID 或 serverId 之类的运行时身份字段。provider 会在创建 HCS 实例时分配这些值。

注意： 租户管理员无法从 HCS UI 中获取 provider 可识别的 flavorName 和 availabilityZone 值。在应用 manifest 之前，请先从 HCS 管理员处获取准确值。

配置 KubeadmControlPlane

KubeadmControlPlane 定义了 Kubernetes 控制平面配置。

Kubernetes 1.35 kubelet 设置

imagePullCredentialsVerificationPolicy: NeverVerify 仅从 Kubernetes 1.35 开始必需。使用 Kubernetes 1.34 或更早版本创建集群时，请省略此参数。

apiVersion: controlplane.cluster.x-k8s.io/v1beta1
kind: KubeadmControlPlane
metadata:
  name: <cluster-name>-kcp
  namespace: cpaas-system
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",
            "imagePullCredentialsVerificationPolicy": "NeverVerify",
            "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"
          volume-plugin-dir: "/opt/libexec/kubernetes/kubelet-plugins/volume/exec/"
  machineTemplate:
    nodeDrainTimeout: 1m
    nodeDeletionTimeout: 5m
    infrastructureRef:
      apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
      kind: HCSMachineTemplate
      name: <cluster-name>-control-plane

HCS controller 在解析 cloud-init 数据时还会注入文件。它会为控制平面机器写入 /etc/kubernetes/pki/kubelet.crt、/etc/kubernetes/pki/kubelet.key 和 /etc/kubernetes/encryption-provider.conf。对于第一台控制平面机器，controller 会生成 encryption provider 配置。在控制平面初始化之后，它会尝试复用现有的 kube-apiserver encryption provider 配置。如果你在 /etc/kubernetes/encryption-provider.conf 中包含了一个 bootstrap 文件，请将其视为占位符，因为 controller 生成或同步的文件具有更高优先级。

注意： 请同时配置 apiServer.extraArgs 和 apiServer.extraVolumes。如果该 volume 未挂载，kube-apiserver 将无法读取 /etc/kubernetes 下写入的文件。

注意： 上面的 rolloutStrategy.rollingUpdate.maxSurge: 0 示例适用于具有静态 IP 的高可用控制平面。对于至少有三个副本的固定规模控制平面池，请保留此设置，以便替换过程按先缩容再扩容的顺序进行。如果你创建的是单控制平面 HCS 集群（spec.replicas: 1），请不要把 rolloutStrategy 块复制到创建 manifest 中。KubeadmControlPlane 的校验会拒绝单副本场景下这种缩容式 rollout 配置。

注意： HCS 还支持通过设置 spec.replicas: 1 并在引用的 HCSMachineConfigPool 中准备一条控制平面配置来创建单控制平面集群。请将其视为仅用于创建的拓扑，并在该创建 manifest 中保持 rollout strategy 未设置。本文档中的升级流程不支持单控制平面 HCS 集群。

仅将 OS 支持矩阵用于其明确列出的组件版本，例如受支持 Alauda OS 镜像的 coredns 和 etcd image tags。它并不是所有 HCS manifest 值的完整来源。在应用此 YAML 之前，还需要使用批准的 release baseline 获取诸如 imageRepository、DNS image repository、Kube-OVN version、Kube-OVN join CIDR、Pod CIDR 和 Service CIDR 等值。

配置 HCSCluster

HCSCluster resource 定义 HCS 基础设施配置。

HCS provider 会在 HCS 平台上为 Kubernetes API server 创建一个 Elastic Load Balance (ELB)。该 ELB 必须保持启用 Hybrid Load Balancing，这样集群节点才能通过 ELB 地址访问 API server。

对于本文档中的 HCS 工作流，请提供 vipAddress、elbVirsubnetL4Ips 和 elbVirsubnetL7Ips。每个 elbVirsubnetL4Ips[].ips 和 elbVirsubnetL7Ips[].ips 条目都必须包含两个 IP。

如果设置了 vipDomainName，请配置 HCS Cloud DNS Private Zones，使该域名解析到 vipAddress。

在任何地方引用子网之前，请先在 spec.network.subnets 中列出集群使用的每个子网。vipSubnetName、elbVirsubnetL4Ips[].subnetName、elbVirsubnetL7Ips[].subnetName 以及 HCSMachineConfigPool 中使用的 subnetName 值都必须存在于 spec.network.subnets 中。

对于初始集群创建流程，controller 可以从 name 解析现有子网元数据。对于已有的 Ready 集群，请追加完整的子网对象，而不是只追加 name。同时包含 id，并为控制平面 ELB 将使用的任何子网包含 neutronSubnetId。子网清单中还应保留 cidr、gatewayIp、primaryDNS 和 secondaryDNS。

在集群创建完成后，不要禁用 provider 创建的 ELB 上的 Hybrid Load Balancing。集群依赖该 ELB 模式，以便节点能够通过 ELB 地址访问 API server。

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: HCSCluster
metadata:
  name: <cluster-name>
  namespace: cpaas-system
spec:
  # Optional. Include only when you want provider-managed control-plane ECS placement.
  controlPlaneHA:
    enabled: true
    policy: soft-anti-affinity
  controlPlaneLoadBalancer:
    vipAddress: <control-plane-vip-address>
    vipSubnetName: <vip-subnet-name>
    vipDomainName: <control-plane-vip-domain-name>
    elbVirsubnetL4Ips:
      - subnetName: <subnet-name>
        ips:
          - <l4-ip-1>
          - <l4-ip-2>
    elbVirsubnetL7Ips:
      - subnetName: <subnet-name>
        ips:
          - <l7-ip-1>
          - <l7-ip-2>
  networkType: kube-ovn
  network:
    vpc:
      name: <vpc-name>
    subnets:
      - name: <subnet-name>
    securityGroup:
      name: <security-group-name>
  identityRef:
    name: <credential-secret-name>

参数	类型	必需	描述
`.spec.networkType`	string	是	网络类型，目前支持 `kube-ovn`
`.spec.network.vpc.name`	string	是	VPC 名称
`.spec.network.subnets[].name`	string	是	集群子网清单中的子网名称。集群 manifests 中其他位置引用到的每个子网都必须出现在此列表中
`.spec.network.subnets[].id`	string	推荐	子网 ID。对于已有的 Ready 集群，在后续追加子网时请包含此值，以便 machine 创建可以安全复用子网清单
`.spec.network.subnets[].neutronSubnetId`	string	对 ELB 子网推荐	Neutron subnet ID。对于控制平面 ELB 使用的任何子网都应包含此值
`.spec.network.subnets[].cidr`	string	推荐	保存在集群子网清单中的子网 CIDR
`.spec.network.subnets[].gatewayIp`	string	推荐	保存在集群子网清单中的子网网关
`.spec.network.subnets[].primaryDNS`	string	推荐	保存在集群子网清单中的主 DNS
`.spec.network.subnets[].secondaryDNS`	string	推荐	保存在集群子网清单中的备用 DNS
`.spec.network.securityGroup.name`	string	是	安全组名称
`.spec.identityRef.name`	string	是	`HCSCluster` 引用的非空凭证 Secret 名称；该值不必与集群名称一致
`.spec.controlPlaneHA.enabled`	bool	设置了 `controlPlaneHA` 时必需	启用由 provider 管理的 server group，用于控制平面 ECS 放置
`.spec.controlPlaneHA.policy`	string	设置了 `controlPlaneHA` 时必需	server group 放置策略。允许的值为 `anti-affinity` 和 `soft-anti-affinity`
`.spec.controlPlaneLoadBalancer`	object	是	provider 创建的控制平面 ELB 的 ELB 设置
`.spec.controlPlaneLoadBalancer.vipAddress`	string	是	控制平面 ELB 的固定 VIP
`.spec.controlPlaneLoadBalancer.vipSubnetName`	string	是	包含 ELB VIP 的子网名称。该子网也必须出现在 `.spec.network.subnets` 中
`.spec.controlPlaneLoadBalancer.vipDomainName`	string	否	VIP 的域名。请配置 HCS Cloud DNS Private Zones 使其解析到 `vipAddress`
`.spec.controlPlaneLoadBalancer.elbVirsubnetL4Ips[]`	array	是	Hybrid Load Balancing 使用的 L4 虚拟子网 IP 组
`.spec.controlPlaneLoadBalancer.elbVirsubnetL4Ips[].subnetName`	string	是	L4 虚拟子网 IP 的子网名称。该子网也必须出现在 `.spec.network.subnets` 中
`.spec.controlPlaneLoadBalancer.elbVirsubnetL4Ips[].ips[]`	string	是	两个固定的 L4 虚拟子网 IP
`.spec.controlPlaneLoadBalancer.elbVirsubnetL7Ips[]`	array	是	Hybrid Load Balancing 使用的 L7 虚拟子网 IP 组
`.spec.controlPlaneLoadBalancer.elbVirsubnetL7Ips[].subnetName`	string	是	L7 虚拟子网 IP 的子网名称。该子网也必须出现在 `.spec.network.subnets` 中
`.spec.controlPlaneLoadBalancer.elbVirsubnetL7Ips[].ips[]`	string	是	两个固定的 L7 虚拟子网 IP

创建 manifest 中不要包含 spec.controlPlaneEndpoint。在 HCS 创建流程中，controller 会在创建 HCSCluster 后，从 spec.controlPlaneLoadBalancer 派生并填充此字段。不要手动设置 controlPlaneEndpoint，也不要添加空的 controlPlaneEndpoint 对象。如果 manifest 中显式存在 controlPlaneEndpoint，它必须同时包含 host 和 port。

controlPlaneHA 是可选项。包含它时，enabled 和 policy 都是必需的。使用 anti-affinity 实现严格的主机隔离。若你希望节点尽量分散在不同主机上，但又不希望因为 HCS 无法满足硬性放置规则而导致 ECS 创建失败，请使用 soft-anti-affinity。有关规划指导，包括在现有集群上启用该功能时所需的滚动替换要求，请参阅控制平面 HA 放置计划。

配置 Cluster

Cluster API 中的 Cluster resource 用于声明集群，并引用控制平面和基础设施资源。

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: <cluster-name>
  namespace: cpaas-system
  annotations:
    cpaas.io/sentry-deploy-type: Baremetal
    cpaas.io/alb-address-type: ClusterAddress
    capi.cpaas.io/resource-group-version: infrastructure.cluster.x-k8s.io/v1beta1
    capi.cpaas.io/resource-kind: HCSCluster
    cpaas.io/kube-ovn-join-cidr: <kube-ovn-join-cidr>
    cpaas.io/kube-ovn-version: <kube-ovn-version>
  labels:
    cluster-type: HCS
spec:
  clusterNetwork:
    pods:
      cidrBlocks:
        - <pods-cidr>
    services:
      cidrBlocks:
        - <services-cidr>
  controlPlaneRef:
    apiVersion: controlplane.cluster.x-k8s.io/v1beta1
    kind: KubeadmControlPlane
    name: <cluster-name>-kcp
  infrastructureRef:
    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    kind: HCSCluster
    name: <cluster-name>

注解	描述
`cpaas.io/sentry-deploy-type`	部署类型，设置为 `Baremetal`
`cpaas.io/alb-address-type`	ALB 地址类型，设置为 `ClusterAddress`
`capi.cpaas.io/resource-group-version`	资源组版本
`capi.cpaas.io/resource-kind`	资源类型，设置为 `HCSCluster`
`cpaas.io/kube-ovn-join-cidr`	Kube-OVN join 子网 CIDR
`cpaas.io/kube-ovn-version`	Kube-OVN 版本

集群验证

部署完所有集群资源后，请验证集群是否已成功创建。

使用 kubectl

# Check cluster status
kubectl get cluster -n cpaas-system <cluster-name>

# Verify control plane nodes
kubectl get kubeadmcontrolplane -n cpaas-system <cluster-name>-kcp

# Check machine status
kubectl get machines -n cpaas-system

# Verify cluster deployment status
kubectl get clustermodule <cluster-name> -o jsonpath='{.status.base.deployStatus}'

验证控制平面 HA

如果你启用了 HCSCluster.spec.controlPlaneHA，请先检查 HCSCluster condition：

kubectl get hcscluster <cluster-name> -n cpaas-system \
  -o jsonpath='{range .status.conditions[?(@.type=="ControlPlaneHAReady")]}{.status}{" "}{.reason}{" "}{.message}{"\n"}{end}'

按如下方式解释该 condition：

状态和原因	含义	下一步
`True ControlPlaneHAReady`	provider 管理的 server group 已存在，当前控制平面 ECS 成员已被跟踪。	无需操作。
`False ControlPlaneHAPending`	provider 正在等待可恢复状态，例如 ECS 创建中或 server group 成员收敛中。	阅读消息并等待引用的控制平面 machine 或 ECS 操作完成。
`False ControlPlaneHAFailed`	provider 无法创建、验证、更新或清理 server group，或者 HCS 拒绝了所选策略下的 ECS 调度。	阅读消息，然后根据需要检查 HCS 容量、所选策略以及 controller 日志。

检查观察到的 server group 和成员快照：

kubectl get hcscluster <cluster-name> -n cpaas-system \
  -o jsonpath='serverGroup={.status.controlPlaneHA.name}{" id="}{.status.controlPlaneHA.id}{" policy="}{.status.controlPlaneHA.policy}{"\n"}{range .status.controlPlaneHA.members[*]}{.machineName}{" "}{.serverID}{"\n"}{end}'

对于 anti-affinity，HCS 会将 server group 策略视为硬性调度约束。如果容量不足，ECS 创建可能失败，此时应首先根据 condition 消息进行排查。对于 soft-anti-affinity，HCS 会尽量分散成员，但仍可能将多个 ECS 实例放置在同一主机上。

预期结果

成功创建的集群应显示：

集群状态：Running 或 Provisioned
所有控制平面机器：Running
Kubernetes nodes：Ready
Cluster Module Status：Completed

添加工作节点

有关向集群添加工作节点的说明，请参阅管理节点。

升级集群

有关升级集群组件的说明，请参阅升级集群。

故障排查

如果集群已达到 Provisioned 但始终未变为 Ready——例如，由于 CNI 未部署导致工作负载节点一直处于 NotReady——请先参考与 provider 无关的排查工作负载集群卡在 Provisioned 状态。

对于 HCS 特有的失败模式（例如，由于带点的 HCSMachineConfigPool hostname 生成了包含点的 POSIX hostname，导致 kubeadm init 一直无法完成），请参阅排查 Huawei Cloud Stack 工作负载集群故障。

#在 Huawei Cloud Stack 上创建集群

#目录

#前提条件

#1. 安装所需插件

#2. 准备 HCS 基础设施输入

#3. OS Release 注册

#使用 Web UI

#创建工作流

#第 1 步：基本信息

#第 2 步：网络

#第 3 步：基础设施

#第 4 步：控制平面节点池

#Machine Config 条目

#第 5 步：工作节点池

#第 6 步：审查

#使用 YAML

#集群创建概览

#控制平面配置

#配置 HCS 身份认证

#配置 Machine Configuration Pool

#节点上的 hostname 行为

#配置 Machine Template

#配置 KubeadmControlPlane

#配置 HCSCluster

#配置 Cluster

#集群验证

#使用 kubectl

#验证控制平面 HA

#预期结果

#添加工作节点

#升级集群

#故障排查

在 Huawei Cloud Stack 上创建集群

目录

前提条件

1. 安装所需插件

2. 准备 HCS 基础设施输入

3. OS Release 注册

使用 Web UI

创建工作流

第 1 步：基本信息

第 2 步：网络

第 3 步：基础设施

第 4 步：控制平面节点池

Machine Config 条目

第 5 步：工作节点池

第 6 步：审查

使用 YAML

集群创建概览

控制平面配置

配置 HCS 身份认证

配置 Machine Configuration Pool

节点上的 hostname 行为

配置 Machine Template

配置 KubeadmControlPlane

配置 HCSCluster

配置 Cluster

集群验证

使用 kubectl

验证控制平面 HA

预期结果

添加工作节点

升级集群

故障排查