创建要在拓扑网域中使用的管理员集群

本页介绍了如何创建管理员集群，以便在 Google Distributed Cloud 拓扑网域中使用。管理员集群管理运行工作负载的用户集群。您必须使用 Google Distributed Cloud 1.31 或更高版本才能使用拓扑网域。

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

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

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

如需详细了解管理员集群，请参阅安装概览。

过程概览

以下是创建管理员集群所涉及的主要步骤：

  1. 填写管理员配置文件
    通过填写管理员集群配置文件，为新的管理员集群指定详细信息。
  2. 填写 vSphere 基础架构配置文件
    在 vSphere 基础架构配置文件中指定拓扑域的详细信息。
  3. 填写 IP 地址块文件
    在 IP 地址块文件中指定网关、网络掩码和控制平面节点的 IP 地址。
  4. 获取操作系统映像
    下载常规的 Google Distributed Cloud 软件包。然后，运行 gkectl prepare，将操作系统映像导入 vSphere，并将容器映像推送到私有注册表（如果适用）。
  5. 创建管理员集群。
    使用 gkectl 按照已完成配置文件中所指定的创建新的管理员集群。Google Distributed Cloud 在创建管理员集群时，会部署一个 Kubernetes in Docker (kind) 集群，用于暂时托管创建管理员集群所需的 Kubernetes 控制器。此暂时性集群称为引导集群。用户集群由其管理员创建和升级，无需使用引导集群。
  6. 验证管理员集群是否正在运行。
    使用 kubectl 查看集群节点。

此过程结束后，您将拥有一个正在运行的管理员集群，可用于在拓扑域中创建和管理用户集群。

准备工作

填写管理员集群配置文件

如果您使用 gkeadm 创建了管理员工作站，则它会生成一个名为 admin-cluster.yaml 的配置文件。

如果您不是使用 gkeadm 来创建管理员工作站，请在管理员工作站上运行以下命令来生成 admin-cluster.yaml：

gkectl create-config admin

此配置文件用于创建管理员集群。

通过扫描管理员集群配置文件文档熟悉该配置文件。建议您在单独的标签页或窗口中打开该文档，因为您在完成以下步骤时将参考它。

name

如果要为管理员集群指定名称，请填写 name 字段。

bundlePath

该软件包是一个包含集群组件的压缩文件。它包含在管理员工作站中。系统已为您填写此字段。

enableAdvancedCluster

将 enableAdvancedCluster 设置为 true。这会启用高级集群，这是设置拓扑域所必需的。

infraConfigFilePath

在 infraConfigFilePath 字段中添加 vSphere 基础架构配置文件的完整路径。

vCenter

移除整个版块。而是在 vSphere 基础架构配置文件中配置 vCenter Server 信息。

network

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

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

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

  • 将 network.ipMode.type 设置为 static。

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

loadBalancer

  • 将 loadBalancer.kind 设置为 "ManualLB"，然后移除 manualLB 部分。

  • 为管理员集群的 Kubernetes API 服务器预留一个 VIP 地址。提供您的 VIP 作为 loadBalancer.vips.controlPlaneVIP 的值

如需了解详情，请参阅管理员集群子网中的 VIP。

antiAffinityGroups

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

adminMaster

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

  • 管理员集群必须有三个控制平面节点。将 adminMaster 部分中的 replicas 字段设置为 3。

  • 如果您想为控制平面节点指定要使用的特定拓扑域，请将拓扑域名称添加到 adminMaster.topologyDomains 字段。如果您未在此处指定名称，则必须在 vSphere 基础架构配置文件的 vSphereInfraConfig.defaultTopologyDomain 中设置名称。

proxy

如果将拥有管理员集群节点的网络位于代理服务器后面，请填写 proxy 部分。

privateRegistry

确定 Google Distributed Cloud 组件的容器映像的存储位置。以下是各个选项：

  • Artifact Registry

  • 您自己的私有 Docker 注册表。

    如果要使用自己的私有注册表，请填写 privateRegistry 部分。

componentAccessServiceAccountKeyPath

Google Distributed Cloud 使用组件访问服务账号从 Artifact Registry 下载集群组件。此字段包含组件访问服务账号的 JSON 密钥文件的路径。

系统已为您填写此字段。

gkeConnect

通过填写 gkeConnect 部分，将管理员集群注册到 Google Cloud 舰队。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 的服务名称）。如需查看相关说明，请参阅停用服务。

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 和区域不相同，则集群创建会失败。

cloudAuditLogging

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

请注意新集群的以下要求：

  • 由于 enableAdvancedCluster 已设置为 true，因此您必须在 cloudAuditLogging.serviceAccountKeyPath 和 stackdriver.serviceAccountKeyPath 中指定相同的路径。

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

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

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

clusterBackup

移除此部分。 不支持将管理员集群备份到 vSphere 数据存储区。

autoRepair

如果您要为管理员集群启用自动节点修复功能，请将 autoRepair.enabled 设置为 true。

secretsEncryption

由于 enableAdvancedCluster 已设置为 true，因此请移除此部分。

osImageType

设置 osImageType。ubuntu_cgroupv2 和 ubuntu_containerd。

preparedSecrets

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

已填写的配置文件的示例

以下是填写好的管理员集群配置文件的示例。该配置支持部分（但不是全部）可用功能。

vc-01-admin-cluster.yaml

apiVersion: v1
kind: AdminCluster
name: "gke-admin-01"
bundlePath: "/var/lib/gke/bundles/gke-onprem-vsphere-1.31.0-gke.1-full.tgz"
enableAdvancedCluster: true
infraConfigFilePath: "/my-config-folder/vsphere-infrastructure-config.yaml"
network:
  serviceCIDR: "10.96.232.0/24"
  podCIDR: "192.168.0.0/16"
  ipMode:
    type: "static"
    ipBlockFilePath: "/my-config-folder/admin-cluster-ipblock.yaml"
loadBalancer:
  vips:
    controlPlaneVIP: "172.16.20.59"
  kind: "ManualLB"
antiAffinityGroups:
  enabled: false
adminMaster:
  cpus: 4
  memoryMB: 16384
  replicas: 3
  topologyDomains: "admin-cluster-domain"
componentAccessServiceAccountKeyPath: "sa-key.json"
gkeConnect:
  projectID: "my-project-123"
  registerServiceAccountKeyPath: "connect-register-sa-2203040617.json"
stackdriver:
  projectID: "my-project-123"
  clusterLocation: "us-central1"
  enableVPC: false
  serviceAccountKeyPath: "log-mon-sa-2203040617.json"
  disableVsphereResourceMetrics: false
autoRepair:
  enabled: true
osImageType: "ubuntu_containerd"

填写 vSphere 基础架构配置文件

将 vSphere 基础架构配置文件的模板复制到您在管理员集群配置文件的 infraConfigFilePath 字段中指定的目录中的文件。管理员集群和所有受管理的用户集群只有一个 vSphere 基础架构配置文件。

Secret

填写 vSphere 基础架构配置文件中的 Secret 部分。本部分介绍用于存储每个 vCenter 服务器凭据的 vSphere 凭据 Secret。

VSphereInfraConfig.name

填写 VSphereInfraConfig,name 字段。

VSphereInfraConfig.credentials.vCenters

对于每个 Secret，请添加相应的 VSphereInfraConfig.credentials.vCenters 部分。

VSphereInfraConfig,topologyDomains

填写 VSphereInfraConfig.topologyDomains 部分以定义拓扑域。

填写 IP 地址块文件

将 IP 地址块文件的模板复制到您在管理员集群配置文件的 network.ipMode.ipBlockFilePath 字段中指定的目录中的文件。添加网关、网掩和三个控制平面节点的 IP 地址。对于每个控制平面节点 IP 地址，请添加 isControlPlane: true，如拓扑域示例所示。

获取操作系统映像

  1. 将常规 Google Distributed Cloud 软件包下载到管理员工作站：

    gcloud storage cp gs://gke-on-prem-release/gke-onprem-bundle/VERSION/gke-onprem-vsphere-VERSION.tgz /var/lib/gke/bundles/gke-onprem-vsphere-VERSION.tgz

    将 VERSION 替换为您要安装的 Google Distributed Cloud 版本。

    此命令会下载常规软件包。请勿下载完整软件包，因为高级集群不支持该软件包。

  2. 运行 gkectl prepare 以初始化您的 vSphere 环境：

    gkectl prepare --config ADMIN_CLUSTER_CONFIG

    将 ADMIN_CLUSTER_CONFIG 替换为管理员集群配置的路径。

    gkectl prepare 命令可执行以下预备任务：

    • 将操作系统映像导入 vSphere 并将其标记为虚拟机模板。

    • 如果您使用的是私有 Docker 注册表，则会将容器映像推送到您的注册表。

    • （可选）验证容器映像的构建证明，从而确保这些映像已由 Google 构建和签名，并已准备好部署。

创建管理员集群

创建管理员集群：

gkectl create admin --config ADMIN_CLUSTER_CONFIG

发生故障后恢复管理员集群创建

如果管理员集群创建失败或被取消，您可以再次运行 create 命令：

gkectl create admin --config ADMIN_CLUSTER_CONFIG

找到管理员集群 kubeconfig 文件的位置

gkectl create admin 命令会在当前目录中创建一个名为 kubeconfig 的 kubeconfig 文件。您稍后需要此 kubeconfig 文件才能与管理员集群进行交互。

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

kubectl config get-clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG

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

NAME
gke-admin-tqk8x

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

验证管理员集群正在运行

验证管理员集群是否正在运行：

kubectl get nodes --kubeconfig ADMIN_CLUSTER_KUBECONFIG

将 ADMIN_CLUSTER_KUBECONFIG 替换为管理员集群 kubeconfig 文件的路径。

输出会显示管理员集群节点。 例如：

admin-cp-vm-1   Ready    control-plane,master   ...
admin-cp-vm-2   Ready    control-plane,master   ...
admin-cp-vm-3   Ready    control-plane,master   ...

配置 PodTemplate

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

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

如需详细了解如何配置 topologySpreadConstraints，请参阅 Kubernetes 文档中的 Pod 拓扑分布约束条件。

备份文件

我们建议您备份管理员集群 kubeconfig 文件。也就是说，将 kubeconfig 文件从管理员工作站复制到其他位置。因此，如果您失去对管理员工作站的访问权限，或者管理员工作站上的 kubeconfig 文件被意外删除，您仍然可以访问管理员集群。

我们还建议您备份管理员集群的 SSH 私钥。然后，如果您失去对管理员集群的访问权限，您仍然可以使用 SSH 连接到管理员集群节点。这样，您就可以排查和调查与管理员集群连接的问题。

将 SSH 密钥从管理员集群提取到名为 admin-cluster-ssh-key 的文件：

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG get secrets -n kube-system sshkeys \
    -o jsonpath='{.data.vsphere_tmp}' | base64 -d > admin-cluster-ssh-key

现在，您可以将 admin-cluster-ssh-key 备份到您选择的其他位置。、

问题排查

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

后续步骤

创建要在拓扑网域中使用的用户集群