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

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

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

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

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

准备工作

确保您已设置并且可以登录管理员工作站，如创建管理员工作站中所述。管理员工作站提供创建用户集群所需的工具。在管理员工作站上完成本文档中的所有步骤。
请按照以下文档中的说明设置您的 Google Cloud 资源（如果尚未这样做）：
在创建用户集群之前，您必须拥有一个管理员集群来管理用户集群。如果您尚未创建，请创建管理员工作站和管理员集群以用于拓扑网域。
确定要安装的用户集群版本。创建用户集群时，您通常应安装与管理员集群版本匹配的版本。如果您想在用户集群上安装其他版本，请参阅版本规则。
查看 IP 地址规划文档，并确保您有足够的 IP 地址可供使用。
为负载均衡器配置手动负载均衡。您必须先设置负载均衡器，然后才能创建用户集群。
考虑您需要的节点池数量以及每个池中运行的操作系统。
收集您访问每个 vCenter Server 实例所需的信息。您需要这些信息才能填写 vSphere 基础架构配置文件中的 Secret 部分和 VSphereInfraConfig.credentials.vCenters 部分。如需了解如何获取所需信息，请参阅以下内容：

过程概览

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

填写用户集群配置文件

在用户集群配置文件中指定新集群的详细信息。
填写 IP 地址块文件

在 IP 地址块文件中指定网关、网络掩码、控制平面节点以及（可选）工作器节点的 IP 地址。
创建用户集群

运行 gkectl create cluster 以按照配置文件中所指定的内容创建集群。
验证用户集群是否正在运行

使用 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.33.100-gke.89。

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

`name`

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

`gkeOnPremVersion`

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

`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`

为用户集群的 Kubernetes API 服务器预留一个 VIP。提供您的 VIP 作为 loadBalancer.vips.controlPlaneVIP 的值
为用户集群的入站流量服务预留另一个 VIP。提供您的 VIP 作为 loadBalancer.vips.ingressVIP 的值。
将 loadBalancer.kind 设置为 "ManualLB"，然后填写 manualLB 部分。如需了解详情，请参阅手动负载均衡。

`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 基础架构配置文件中指定此信息。
将 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 中指定舰队和连接服务运行的区域。如果您不添加此字段，则集群会使用这些服务的全球实例。

如果您在配置文件中添加 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 字段。启用拓扑网域后，不支持准备好的凭据。

`schedulerConfiguration`

如果您要设置将传递给 kube-scheduler 的其他配置，请将 schedulerConfiguration 部分添加到您的配置文件。

已填写的配置文件的示例

以下是 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.33.100-gke.89
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" 中有三个工作器节点。所有工作器节点都使用静态 IP 地址，因为 network.ipMode.type 设置为 "static"。
控制平面节点和工作器节点的 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" 作为拓扑键，否则您需要在 Deployment、StatefulSet 或 ReplicaSet 的 Pod 模板中配置拓扑键（如适用）。

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

问题排查

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

创建用于与拓扑网域搭配使用的用户集群 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

过程概览

填写用户集群配置文件

name

gkeOnPremVersion

enableAdvancedCluster

enableControlplaneV2

enableDataplaneV2

vCenter

network

loadBalancer

advancedNetworking

multipleNetworkInterfaces

storage

masterNode

nodePools

antiAffinityGroups

stackdriver

gkeConnect

gkeOnPremAPI

cloudAuditLogging