创建管理员集群

本文档介绍如何为 Google Distributed Cloud 创建管理员集群。管理员集群管理运行工作负载的用户集群。

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

过程概览

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

  1. 准备管理员工作站。
    此机器具有创建新集群所需的工具。
  2. 填写配置文件。
    通过完成并验证管理员集群配置文件、凭据配置文件以及可能的 IP 地址块文件,指定新管理员集群的详细信息。
  3. 将操作系统映像导入 vSphere,并将容器映像推送到私有注册表(如果适用的话)。
    运行 gkectl prepare
  4. 创建管理员集群。
    使用 gkectl 按照已完成配置文件中所指定的创建新的管理员集群。当 Google Distributed Cloud 创建管理员集群时,它会部署 Docker in Docker(种类)集群以临时托管创建管理员集群所需的 Kubernetes 控制器。此临时集群称为引导集群。用户集群由其管理员创建和升级,而无需使用引导集群。
  5. 验证管理员集群是否正在运行。
    使用 kubectl 查看集群节点。

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

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

准备工作

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

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

  • 请查看 privateRegistry 部分,决定要对 Google Distributed Cloud 组件使用公共注册表还是私有注册表。

  • 请查看 osImageType 字段,并确定要在管理员集群节点上运行的操作系统类型。

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

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

1. 准备管理员工作站

确保您已按照创建管理员工作站中的说明设置并登录管理员工作站。管理员工作站提供创建管理员集群所需的工具。

在管理员工作站上完成本文档中的所有其余步骤。

2. 填写配置文件

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

如果您未使用 gkeadm 创建管理员工作站,请通过在管理员工作站上运行以下命令来生成 admin-cluster.yaml

gkectl create-config admin

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

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

name

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

bundlePath

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

vCenter

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

network

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

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

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

loadBalancer

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

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

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

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

  • 使用 F5 BIG-IP 的集成式负载均衡。将 loadBalancer.kind 设置为 "F5BigIP",然后填写 f5BigIP 部分。

  • 手动负载均衡。将 loadBalancer.kind 设置为 "ManualLB",然后填写 manualLB 部分。

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

antiAffinityGroups

根据您的偏好将 antiAffinityGroups.enabled 设置为 truefalse

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

adminMaster

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

adminMaster 部分中的 replicas 字段设置为 3

proxy

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

privateRegistry

确定将 Google Distributed Cloud 组件的容器映像保留在何处。以下是各个选项:

  • Container Registry

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

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

componentAccessServiceAccountKeyPath

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

系统已为您填写此字段。

gkeConnect

填写 gkeConnect 部分,将管理员集群注册到 Google Cloud 舰队。如果您在配置文件中包含 stackdrivercloudAuditLogging 部分,则 gkeConnect.projectID 中的 ID 必须与 stackdriver.projectIDcloudAuditLogging.projectID 中设置的 ID 相同。如果项目 ID 不同,集群创建将失败。

在 1.28 及更高版本中,您可以选择在 gkeConnect.location 中指定舰队和连接服务在哪个区域运行。如果您不添加此字段,集群将使用这些服务的全局实例。

如果您添加了 gkeConnect.location,则您指定的区域必须与在 cloudAuditLogging.clusterLocationstackdriver.clusterLocationgkeOnPremAPI.location 中配置的区域相同。如果区域不同,则集群创建将失败。

gkeOnPremAPI

如果您的 Google Cloud 项目中启用了 GKE On-Prem API,则项目中的所有集群都会自动在 stackdriver.clusterLocation 中配置的区域中注册 GKE On-Prem APIgkeOnPremAPI.location 区域必须与 cloudAuditLogging.clusterLocationgkeConnect.locationstackdriver.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 标志。

对于新集群,请注意以下要求:

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

  • stackdriver.clusterLocation 中设置的 Google Cloud 区域必须与在 cloudAuditLogging.clusterLocationgkeConnect.location 中设置的区域相同(如果配置文件中包含该字段)。此外,如果 gkeOnPremAPI.enabledtrue,则必须在 gkeOnPremAPI.location 中设置同一区域。

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

cloudAuditLogging

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

对于新集群,请注意以下要求:

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

  • cloudAuditLogging.clusterLocation 中设置的 Google Cloud 区域必须与在 stackdriver.clusterLocationgkeConnect.location 中设置的区域相同(如果配置文件中包含该字段)。此外,如果 gkeOnPremAPI.enabledtrue,则必须在 gkeOnPremAPI.location 中设置同一区域。

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

clusterBackup

如果要启用管理员集群备份功能,请将 clusterBackup.datastore 设置为要保存集群备份的 vSphere 数据存储区

autoRepair

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

secretsEncryption

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

osImageType

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

已填写的配置文件的示例

以下是已填写的管理员集群配置文件的示例。此配置可实现部分(而非全部)可用功能。

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-xxx 标志。如需详细了解 check-config 命令,请参阅运行预检检查

3. 获取操作系统映像

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

gkectl prepare --config ADMIN_CLUSTER_CONFIG

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

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

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

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

5. 创建管理员集群

创建管理员集群:

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 文件

在您运行 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 文件会自动更新。

6.验证管理员集群正在运行

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

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

7. 备份文件

我们建议您备份管理员集群 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 控制台中管理用户集群的生命周期。

问题排查

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

后续步骤

创建用户集群