使用 `gkectl` 创建管理员集群

使用 gkectl 为 Google Distributed Cloud for VMware（纯软件）创建管理员集群。如果您需要在本地环境内管理整个管理员集群生命周期，以满足严格的安全性、合规性或气隙要求，请使用 gkectl。您还可以使用 Terraform 或 Google Cloud 控制台创建管理员集群。

准备工作

  • 确保您已设置并且可以登录管理员工作站，如创建管理员工作站中所述。

  • 确保服务账号的 JSON 密钥文件位于管理员工作站上。

  • 查看 IP 地址规划文档。确保您有足够的 IP 地址供三个控制平面节点和一个控制平面 VIP 使用。如果您计划创建任何 kubeception 用户集群，则必须有足够的 IP 地址供这些用户集群的控制平面节点使用。

  • 查看负载均衡概览，并重新考虑有关要使用的负载均衡器类型的决定。对于手动负载均衡器，您必须先设置负载均衡器，然后才能创建管理员集群。

  • 如果您使用 gkectl 创建管理员集群，请确定您要为 Google Distributed Cloud 组件使用公共注册表还是私有注册表。如需了解如何使用私有 Docker 注册表，请参阅 privateRegistry。Terraform 和 Google Cloud 控制台均不支持使用私有 Docker 注册表来存储系统组件。

  • 确定您要在管理员集群节点上运行的操作系统类型。

  • 如果您的组织要求出站流量通过代理服务器，请务必将所需的 API 和 Artifact Registry 地址列入许可名单。

  • 在 1.29 版及更高版本中，服务器端预检检查默认处于启用状态。服务器端预检检查需要额外的防火墙规则。在管理员集群的防火墙规则中，搜索“预检检查”，并确保已配置所有必需的防火墙规则。服务器端预检检查在引导集群上运行，而不是在管理员工作站上本地运行。

过程概览

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

  1. 填写配置文件。指定新管理员凭据配置文件的详细信息，以及可能的 IP 地址块文件。

  2. 将操作系统映像导入 vSphere，并将容器映像推送到私有注册表（如果适用的话）。运行 gkectl prepare。

  3. 创建管理员集群。使用 gkectl 按照已完成配置文件中所指定的创建新的管理员集群。Google Distributed Cloud 在创建 管理员集群时，会部署一个 Kubernetes in Docker (kind) 集群，用于暂时托管创建 管理员集群所需的 Kubernetes 控制器。此暂时性集群称为引导集群。 用户集群由其管理员创建和升级，无需使用引导集群。

  4. 验证管理员集群是否正在运行。使用 kubectl 查看集群节点。

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

如果您使用 VPC Service Controls，在运行某些 gkectl 命令时可能会看到错误，例如 "Validation Category: GCP - [UNKNOWN] GCP service: [Stackdriver] could not get GCP services"。为避免这些错误，请在命令中添加 --skip-validation-gcp 参数。

填写配置文件

  • 确保您的管理员工作站具有所需的 gkectl 版本。通常，您使用的 gkectl 版本应与创建集群时将使用的版本相同。您可以在集群配置文件中的 gkeOnPremVersion 字段中指定集群版本。在创建集群期间，系统会强制执行以下版本规则：

    • gkectl 次要版本不能低于集群的次要版本。例如，不允许使用 1.29 版 gkectl 创建 1.30 版集群。补丁版本无关紧要。例如，您可以使用 gkectl 版本 1.29.0-gke.1456 创建具有更高补丁版本的集群，例如 1.29.1000-gke.94。

    • gkectl 次要版本最多只能比集群版本高两个次要版本。例如，如果您要创建 1.28 集群，则 gkectl 版本可以是 1.29 或 1.30。但您不能使用 gkectl 版本 1.31，因为它比集群版本高三个次要版本。

    如果需要，请参阅下载 gkectl 以获取受支持的 gkectl 版本。

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

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

gkectl create-config admin

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

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

name

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

bundlePath

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

vCenter

此部分中的字段已填充您在创建管理员工作站时输入的值。

enableAdvancedCluster

在 1.31 版中，如果您要启用高级集群功能，请将 enableAdvancedCluster 设置为 true。

请注意以下版本差异：

  • 在 1.31 版中，高级集群功能处于预览版阶段：

    • 您只能在创建集群时为新的 1.31 版集群启用高级集群。

    • 启用高级集群后，您将无法将集群升级到 1.32。请仅在测试环境中启用高级集群。

  • 在 1.32 版中，高级集群功能为正式版。

    • 默认情况下，管理员集群会创建为高级集群。如果您要创建非高级集群，必须明确将 enableAdvancedCluster 设置为 false。

    • 对于启用了高级集群功能的集群，支持集群升级。

  • 在 1.33 版及更高版本中，所有集群都会创建为高级集群。如果您将 enableAdvancedCluster 设置为 false，则集群创建会失败。

network

请填写 network.controlPlaneIPBlock 部分和 network.hostConfig 部分。此外，将 adminMaster.replicas 设置为 3。

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

根据需要填写配置文件的 network 部分中的其余字段。

loadBalancer

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

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

确定要使用的负载均衡类型。以下是各个选项：

  • MetalLB 捆绑式负载均衡。将 loadBalancer.kind 设置为 "MetalLB"。

  • 手动负载均衡。将 loadBalancer.kind 设置为 "ManualLB"，然后移除 manualLB 部分。

如需详细了解负载均衡选项，请参阅负载均衡概览。

antiAffinityGroups

根据您的偏好将 antiAffinityGroups.enabled 设置为 true 或 false。

使用此字段可指定您是否希望 Google Distributed Cloud 为管理员集群节点创建 VMware 分布式资源调度器 (DRS) 反亲和性规则，使其分布到数据中心内的至少三个物理主机上。

adminMaster

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

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

proxy

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

privateRegistry

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

  • Artifact Registry

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

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

如需详细了解如何使用私有注册表（包括普通集群和高级集群之间的差异），请参阅配置私有容器注册表。

componentAccessServiceAccountKeyPath

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

系统已为您填写此字段。

gkeConnect

通过填写 gkeConnect 部分，将管理员集群 注册到 Google Cloud 舰队。如果您在配置文件中添加 stackdriver 和 cloudAuditLogging 部分，则 gkeConnect.projectID 中的 ID 必须与 stackdriver.projectID 和 cloudAuditLogging.projectID 中设置的 ID 相同。如果项目 ID 不同，集群创建将失败。

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

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

gkeOnPremAPI

如果在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

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

默认情况下，此部分是必需的。也就是说，如果您不填写此部分，则必须在运行 gkectl create admin 时添加 --skip-validation-stackdriver 标志。

请注意以下要求：

  • 如果您 启用高级集群， 则必须在 cloudAuditLogging.serviceAccountKeyPath 和 stackdriver.serviceAccountKeyPath 中指定相同的路径。

  • 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 部分。

请注意以下要求：

  • 如果您启用高级集群，则必须在 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

如果您要启用管理员集群备份，请将 clusterBackup.datastore 设置为您要在其中保存集群备份的 vSphere 数据存储区。

如果您启用高级集群，请移除此部分。不支持将管理员集群备份到 vSphere 数据存储区。

autoRepair

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

secretsEncryption

如果要启用始终开启的 Secret 加密，请填写 secretsEncryption 部分。

如果您启用高级集群，请将 secretsEncryption.enabled 设置为 false。 不支持始终开启的 Secret 加密。

osImageType

决定您要用于管理员集群节点的操作系统映像类型，并相应地填写 osImageType 部分。

如果您启用高级集群，请将 osImageType 设置为 ubuntu_cgroupv2 或 ubuntu_containerd。

已填写的配置文件的示例

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

vc-01-admin-cluster.yaml

apiVersion: v1
kind: AdminCluster
name: "gke-admin-01"
bundlePath: "/var/lib/gke/bundles/gke-onprem-vsphere-1.28.0-gke.1-full.tgz"
vCenter:
  address: "vc01.example"
  datacenter: "vc-01"
  cluster: "vc01-workloads-1"
  resourcePool: "vc-01-pool-1"
  datastore: "vc01-datastore-1"
  caCertPath: "/usr/local/google/home/me/certs/vc01-cert.pem""
  credentials:
    fileRef:
      path: "credential.yaml"
      entry: "vCenter"
network:
  hostConfig:
    dnsServers:
    - "203.0.113.1"
    - "198.51.100.1"
    ntpServers:
    - "216.239.35.4"
  serviceCIDR: "10.96.232.0/24"
  podCIDR: "192.168.0.0/16"
  vCenter:
    networkName: "vc01-net-1"
  controlPlaneIPBlock:
    netmask: "255.255.248.0"
    gateway: "21.0.143.254"
    ips:
    - ip: "21.0.140.226"
      hostname: "admin-cp-vm-1"
    - ip: "21.0.141.48"
      hostname: "admin-cp-vm-2"
    - ip: "21.0.141.65"
      hostname: "admin-cp-vm-3"
loadBalancer:
  vips:
    controlPlaneVIP: "172.16.20.59"
  kind: "MetalLB"
antiAffinityGroups:
  enabled: true
adminMaster:
  cpus: 4
  memoryMB: 16384
  replicas: 3
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
clusterBackup:
  datastore: "vc-01-datastore-bu"
autoRepair:
  enabled: true
osImageType: "ubuntu_containerd"

验证配置文件

填写管理员集群配置文件后，请运行 gkectl check-config 以验证该文件是否有效：

gkectl check-config --config ADMIN_CLUSTER_CONFIG

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

如果该命令返回任何失败消息，请修复问题并再次验证文件。

如果您想跳过更耗时的验证，请传递 --fast 标志。如需跳过各项验证，请使用 --skip-validation-yyy 标志。如需详细了解 check-config 命令，请参阅运行预检检查。

获取操作系统映像

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

gkectl prepare --config ADMIN_CLUSTER_CONFIG

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

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

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

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

如果您将 bundlePath 配置为使用完整软件包，gkectl prepare 会使用软件包中包含的操作系统和容器映像 ，而无需从外部 网络下载它们。建议您在代理速度较慢或互联网访问受限的环境中使用此方法。如需了解详情，请参阅 关于 Google Distributed Cloud 软件包。

创建管理员集群

创建管理员集群：

gkectl create admin --config ADMIN_CLUSTER_CONFIG

如果您使用 VPC Service Controls，在运行某些 gkectl 命令时可能会看到错误，例如 "Validation Category: GCP - [UNKNOWN] GCP service: [Stackdriver] could not get GCP services"。为避免这些错误，请在命令中添加 --skip-validation-gcp 参数。

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

如果管理员集群创建失败或被取消，您可以再次运行 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 文件的名称和位置。

管理 checkpoint.yaml 文件

本部分仅适用于非高可用性管理员集群。创建高可用性管理员集群时不会使用 checkpoint.yaml 文件。

在您运行 gkectl create admin 命令创建管理员集群时，它在管理员集群数据磁盘所在的数据存储区文件夹中创建了一个检查点文件。默认情况下，此文件的名称为 DATA_DISK_NAME‑checkpoint.yaml。如果 DATA_DISK_NAME 的长度大于或等于 245 个字符，则由于 vSphere 对文件名长度的限制，其名称为 DATA_DISK_NAME.yaml。

此文件包含管理员集群状态和凭据，用于未来的升级。除非您按照删除管理员集群的流程操作，否则请勿删除此文件。

如果您已在 vCenter Server 实例中启用了虚拟机加密，则必须拥有 Cryptographic operations.Direct Access 特权才能创建或升级管理员集群。否则，检查点不会上传。如果您无法获取此权限，则可以在运行相关命令时使用隐藏的标志 --disable-checkpoint 禁止上传检查点文件。

在您运行 gkectl upgrade admin 命令或运行影响管理员集群的 gkectl update 命令时，checkpoint.yaml 文件会自动更新。

验证管理员集群正在运行

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

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

备份文件

我们建议您备份管理员集群 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 备份到您选择的其他位置。、

RBAC 政策

当您在管理员集群配置文件中填写 gkeConnect 部分后，系统会在创建或更新集群期间将集群注册到您的舰队。为了启用舰队管理功能， Google Cloud 会部署 Connect Agent，并创建一个 Google 服务账号来代表集群注册到的项目。Connect Agent 会建立与该服务账号的连接，以处理向集群的 Kubernetes API 服务器发出的请求。这样，您就能够在 Google Cloud中访问集群和工作负载管理功能（包括访问Google Cloud 控制台），以便与集群进行交互。

管理员集群的 Kubernetes API 服务器必须能够对来自 Connect Agent 的请求进行授权。为确保这一点，需在服务账号上配置以下基于角色的访问控制 (RBAC) 政策：

  • 模拟政策，用于授权 Connect Agent 代表服务账号向 Kubernetes API 服务器发送请求。

  • 权限政策，用于指定允许对其他 Kubernetes 资源执行的操作。

您需要有服务帐号和 RBAC 政策，才能在 控制台中管理用户集群的 Google Cloud 生命周期。