创建用户集群以与拓扑网域搭配使用

在 Google Distributed Cloud 中，您的工作负载在一个或多个用户集群上运行。本页介绍了如何创建用户集群，以便在 Google Distributed Cloud 拓扑网域中使用。您需要使用 Google Distributed Cloud 1.31 或更高版本才能使用拓扑域。

若要设置拓扑网域，您需要启用高级集群。请注意高级集群预览版的以下限制：

  • 您只能在创建 1.31 版新集群时为其启用高级集群。
  • 启用高级集群后，您将无法将集群升级到 1.32。仅在测试环境中启用高级集群。

本页面适用于设置、监控和管理技术基础设施的管理员、架构师和运维人员。如需详细了解我们在 Google Cloud 内容中提及的常见角色和示例任务，请参阅常见的 GKE Enterprise 用户角色和任务。

准备工作

过程概览

使用 gkectl 创建用户集群涉及以下主要步骤：

  1. 填写用户集群配置文件
    在用户集群配置文件中指定新集群的详细信息。
  2. 填写 IP 地址块文件
    在 IP 地址块文件中指定网关、网络掩码、控制平面节点以及（可选）工作器节点的 IP 地址。
  3. 创建用户集群
    运行 gkectl create cluster 以按照配置文件中所指定的内容创建集群。
  4. 验证用户集群是否正在运行
    使用 kubectl 查看集群节点。

此过程结束时，您将有一个正在运行的用户集群，您可以在其中部署工作负载。

填写用户集群配置文件

如果您使用 gkeadm 创建管理员工作站，则 gkeadm 会为您的用户集群配置文件生成一个名为 user-cluster.yaml 的模板。此外，gkeadm 还为您填写了一些字段。

如果您未使用 gkeadm 创建管理员工作站，则可以使用 gkectl 为用户集群配置文件生成模板。

如需为用户集群配置文件生成模板，请运行以下命令：

gkectl create-config cluster --config=OUTPUT_FILENAME --gke-on-prem-version=VERSION

替换以下内容：

OUTPUT_FILENAME：您为生成的模板选择的路径。如果省略此标志，则 gkectl 将该文件命名为 user-cluster.yaml，并将其放在当前目录中。

VERSION：所需的版本号。例如：gkectl create-config cluster --gke-on-prem-version=1.31.0-gke.889。

浏览用户集群配置文件文档，以熟悉配置文件。建议您在单独的标签页或窗口中打开该文档，因为您在完成以下步骤时将参考它。

name

将 name 字段设置为您为用户集群选择的名称。

gkeOnPremVersion

系统已为您填写此字段。它指定 Google Distributed Cloud 的版本。例如 1.31.0-gke.889。

enableAdvancedCluster

将 enableAdvancedCluster 设置为 true。

enableControlplaneV2

所有 1.30 及更高版本的用户集群都必须使用 Controlplane V2。将 enableControlplaneV2 设置为 true。

启用 Controlplane V2 后，用户集群的控制平面在用户集群本身的节点上运行。

enableDataplaneV2

将 enableDataplaneV2 设置为 true。

vCenter

移除整个版块。而是按拓扑网域在 vSphere 基础架构配置文件中配置 vCenter 信息。

network

  • 从配置文件中移除以下内容：

    • 整个 network.hostConfig 部分。此信息在每个拓扑网域的 vSphere 基础架构配置文件中进行配置。
    • network.vCenter.networkName 字段。此字段在每个拓扑网域的 vSphere 基础架构配置文件中进行配置。
    • 整个 network.controlPlaneIPBlock 部分。网关、子网掩码和控制平面节点的 IP 地址在 IP 地址块文件中进行配置。

  • 将 network.ipMode.ipBlockFilePath 设置为 IP 地址块文件的路径。

  • 确定您要工作器节点获取其 IP 地址的方式。选项包括：

    • 从提前设置的 DHCP 服务器获取。将 network.ipMode.type 设置为 "dhcp"。

    • 从您在 IP 地址块文件中提供的静态 IP 地址列表获取。将 network.ipMode.type 设置为 "static"。

    用户集群的控制平面节点必须从您在 IP 地址块文件中提供的静态地址列表中获取其 IP 地址。即使工作器节点从 DHCP 服务器获取其地址，情况也是如此。

    无论您是依赖 DHCP 服务器还是指定静态 IP 地址列表，都需要有足够的 IP 地址供用户集群使用。如需了解所需的 IP 地址数量，请参阅规划 IP 地址。

  • network.podCIDR 和 network.serviceCIDR 具有预填充的值，您可以保持不变，除非它们与已在您的网络中使用的地址冲突。Kubernetes 会使用这些范围将 IP 地址分配给集群中的 Pod 和 Service。

loadBalancer

advancedNetworking

如果您计划创建出站 NAT 网关，请将 advancedNetworking 设置为 true。

multipleNetworkInterfaces

将 multipleNetworkInterfaces 设置为 false。拓扑域不支持为 Pod 使用多个网络接口。

storage

将 storage.vSphereCSIDisabled 设置为 true 可停用 vSphere CSI 组件的部署。

masterNode

  • 如果要为用户集群的控制平面节点指定 CPU 和内存，请填写 masterNode 部分中的 cpus 和 memoryMB 字段。

  • 仅支持高可用性 (HA) 集群。将 replicas 字段设置为 3，以指定集群将有三个控制平面节点。

  • 如需为控制平面节点启用自动调整大小功能，请将 autoResize.enabled 设置为 true。

  • 移除整个 masterNode.vsphere 部分。

  • 使用您希望控制平面节点所在的拓扑域的名称填充 masterNode.topologyDomains 字段。

nodePools

节点池是集群中全都具有相同配置的一组工作器节点。例如，您可能需要为每个节点池设置单独的拓扑域。您必须通过填写 nodePools 部分来至少指定一个节点池。

对于您指定的每个节点池：

  • 在 nodePools[i].topologyDomains 字段中，填写您希望节点池所在的拓扑域的名称。

  • 移除 nodePools[i].vsphere 部分中除 nodePools[i].vsphere.tags 以外的所有字段。您可以在每个拓扑域的 vSphere 基础架构配置文件中指定此信息。

# advanced-cluster-change #

将 nodePools[i].osImageType 设置为 ubuntu_cgroupv2 或 ubuntu_containerd。

如需详细了解节点池，请参阅节点池以及创建和管理节点池。

antiAffinityGroups

将 antiAffinityGroups.enabled 设置为 false。拓扑网域不支持分布式资源调度器 (DRS) 反亲和性规则。

stackdriver

填写 stackdriver 部分，为集群启用 Cloud Logging 和 Cloud Monitoring。

请注意以下要求：

  • stackdriver.projectID 中的 ID 必须与 gkeConnect.projectID 和 cloudAuditLogging.projectID 中的 ID 相同。

  • 在 stackdriver.clusterLocation 中设置的 Google Cloud 区域必须与在 cloudAuditLogging.clusterLocation 和 gkeConnect.location 中设置的区域相同。此外，如果 gkeOnPremAPI.enabled 为 true，则必须在 gkeOnPremAPI.location 中设置同一区域。

如果项目 ID 和区域不相同，则集群创建会失败。

gkeConnect

用户集群必须注册到 Google Cloud 舰队。

填写 gkeConnect 部分以指定舰队宿主项目和关联的服务账号。 gkeConnect.projectID 中的 ID 必须与 stackdriver.projectID 和 cloudAuditLogging.projectID 中设置的 ID 相同。如果项目 ID 不同，则集群创建会失败。

您可以选择在 gkeConnect.location 中指定 Fleet 服务和 Connect 服务运行的区域。如果您不添加此字段，则集群会使用这些服务的全球实例。

如果您在配置文件中添加 gkeConnect.location，则您指定的区域必须与 cloudAuditLogging.clusterLocation、stackdriver.clusterLocation 和 gkeOnPremAPI.location 中配置的区域相同。如果区域不相同，集群创建将失败。

gkeOnPremAPI

本部分介绍了如何在 GKE On-Prem API 中注册集群。

gkectl 命令行工具是唯一可用于使用拓扑域的集群的集群生命周期管理工具。虽然使用拓扑域的集群不支持 Google Cloud 控制台、Google Cloud CLI 和 Terraform，但您可以选择在创建集群时将其注册到 GKE On-Prem API。

如果在Google Cloud 项目中启用了 GKE On-Prem API，则项目中的所有集群会在 stackdriver.clusterLocation 中配置的区域中自动注册 GKE On-Prem API。gkeOnPremAPI.location 区域必须与 cloudAuditLogging.clusterLocation、gkeConnect.location 和 stackdriver.clusterLocation 中指定的区域相同。

  • 如果您想要在 GKE On-Prem API 中注册项目中的所有集群，请务必执行准备工作中的步骤，以在项目中激活和使用 GKE On-Prem API。

  • 如果您不想在 GKE On-Prem API 中注册集群，请添加此部分并将 gkeOnPremAPI.enabled 设置为 false。如果您不想注册项目中的任何集群，请在项目中停用 gkeonprem.googleapis.com（GKE On-Prem API 的服务名称）。如需查看相关说明，请参阅停用服务。

cloudAuditLogging

如果要将集群的 Kubernetes API 服务器中的审核日志与 Cloud Audit Logs 集成，请填写 cloudAuditLogging 部分。

请注意以下要求：

# advanced-cluster-change #

将 cloudAuditLogging.serviceAccountKeyPath 设置为与 stackdriver.serviceAccountKeyPath 相同的路径。

  • cloudAuditLogging.projectID 中的 ID 必须与 gkeConnect.projectID 和 stackdriver.projectID 中的 ID 相同。

  • cloudAuditLogging.clusterLocation 中的区域必须与 gkeConnect.location（如果配置文件包含该字段）和 stackdriver.clusterLocation 中设置的区域相同。此外，如果 gkeOnPremAPI.enabled 为 true，则必须在 gkeOnPremAPI.location 中设置同一区域。

如果项目 ID 和区域不相同，则集群创建会失败。

preparedSecrets

移除 preparedSecrets 字段。 启用拓扑网域后，不支持预先准备的凭据。

已填写的配置文件的示例

以下是 IP 地址块文件和用户集群配置文件的示例：

user-ipblock.yaml

blocks:
  - netmask: 255.255.255.0
    gateway: 172.16.21.1
    ips:
    - ip: 172.16.21.2
      hostname: worker-vm-1
    - ip: 172.16.21.3
      hostname: worker-vm-2
    - ip: 172.16.21.4
      hostname: worker-vm-3
    - ip: 172.16.21.5
      hostname: worker-vm-4
  - netmask: 255.255.255.0
    gateway: 100.115.223.254
    ips:
    - ip: 100.115.222.205
      hostname: cp-1
      isControlPlane: true
    - ip: 100.115.222.206
      hostname: cp-2
      isControlPlane: true
    - ip: 100.115.222.207
      hostname: cp-3
      isControlPlane: true

user-cluster.yaml

cat user-cluster.yaml
apiVersion: v1
kind: UserCluster
name: "my-user-cluster"
gkeOnPremVersion: 1.31.0-gke.889
enableAdvancedCluster: true
enableControlplaneV2: true
enableDataplaneV2: true
network:
  ipMode:
    type: "static"
    ipBlockFilePath: "user-ipblock.yaml"
  serviceCIDR: 10.96.0.0/20
  podCIDR: 192.168.0.0/16
loadBalancer:
  vips:
    controlPlaneVIP: "100.115.222.200"
    ingressVIP: "172.16.21.30"
  kind: "ManualLB"
  manualLB:
    ingressHTTPNodePort: 32527
    ingressHTTPSNodePort: 30139
    controlPlaneNodePort: 30968
masterNode:
  cpus: 4
  memoryMB: 8192
  replicas: 3
nodePools:
- name: "worker-node-pool1"
  cpus: 4
  memoryMB: 8192
  replicas: 3
  topologyDomains:
  - "domain1"
antiAffinityGroups:
  enabled: false
gkeConnect:
  projectID: "my-project-123"
  location: "us-central1"
  registerServiceAccountKeyPath: "connect-register-sa-2203040617.json"
stackdriver:
  projectID: "my-project-123"
  clusterLocation: "us-central1"
  enableVPC: false
  serviceAccountKeyPath: "log-mon-sa-2203040617.json"
autoRepair:
  enabled: true

以下是在上述示例中要理解的要点：

  • nodePools.replicas 字段设置为 3，这意味着 "worker-node-pool" 中有三个工作器节点。由于 network.ipMode.type 设置为 "static"，因此所有工作器节点都使用静态 IP 地址。

  • 控制平面节点和工作器节点的 IP 地址在 IP 地址块文件中指定。即使只有三个工作器节点，IP 地址块文件也包含四个工作器节点地址。在集群升级、更新和自动修复期间需要额外的工作器节点 IP 地址。控制平面节点的 IP 地址具有 isControlPlane: true 标志。

  • 高级集群、ControlPlane V2 和 Dataplane V2 已启用。

  • masterNode.replicas 字段设置为 3，因此集群将具有高可用性控制平面。

  • 控制平面 VIP 与控制平面节点位于同一 VLAN，入站流量 VIP 与工作器节点位于同一 VLAN

填写 IP 地址块文件

将 IP 地址块文件的模板复制到您在用户集群配置文件的 network.ipMode.ipBlockFilePath 字段中指定的目录中的文件。为管理员集群和每个用户集群创建单独的 IP 地址块文件。

将网关、子网掩码和控制平面节点的 IP 地址添加到 IP 地址块文件中。对于每个控制平面节点 IP 地址，请添加 isControlPlane: true，如上例所示。如果您需要高可用性 (HA) 用户集群，请指定三个 IP 地址。否则，请指定一个 IP 地址。您为控制平面节点指定的 IP 地址数量必须与用户集群配置文件的 masterNode.replicas 字段中的数量一致。

如果将 network.ipMode.type 设置为 "static"，请将工作器节点的 IP 地址添加到 IP 地址块文件中。请务必指定一个额外的 IP 地址，以供集群升级、更新和自动修复期间使用。

IP 地址块文件中的每个网关地址都必须与 vSphere 基础架构配置文件的 topologyDomains[i].network.gateway 字段中指定的地址一致。如需了解详情，请参阅拓扑域示例。

创建用户集群

运行以下命令以创建用户集群：

gkectl create cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG --config USER_CLUSTER_CONFIG

找到用户集群 kubeconfig 文件的位置

gkectl create cluster 命令会在当前目录中创建一个名为 USER_CLUSTER_NAME-kubeconfig 的 kubeconfig 文件。您稍后需要此 kubeconfig 文件才能与用户集群进行互动。

kubeconfig 文件包含您的用户集群的名称。如需查看集群名称，您可以运行以下命令：

kubectl config get-clusters --kubeconfig USER_CLUSTER_KUBECONFIG

输出会显示集群的名称。例如：

NAME
my-user-cluster

如果愿意，您可以更改 kubeconfig 文件的名称和位置。

验证用户集群是否正在运行

验证用户集群是否正在运行：

kubectl get nodes --kubeconfig USER_CLUSTER_KUBECONFIG

将 USER_CLUSTER_KUBECONFIG 替换为用户集群 kubeconfig 文件的路径。

输出会显示用户集群节点。例如：

cp-vm-1       Ready    control-plane,master   18m
cp-vm-2       Ready    control-plane,master   18m
cp-vm-3       Ready    control-plane,master   18m
worker-vm-1   Ready                           6m7s
worker-vm-2   Ready                           6m6s
worker-vm-3   Ready                           6m14s

配置 PodTemplate

拓扑标签会填充到拓扑网域中节点的标签中。除非您的拓扑网域设置使用了默认约束条件 "topology.kubernetes.io/zone" 作为拓扑键，否则您需要在部署、StatefulSet 或 ReplicaSet 的 pod 模板中配置拓扑键（如适用）。

例如，假设您在拓扑标签中将键定义为 "topology.examplepetstore.com/zone"。在 PodTemplate 中，您可以将键指定为 topologySpreadConstraints.topologyKey 字段的值。这样，Kubernetes 调度器便可在拓扑网域中分布 Pod，以确保高可用性，并防止在发生故障时任何单个区域出现过度集中。

问题排查

请参阅排查集群创建和升级问题。

后续步骤