Immutable Infrastructure
  • 简体中文

    • 安装 global 集群

    本文档介绍如何将 global 集群安装到 Immutable Infrastructure 上。global 集群是平台控制平面，并通过 Cluster API 进行部署。当平台控制平面必须运行在不可变操作系统（例如 Alauda OS）上时，请使用此路径。

    目录

    何时使用此路径通用前提条件兼容性与版本输入操作步骤第 1 步 — 准备通用变量第 2 步 — 引导 KIND 主机第 3 步 — 上传并安装 Provider 包第 4 步 — 配置 provider 特定的 global Manifest第 5 步 — 应用 global Manifest第 6 步 — 等待控制平面第 7 步 — 导入 Provider 资源第 8 步 — 触发平台安装第 9 步 — 监控安装过程你将观察到的阶段安装期间的信号常见卡住情况及排查位置可选的灾难恢复部署准备共享 DR 变量为 KubeadmControlPlane 添加 DR 证书 SAN添加 provider 特定的 DR 字段安装主集群和待机集群验证后续步骤

    何时使用此路径

    当满足以下所有条件时，选择此安装路径：

    • 希望 global 集群运行在不可变操作系统上。当前支持的镜像是 Alauda OS。
    • 你的基础设施属于本文档所支持的提供商之一：Huawei DCS、VMware vSphere 或 Huawei Cloud Stack。global 集群的裸金属支持计划中。
    • 你可以运行一个临时的 KIND 主机，并且该主机可以访问目标 IaaS 平台的网络。

    对于 Ubuntu 或 RHEL 等传统操作系统，请改用 标准安装路径。

    通用前提条件

    以下前提条件适用于所有提供商：

    • 一个满足最低硬件和网络要求的 KIND 主机。有关规格建议，请参见 概述。
    • 来自 Customer Portal 的 Core Package。
    • Alauda Container Platform Kubeadm Provider 包。
    • 目标平台对应的基础设施提供商包。
    • KIND 主机与目标 IaaS 平台 API 端点之间的网络可达性。
    • global 控制平面和 worker 节点的 IP 与主机名规划。请参见 基础设施资源，了解各提供商使用的资源模型。
    • global 集群的稳定 Kubernetes API 端点，例如 VIP 或负载均衡器地址。
    • 平台访问地址、registry 地址，以及 Pod 和 Service CIDR 范围。
    • 对于使用 ACP 提供的 Alauda OS 镜像的 x86_64 节点，底层 CPU 必须支持 x86-64-v2 ISA 基线。请参见 OS 支持矩阵。
    命名规范（必需）

    此规则适用于此安装路径支持的所有基础设施提供商——Huawei DCS、Huawei Cloud Stack、VMware vSphere，以及未来添加的任何提供商。你在第 4 步中编写的每个 manifest 都必须遵守该规则。资源命名错误有两种不同的失败模式，下面分别说明；一种会破坏初始部署，另一种只会在灾难恢复期间暴露。

    • CAPI Cluster 以及提供商的基础设施集群资源（例如 Huawei DCS 的 DCSCluster，或 Huawei Cloud Stack 的 HCSCluster；每个提供商都有各自对应的资源）必须精确命名为 global。cpaas-installer 会按字面名称进行查找，而且只有当基础设施集群命名为 global 时，Huawei Cloud Stack 提供商才会分配 global ELB 监听端口（注册表和控制台使用 11443，DR etcd-sync 使用 2379，Web 访问使用 443）。使用其他名称会静默破坏 registry 拉取、DR etcd-sync 和 Web 控制台。
    • 其他所有 CAPI 资源（KubeadmControlPlane、KubeadmConfigTemplate、MachineDeployment）以及其他所有提供商基础设施资源（机器模板、IP/主机名池、机器配置池，以及任何其他按提供商区分的资源）必须使用带有 global- 前缀的名称。DR（故障切换）机制会使用该前缀来识别属于 global 集群的资源。没有 global- 前缀的 global 集群资源对 DR 不可见，并会在故障切换时导致待机集群的机器被删除——集群会正常部署并运行，但在首次执行 DR 时会丢失节点。这是硬性要求，不是风格约定。
    • Cluster.spec.controlPlaneRef.name 以及任何其他交叉引用都必须与带前缀的名称完全一致。

    兼容性与版本输入

    在安装前，请记录交付包支持的版本集：

    输入目的
    Core Package 版本提供安装器、本地 registry 和基础平台负载。
    Kubeadm provider chart 版本必须与 global manifest 使用的 Cluster API 控制平面资源匹配。
    基础设施提供商 chart 版本使用随目标版本交付的 VMware vSphere、DCS 或 HCS provider chart 版本。
    Alauda OS 镜像或 VM 模板必须包含 K8S_VERSION 使用的 Kubernetes 版本。
    K8S_VERSION使用带 v 前缀的 semver，并与目标 Alauda OS 镜像匹配，例如 v<major>.<minor>.<patch>。

    操作步骤

    第 1 步 — 准备通用变量

    在 KIND 主机上设置通用变量。

    export HOST_IP="<kind-host-ip>"
export LOCAL_REGISTRY_ADDRESS="127.0.0.1:11443"
export BOOTSTRAP_REGISTRY_ADDRESS="172.18.0.1:11443"
export NODE_REGISTRY_ADDRESS="${HOST_IP}:11443"
export CONTROL_PLANE_VIP="<global-control-plane-vip>"
export PLATFORM_HOST="<platform-access-domain-or-vip>"
export REGISTRY_DOMAIN="<platform-registry-domain-or-vip>:11443"
export CLUSTER_CIDR="100.3.0.0/16"
export SERVICE_CIDR="100.4.0.0/16"
export K8S_VERSION="<target-kubernetes-version>"
export INGRESS_CLASS_NAME="global-alb2"
export HCS_SECRET_NAME="global-secret"
# Use v-prefixed semver that matches the target Alauda OS image.

    从 KIND 主机推送包时使用 LOCAL_REGISTRY_ADDRESS。在 AppRelease chart repository values 中使用 BOOTSTRAP_REGISTRY_ADDRESS，因为 provider Pod 会从 bootstrap KIND 网络内部读取 chart repository。在 Cluster API registry 注释中使用 NODE_REGISTRY_ADDRESS，因为已部署的 global 节点必须通过其子网内可达的地址拉取镜像。

    第 2 步 — 引导 KIND 主机

    运行 Core Package 提供的 bootstrap 脚本。这会在 KIND 主机上拉起一个临时管理集群 minialauda。

    mkdir -p /root/cpaas-install
tar -xvf <core-package> -C /root/cpaas-install
cd /root/cpaas-install/installer
sh setup.sh
mkdir -p ~/.kube
cp /var/cpaas/data/alauda.kubeconfig ~/.kube/config

    bootstrap 脚本会部署一个嵌入式 registry、Cluster API 控制平面以及驱动 global 集群安装的安装器组件。

    第 3 步 — 上传并安装 Provider 包

    将 Kubeadm provider 包和基础设施提供商包上传到本地 registry。

    为何所有提供商的 cluster.type 都是 Baremetal

    下方各个选项卡中的 AppRelease values 都将 global.cluster.type 设置为 Baremetal。这是一种 chart 内部分类，而不是 IaaS 提供商名称。对于 Huawei DCS、VMware vSphere 和 Huawei Cloud Stack 的 global 安装，请保持使用 Baremetal。该值用于驱动平台如何配置节点级组件；它不会用于选择基础设施提供商。

    Huawei DCS
    VMware vSphere
    Huawei Cloud Stack
    裸金属

    设置 provider 包路径和 chart 版本。

    export DCS_PROVIDER_PACK="/root/cluster-api-provider-dcs.amd64.<version>.tgz"
export KUBEADM_PROVIDER_PACK="/root/cluster-api-provider-kubeadm.amd64.<version>.tgz"
export DCS_PROVIDER_VERSION="<dcs-provider-chart-version>"
export KUBEADM_PROVIDER_VERSION="<kubeadm-provider-chart-version>"

    上传这些包。

    /root/cpaas-install/installer/res/amd64/packtool pack push \
  -r "${LOCAL_REGISTRY_ADDRESS}" -c "${DCS_PROVIDER_PACK}"

/root/cpaas-install/installer/res/amd64/packtool pack push \
  -r "${LOCAL_REGISTRY_ADDRESS}" -c "${KUBEADM_PROVIDER_PACK}"

    为 Kubeadm provider 和 DCS provider 创建并应用 AppRelease 资源。

    mkdir -p /root/yamls
export DCS_PROVIDER_APPRELEASES="/root/yamls/dcs-provider-appreleases.yaml"

cat > "${DCS_PROVIDER_APPRELEASES}" <<EOF
---
apiVersion: operator.alauda.io/v1alpha1
kind: AppRelease
metadata:
  annotations:
    auto-recycle: "true"
    interval-sync: "true"
  name: cluster-api-provider-kubeadm
  namespace: cpaas-system
spec:
  destination:
    cluster: ""
    namespace: ""
  source:
    chartPullSecret: global-registry-auth
    charts:
      - name: ait/chart-cluster-api-provider-kubeadm
        releaseName: cluster-api-provider-kubeadm
        targetRevision: ${KUBEADM_PROVIDER_VERSION}
    repoURL: ${BOOTSTRAP_REGISTRY_ADDRESS}
  timeout: 120
  values:
    global:
      albName: ${INGRESS_CLASS_NAME}
      auth:
        default_admin: admin@cpaas.io
      cluster:
        isGlobal: true
        name: global
        networkType: kube-ovn
        type: Baremetal
      host: ${PLATFORM_HOST}
      ingress:
        ingressClassName: ${INGRESS_CLASS_NAME}
      labelBaseDomain: cpaas.io
      namespace: cpaas-system
      platformUrl: https://${PLATFORM_HOST}
      protectSecretFiles:
        enabled: false
      region: global
      registry:
        address: ${BOOTSTRAP_REGISTRY_ADDRESS}
        imagePullSecrets:
          - global-registry-auth
      replicas: 1
      scheme: https
---
apiVersion: operator.alauda.io/v1alpha1
kind: AppRelease
metadata:
  annotations:
    auto-recycle: "true"
    interval-sync: "true"
  name: cluster-api-provider-dcs
  namespace: cpaas-system
spec:
  destination:
    cluster: ""
    namespace: ""
  source:
    chartPullSecret: global-registry-auth
    charts:
      - name: ait/chart-cluster-api-provider-dcs
        releaseName: cluster-api-provider-dcs
        targetRevision: ${DCS_PROVIDER_VERSION}
    repoURL: ${BOOTSTRAP_REGISTRY_ADDRESS}
  timeout: 120
  values:
    global:
      albName: ${INGRESS_CLASS_NAME}
      auth:
        default_admin: admin@cpaas.io
      cluster:
        isGlobal: true
        name: global
        networkType: kube-ovn
        type: Baremetal
      host: ${PLATFORM_HOST}
      ingress:
        ingressClassName: ${INGRESS_CLASS_NAME}
      labelBaseDomain: cpaas.io
      namespace: cpaas-system
      platformUrl: https://${PLATFORM_HOST}
      protectSecretFiles:
        enabled: false
      region: global
      registry:
        address: ${BOOTSTRAP_REGISTRY_ADDRESS}
        imagePullSecrets:
          - global-registry-auth
      replicas: 1
      scheme: https
EOF

kubectl apply -f "${DCS_PROVIDER_APPRELEASES}"

until kubectl get crd kubeadmcontrolplanes.controlplane.cluster.x-k8s.io --ignore-not-found 2>/dev/null | grep -q kubeadmcontrolplanes.controlplane.cluster.x-k8s.io; do
  sleep 10
done

until kubectl get crd dcsclusters.infrastructure.cluster.x-k8s.io --ignore-not-found 2>/dev/null | grep -q dcsclusters.infrastructure.cluster.x-k8s.io; do
  sleep 10
done

    第 4 步 — 配置 provider 特定的 global Manifest

    为 global 集群创建一个 provider 特定的 manifest。该 manifest 使用的 provider 资源与业务集群相同，但还必须包含平台控制平面所需的 global 特定标签、注解、registry 值、与安装器兼容的 kubeadm 设置以及持久数据路径。

    请使用 provider 创建指南作为详细的资源参考：

    将 通用前提条件中的命名规范 应用于你在下方编写的 manifest 中的每个资源。

    将 KubeadmControlPlane.spec.kubeadmConfigSpec.format 设置为目标提供商接受的值。provider controller 会强制执行此要求：

    提供商Bootstrap userdata 格式
    Huawei DCSignition（provider 强制要求；DCS provider 会拒绝任何其他格式，并返回 invalid format, expected ignition, got <other>）。
    VMware vSpherecloud-init（provider 默认值；不支持设置为 ignition）。
    Huawei Cloud Stackcloud-init（provider 强制要求；HCS 会拒绝 ignition，并返回 ignition format is not supported）。
    Huawei DCS
    VMware vSphere
    Huawei Cloud Stack
    裸金属

    在渲染之前，为 DCS global manifest 设置输出路径。

    export GLOBAL_DCS_YAML="/root/yamls/new-global.yaml"

    DCS global manifest 必须在 cpaas-system 命名空间中包含以下资源：

    资源目的
    Secret，类型为 CloudCredential存储 DCS API 访问所需的 authUser、authKey、endpoint 和 site。
    DCSIpHostnamePool，用于控制平面节点分配静态 IP、主机名、网络设置以及由池管理的持久磁盘。
    DCSMachineTemplate，用于控制平面节点定义 DCS VM 模板、folder、CPU、内存和模板本地磁盘。
    KubeadmControlPlane引导 Kubernetes 控制平面。将 spec.version 设置为 ${K8S_VERSION}。
    DCSCluster定义 DCS 基础设施集群和控制平面端点。
    Cluster将 Cluster API Cluster 连接到 DCSCluster 和 KubeadmControlPlane。
    DCSIpHostnamePool、DCSMachineTemplate、KubeadmConfigTemplate 和 MachineDeployment，用于 worker创建 worker 节点。

    使用 在 Huawei DCS 上创建集群 和 Huawei DCS 的基础设施资源 中的 DCS 资源字段。对于 global 集群，请保留以下附加要求：

    • 将 Cluster.metadata.name 和 DCSCluster.metadata.name 设置为 global（基础设施集群与 CAPI Cluster 共用同一个名称）。为其他所有 CAPI 资源和 provider 资源添加 global- 前缀；下方的 wiring 片段使用 KubeadmControlPlane.metadata.name: global-kcp。
    • 添加 Cluster.metadata.labels.is-global: "true" 和 Cluster.metadata.labels.cluster-type: DCS。
    • 添加 Cluster.metadata.annotations["cpaas.io/registry-address"]，值为 ${NODE_REGISTRY_ADDRESS}。
    • 为 Alauda OS 设置 KubeadmControlPlane.spec.kubeadmConfigSpec.format: ignition。
    • 保留发布 manifest 中非加密的 kubeadm 文件、kubelet patch、audit policy 和 installer RBAC 条目。
    • 对于普通的非 DR 部署，不要设置 DCSCluster.spec.encryptionProviderConfigRef，也不要在 KubeadmControlPlane.spec.kubeadmConfigSpec.files 中添加 /etc/kubernetes/encryption-provider.conf。
    • 保持 /var/cpaas 作为平台状态。如果需要磁盘在滚动替换后继续保留，请将其声明在 DCSIpHostnamePool.spec.pool[].persistentDisk 中；不要依赖 DCSMachineTemplate 模板磁盘作为持久状态。
    • 除非你已验证所选 datastore cluster 能够在可运行目标 VM 的主机上放置卷，否则请为 DCS 本地存储使用具体的 datastoreName 值。
    片段范围

    以下 YAML 是差异片段，不是可以直接应用的完整 manifest。请将这些 global 特定变更合并到你根据 DCS create-cluster 参考准备的 manifest 中，然后再应用完整 manifest 文件。

    下方片段展示了 global 特定的 Cluster API wiring。请使用上面的 DCS create-cluster 参考来填充 provider 资源字段。

    apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: global
  namespace: cpaas-system
  labels:
    cluster-type: DCS
    is-global: "true"
  annotations:
    capi.cpaas.io/resource-group-version: infrastructure.cluster.x-k8s.io/v1beta1
    capi.cpaas.io/resource-kind: DCSCluster
    cpaas.io/registry-address: "${NODE_REGISTRY_ADDRESS}"
spec:
  clusterNetwork:
    pods:
      cidrBlocks:
        - ${CLUSTER_CIDR}
    services:
      cidrBlocks:
        - ${SERVICE_CIDR}
  controlPlaneRef:
    apiVersion: controlplane.cluster.x-k8s.io/v1beta1
    kind: KubeadmControlPlane
    name: global-kcp
  infrastructureRef:
    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    kind: DCSCluster
    name: global
---
apiVersion: controlplane.cluster.x-k8s.io/v1beta1
kind: KubeadmControlPlane
metadata:
  name: global-kcp
  namespace: cpaas-system
  annotations:
    controlplane.cluster.x-k8s.io/skip-kube-proxy: ""
spec:
  replicas: 3
  version: ${K8S_VERSION}
  rolloutStrategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 0
  machineTemplate:
    nodeDrainTimeout: 1m
    nodeDeletionTimeout: 5m
    infrastructureRef:
      apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
      kind: DCSMachineTemplate
      name: global-master-template
  kubeadmConfigSpec:
    format: ignition
    clusterConfiguration:
      etcd:
        local:
          serverCertSANs:
            - "${CONTROL_PLANE_VIP}"
            - "${PLATFORM_HOST}"

    第 5 步 — 应用 global Manifest

    将 provider 特定的 manifest 应用到 minialauda。

    Huawei DCS
    VMware vSphere
    Huawei Cloud Stack
    裸金属
    kubectl apply -f "${GLOBAL_DCS_YAML}"

    第 6 步 — 等待控制平面

    等待 Cluster API provider 部署虚拟机并拉起 Kubernetes 控制平面。

    kubectl get clusters.cluster.x-k8s.io -n cpaas-system
kubectl get kubeadmcontrolplane -n cpaas-system
kubectl get machines -n cpaas-system

    当 KubeadmControlPlane 报告 Ready: True 且 Cluster 报告 Phase: Provisioned 时，控制平面即已就绪。

    第 7 步 — 导入 Provider 资源

    在触发安装器之前，对于需要额外资源导入的 provider，请在 cpaas-system 命名空间中创建 dcs-import-extra-resources ConfigMap。即使 provider 不是 Huawei DCS，ConfigMap 名称仍保留 dcs 前缀，以兼容历史安装器。

    VMware vSphere 和 Huawei Cloud Stack 在正常和灾难恢复的 global 安装中都需要此 ConfigMap。Huawei DCS 的默认安装不需要它，因为 DCS provider 资源会通过内置流程迁移；只有当你需要导入内置 provider 资源迁移之外的额外资源时，才为 DCS 创建它。

    Huawei DCS
    VMware vSphere
    Huawei Cloud Stack
    裸金属

    对于默认的 DCS 安装路径，不要创建 DCS dcs-import-extra-resources ConfigMap。DCS provider 资源会通过内置流程迁移。

    第 8 步 — 触发平台安装

    向嵌入式安装器 REST API 提交平台安装请求。安装器会将 Cluster API 资源导入到新的 global 集群中，部署基础 operator，并安装所选插件。

    export INSTALLER_IP=$(kubectl get pods -n cpaas-system -l service_name=cpaas-installer \
  -o jsonpath='{.items[0].status.podIP}')
    网络范围

    INSTALLER_IP 是 minialauda 中嵌入式安装器的 Pod IP。该端点仅在安装期间使用。

    在当前 KIND 主机上创建 provider 特定的安装器配置 JSON 文件，然后将其提交到安装器端点。DCS、VMware vSphere 和 HCS 使用相同的端点路径，但请求体不同。

    字段Huawei DCSVMware vSphereHuawei Cloud Stack
    端点路径/cpaas-installer/api/config/dcs/cpaas-installer/api/config/dcs/cpaas-installer/api/config/dcs
    console.host本地 global HA VIP 列表空列表 []空列表 []
    console.globalHost平台访问地址平台访问地址平台访问地址
    cluster.clusterCIDR 和 cluster.serviceCIDR必填不设置；cluster CIDR 在 VMware vSphere Cluster manifest 中声明不设置
    cluster.features.ha必填，指向本地 HA VIP，且 isThirdParty: true不设置；控制平面端点在 VSphereCluster.spec.controlPlaneEndpoint.host 中声明不设置；HCS ELB 在 HCSCluster 中声明
    hostIP当前 KIND 主机 IP当前 KIND 主机 IP当前 KIND 主机 IP
    Huawei DCS
    VMware vSphere
    Huawei Cloud Stack
    裸金属

    DCS 安装器请求包含外部 HA VIP，因为 DCS 使用第三方控制平面 VIP。

    mkdir -p /root/yamls
export INSTALLER_CONFIG_JSON="/root/yamls/installer-config-dcs.json"

cat > "${INSTALLER_CONFIG_JSON}" <<EOF
{
  "basic": {
    "username": "admin@cpaas.io",
    "password": "<base64-platform-admin-password>"
  },
  "registry": {
    "domain": "${REGISTRY_DOMAIN}",
    "username": "<registry-username>",
    "password": "<base64-registry-password>"
  },
  "console": {
    "host": [
      "${CONTROL_PLANE_VIP}"
    ],
    "globalHost": "${PLATFORM_HOST}",
    "httpPort": 80,
    "httpsPort": 443,
    "cert": {
      "selfSigned": {}
    }
  },
  "cluster": {
    "clusterCIDR": "${CLUSTER_CIDR}",
    "serviceCIDR": "${SERVICE_CIDR}",
    "features": {
      "ha": {
        "vip": "${CONTROL_PLANE_VIP}",
        "vport": 6443,
        "isThirdParty": true
      }
    }
  },
  "product": [
    "base",
    "acp"
  ],
  "deployMode": "normal",
  "hostIP": "${HOST_IP}"
}
EOF

curl -k -X POST "http://${INSTALLER_IP}:8080/cpaas-installer/api/config/dcs" \
  -H 'Content-Type: application/json' \
  -d @"${INSTALLER_CONFIG_JSON}"

    将 console.host 和 cluster.features.ha.vip 设置为本地 global HA VIP。不要在 console.host 中使用平台域名；平台访问地址请使用 console.globalHost。

    第三方控制台证书

    示例使用自签名控制台证书。如果环境要求第三方证书，请在提交安装器请求之前，将 console.cert 替换为一个 thirdParty 块，其中包含 base64 编码的完整证书链、私钥以及可选的 PKCS#12 值。

    第 9 步 — 监控安装过程

    安装器接受请求后，安装会经过多个阶段，并且可以从 KIND 主机上观察到。典型的不可变操作系统 global 集群需要 30–60 分钟；总耗时取决于 IaaS 部署速度、镜像拉取时间以及所选插件数量。

    你将观察到的阶段

    阶段正在发生什么首先查看的位置
    Bootstrapbootstrap KIND、嵌入式 registry 和 Cluster API providers 正在 KIND 主机上运行。第 2 步和第 3 步已完成。KIND 主机终端；kubectl get pods -n cpaas-system
    基础设施部署Cluster API provider 正在目标 IaaS 平台上从 Alauda OS 模板创建 VM。kubectl get machines -n cpaas-system
    控制平面引导KubeadmControlPlane 引导第一个控制平面节点，etcd 启动，其余控制平面节点加入集群。kubectl get kubeadmcontrolplane -n cpaas-system
    网络和核心附加组件CAPI provider 正在新集群上协调 Kube-OVN、CoreDNS 和 kube-proxy。kubectl --kubeconfig <global-kubeconfig> get pods -n kube-system
    平台安装安装器将 Cluster API 资源导入新的 global 集群，部署基础 operator，并安装所选插件。安装器进度 API；安装器日志
    完成安装器将请求标记为 Success，并将最终集群状态写入 ClusterModule/global。安装器进度 API；kubectl --kubeconfig <global-kubeconfig> get clustermodule global

    安装期间的信号

    请同时关注安装器进度 API 和安装器日志。如果其中一个看起来停滞，请直接在 bootstrap KIND 主机上检查底层 Cluster API 资源。

    # Installer progress and live log
curl "http://${INSTALLER_IP}:8080/cpaas-installer/api/progress"
tail -f /var/cpaas/data/installer.log

# Cluster API resources on the bootstrap KIND host
kubectl get clusters.cluster.x-k8s.io -A
kubectl get kubeadmcontrolplane -A
kubectl get machines -A

    安装器日志会记录每一次阶段切换。瞬时错误会以短间隔重试；持续错误会一直显示在日志中，并在进度 API 中体现为停滞阶段。

    当安装器报告成功后，检查 global 集群。

    kubectl --kubeconfig <global-kubeconfig> get nodes
kubectl --kubeconfig <global-kubeconfig> get pods -n cpaas-system
kubectl --kubeconfig <global-kubeconfig> get clustermodule global

    常见卡住情况及排查位置

    症状首先查看的位置你需要关注的内容
    Machine 一直处于 Pending 或根本未出现kubectl describe machine -n cpaas-system <machine>Machine Bootstrap 和 Infrastructure 条件中的 provider 特定失败原因。IaaS 配额、网络和凭证问题通常会在这里暴露。
    KubeadmControlPlane 无法到达 Ready使用新集群 kubeconfig 执行 kubectl get nodes，以及 kubectl describe kubeadmcontrolplane -n cpaas-system第一个控制平面节点上的 etcd 健康状况，以及其余节点的加入进度。
    kube-system 中的 Pod 一直 Pending 或拉取镜像失败kubectl --kubeconfig <global-kubeconfig> describe pod -n kube-system <pod>镜像拉取错误通常意味着节点侧 registry 地址无法从新集群子网访问。
    安装器进度 API 显示某个阶段停滞/var/cpaas/data/installer.log最近的阶段行以及最近的错误消息。重试中的错误会以短间隔重复；持续错误不会推进。
    ClusterModule/global 无法进入健康阶段kubectl --kubeconfig <global-kubeconfig> describe clustermodule globalStatus.conditions 会说明是哪个模块阻止了集群完成。

    这里未列出的其他问题通常指向环境特定原因。请收集安装器日志、进度 API 响应以及相关的 kubectl describe 输出，然后上报。

    可选的灾难恢复部署

    当你为灾难恢复部署主集群和待机 global 集群时，使用本节内容。在为每个 global 集群应用 provider 特定 manifest 之前，先完成这些补充项。

    主集群和待机集群必须使用相同的 encryption provider 配置。对于 DCS 和 HCS，正常的非 DR 部署不会在 KubeadmControlPlane.spec.kubeadmConfigSpec.files 中添加 /etc/kubernetes/encryption-provider.conf；对于 DCS，正常的非 DR 部署也不会设置 DCSCluster.spec.encryptionProviderConfigRef。VMware vSphere 会保留发布 manifest 中的 /etc/kubernetes/encryption-provider.conf 文件条目。

    准备共享 DR 变量

    在主集群和待机集群的安装环境上设置相同的加密密钥值。

    export ENCRYPTION_PROVIDER_CONF="/root/yamls/encryption-provider.conf"
export ENCRYPTION_PROVIDER_SECRET_B64="<base64-shared-etcd-encryption-key>"
export PRIMARY_CLUSTER_VIP="<primary-ha-vip>"
export STANDBY_CLUSTER_VIP="<standby-ha-vip>"
export ETCD_SYNC_VERSION="<global-etcd-sync-version>"
export ETCD_SYNC_MODULEINFO="/root/yamls/global-etcd-sync-moduleinfo.json"

    在两个安装环境上创建 encryption provider 配置文件。

    mkdir -p "$(dirname "${ENCRYPTION_PROVIDER_CONF}")"
cat > "${ENCRYPTION_PROVIDER_CONF}" <<EOF_CONF
apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
- resources:
  - secrets
  providers:
  - aescbc:
      keys:
      - name: key1
        secret: ${ENCRYPTION_PROVIDER_SECRET_B64}
EOF_CONF

    为 KubeadmControlPlane 添加 DR 证书 SAN

    在第 4 步生成的 manifest 中，将主集群和待机集群的控制平面 VIP 以及平台访问地址都包含到 KubeadmControlPlane.spec.kubeadmConfigSpec.clusterConfiguration.etcd.local.serverCertSANs 中。主集群和待机集群的安装环境都应使用相同的 SAN 列表。

    serverCertSANs:
  - "${PRIMARY_CLUSTER_VIP}"
  - "${STANDBY_CLUSTER_VIP}"
  - "${PLATFORM_HOST}"

    添加 provider 特定的 DR 字段

    Huawei DCS
    VMware vSphere
    Huawei Cloud Stack
    裸金属

    在 minialauda 中创建 encryption provider Secret。

    kubectl create secret generic encryption-provider-config \
  --from-file=encryption-provider.conf="${ENCRYPTION_PROVIDER_CONF}" \
  -n cpaas-system \
  --dry-run=client -o yaml | kubectl apply -f -

    将该 Secret 引用添加到 DCSCluster.spec。

    encryptionProviderConfigRef:
  name: encryption-provider-config

    DCS 使用 DCSCluster.spec.encryptionProviderConfigRef 来交付灾难恢复所需的 encryption provider 配置。对于 DCS DR 路径，不要在 KubeadmControlPlane.spec.kubeadmConfigSpec.files 中添加 /etc/kubernetes/encryption-provider.conf。

    如果你创建了 dcs-import-extra-resources，请在主集群和待机集群的安装环境上都保留该 ConfigMap。

    安装主集群和待机集群

    为主集群和待机 global 集群都执行第 1 步到第 9 步。

    两侧都要使用 provider 特定的安装器配置差异：

    提供商主集群安装待机集群安装
    Huawei DCS将 console.host 和 cluster.features.ha.vip 设置为主集群 HA VIP。将 console.host 和 cluster.features.ha.vip 设置为待机集群 HA VIP。
    VMware vSphere将 VSphereCluster.spec.controlPlaneEndpoint.host 设置为主 manifest 中使用的主集群 HA VIP。创建第 7 步中的 VMware vSphere dcs-import-extra-resources ConfigMap，并保持 global-vsphere-credentials 与 VSphereCluster.spec.identityRef.name 一致。将 VSphereCluster.spec.controlPlaneEndpoint.host 设置为待机 manifest 中使用的待机集群 HA VIP。创建第 7 步中的 VMware vSphere dcs-import-extra-resources ConfigMap，并保持 global-vsphere-credentials 与 VSphereCluster.spec.identityRef.name 一致。
    Huawei Cloud Stack保持 console.host: []；主集群 VIP 由 HCS ELB 管理。创建第 7 步中的 HCS dcs-import-extra-resources ConfigMap，并保持 HCS_SECRET_NAME 与 HCSCluster.spec.identityRef.name 一致。保持 console.host: []；待机集群 VIP 由 HCS ELB 管理。创建第 7 步中的 HCS dcs-import-extra-resources ConfigMap，并保持 HCS_SECRET_NAME 与 HCSCluster.spec.identityRef.name 一致。

    对于主集群，请确保平台域名解析到主集群 HA VIP。在第 8 步中，将 hostIP 设置为主 KIND 节点 IP。对于 DCS，将 console.host 和 cluster.features.ha.vip 设置为主集群 HA VIP。对于 VMware vSphere，将主 manifest 中的控制平面端点设置为主集群 HA VIP。对于 HCS，保持 console.host: []，因为 VIP 由 HCS ELB 管理。

    在主集群安装成功后，根据 DR 流程要求，将平台域名切换到待机集群 HA VIP。然后安装待机集群。在待机 KIND 主机上的第 8 步中，将 hostIP 设置为待机 KIND 节点 IP。对于 DCS，将 console.host 和 cluster.features.ha.vip 设置为待机集群 HA VIP。对于 VMware vSphere，将待机 manifest 中的控制平面端点设置为待机集群 HA VIP。对于 HCS，保持 console.host: []。INSTALLER_IP 请从待机 KIND 主机上的 cpaas-installer Pod 获取；不要复用主 KIND 主机的值。

    在两个集群都安装完成后，在主控制平面节点上获取主集群的 k8sadmin 令牌。etcd-sync 仅安装在待机集群上，其 active_cluster_* 值指向主集群。请将该值保持为原始的 base64 Secret 形式，用于 active_cluster_token。

    export PRIMARY_CLUSTER_TOKEN_B64="$(sudo kubectl get secret -n cpaas-system k8sadmin -o jsonpath='{.data.token}')"

    在待机控制平面节点上获取待机集群的 k8sadmin 令牌。使用这个解码后的 bearer token 调用待机集群的 ModuleInfo API。

    export STANDBY_CLUSTER_BEARER_TOKEN="$(sudo kubectl get secret -n cpaas-system k8sadmin -o jsonpath='{.data.token}' | base64 -d)"

    如果你从其他主机创建 global-etcd-sync ModuleInfo payload，请将待机控制平面节点上的解码值安全传输到该主机并在那里导出。

    export STANDBY_CLUSTER_BEARER_TOKEN="<decoded-standby-token>"

    为待机集群创建 global-etcd-sync ModuleInfo payload。active_cluster_vip 和 active_cluster_token 的值必须指向主集群。

    cat > "${ETCD_SYNC_MODULEINFO}" <<EOF
{
  "kind": "ModuleInfo",
  "apiVersion": "cluster.alauda.io/v1alpha1",
  "metadata": {
    "name": "global-etcd-sync",
    "labels": {
      "cpaas.io/cluster-name": "global",
      "cpaas.io/module-name": "etcd-sync",
      "cpaas.io/module-type": "plugin"
    }
  },
  "spec": {
    "version": "${ETCD_SYNC_VERSION}",
    "config": {
      "monitor_check_interval": 1,
      "detail": false,
      "active_cluster_vip": "${PRIMARY_CLUSTER_VIP}",
      "active_cluster_token": "${PRIMARY_CLUSTER_TOKEN_B64}"
    }
  }
}
EOF

    通过调用待机集群上的 ModuleInfo API 来安装 global-etcd-sync。

    curl -sk -X POST "https://${STANDBY_CLUSTER_VIP}/apis/cluster.alauda.io/v1alpha1/moduleinfoes" \
  -H "Authorization: Bearer ${STANDBY_CLUSTER_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @"${ETCD_SYNC_MODULEINFO}"

    重启必须重新加载 DR 和端点配置的 Pod。在主控制平面节点和待机控制平面节点上执行相同命令。

    sudo kubectl delete po -n cpaas-system -l 'service_name in (alertmanager,vmselect,vminsert)'
sudo kubectl delete po -n cpaas-system -l service_name=cpaas-elasticsearch
sudo kubectl delete po -n cpaas-system -l service_name=cluster-transformer

    关于安装后的 DR 生命周期，请参见 Global Cluster Disaster Recovery。

    验证

    安装器报告完成后，请验证 global 集群是否健康。

    kubectl --kubeconfig <global-kubeconfig> get nodes
kubectl --kubeconfig <global-kubeconfig> get clusters.platform.tkestack.io global \
  -o jsonpath='{.status.phase}'
kubectl --kubeconfig <global-kubeconfig> get pods -n cpaas-system
kubectl --kubeconfig <global-kubeconfig> get clustermodule global

    当满足以下所有条件时，说明安装成功：

    • 安装器进度 API 报告 status: Success 且 type: Complete。
    • 所有 global 集群节点均为 Ready。
    • cpaas-system 中的关键 Pod 处于 Running 或 Completed 状态。
    • ClusterModule/global 报告基础模块健康。

    后续步骤