使用 GKE On-Prem API 客户端创建用户集群

本页面介绍如何使用 Google Cloud 控制台、Google Cloud CLI (gcloud CLI) 或 Terraform 创建用户集群。

什么是 GKE On-Prem API？

GKE On-Prem API 是由 Google Cloud 托管的 API，可让您使用 Terraform 和标准 Google Cloud 应用来管理本地集群的生命周期。GKE On-Prem API 在 Google Cloud 的基础架构中运行。Terraform、控制台和 gcloud CLI 是 API 的客户端，它们使用 API 在数据中心内创建集群。

为了管理集群的生命周期，GKE On-Prem API 必须使用您在创建集群时指定的 Google Cloud 区域将有关集群状态的元数据存储在 Google Cloud 中。此元数据可让 API 管理集群生命周期，并且不包含特定于工作负载的数据。

使用 GKE On-Prem API 客户端创建集群时，您需要指定 Google Cloud 项目。创建集群后，它会自动注册到指定项目的舰队。此项目称为舰队宿主项目。集群创建后，舰队宿主项目便无法更改。

如果您愿意，可以通过创建用户集群配置文件并使用 bmctl 来创建用户集群，如创建用户集群中所述。

如果您希望使用 Terraform、控制台或 gcloud CLI 管理使用 bmctl 创建的集群的生命周期，请参阅配置要由 GKE On-Prem API 管理的用户集群。

准备工作

本部分介绍了使用 GKE On-Prem API 客户端创建用户集群的要求。

授予 IAM 权限

如果您不是项目所有者，则必须获得 roles/gkeonprem.admin。

如果要在控制台中访问 Google Kubernetes Engine (GKE) Enterprise 版本和 Google Kubernetes Engine 页面，您还必须拥有以下角色：

创建集群后，如果您不是项目所有者，并且想要通过命令行使用连接网关连接到用户集群，则需要以下角色：

  • roles/gkehub.gatewayAdmin：此角色可让您访问连接网关 API。如果您只需要对集群的只读权限，则 roles/gkehub.gatewayReader 足矣。

  • roles/gkehub.viewer：此角色允许您检索集群凭据。

如需了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

所需的 Google API

确保舰队宿主项目中启用了所有必需的 Google API。

如果您要使用 gcloud CLI 创建集群，则必须启用 GKE On-Prem API。如果您使用控制台创建集群，则控制台会自动启用 GKE On-Prem API。

gcloud services enable --project FLEET_HOST_PROJECT_ID \
    gkeonprem.googleapis.com

管理员集群前提条件

您必须拥有有效的管理员集群，然后才能创建用户集群。管理员集群必须：

  • 创建 Kubernetes Engine 服务器后，可以访问用户集群上的服务器。

  • 创建用户集群后，与用户集群上的所有节点建立网络连接。

  • 必须向舰队注册。在该管理员集群的 gkeConnect.projectID 字段中配置的项目 ID（称为舰队宿主项目）必须是您将在其中创建用户集群所在的项目。

集群节点机器前提条件

查看集群节点机器前提条件，以确保将运行用户集群的机器满足前提条件。

命令行访问权限

创建集群后，如果要使用连接网关在管理员工作站以外的计算机上对用户集群运行kubectl，请在您打算使用的计算机上安装以下命令行工具。

  • 最新版本的 gcloud CLI。
  • kubectl，用于对 Kubernetes 集群运行命令。如果您需要安装 kubectl，请按照相关instructions操作。

创建用户集群

您可以使用 Terraform、Google Cloud 控制台或 Google Cloud CLI (gcloud CLI) 来创建由 GKE On-Prem API 管理的集群。如果这是您第一次在 Bare Metal 上安装 GKE，您可能会发现控制台是最易用的工具。

在您进一步熟悉创建集群所需的信息后，您可能会发现 Terraform 或 gcloud CLI 更方便，尤其是要创建多个集群的情况下。Terraform 是一个业界标准的基础架构即代码工具。如果您的组织已在使用 Terraform，则您可能需要使用它来创建集群和管理集群生命周期。

如果使用 gcloud CLI，您可以将该命令及其参数保存到文本文件中，并根据需要进行更改，以创建其他集群。如果您使用的是 CI/CD 工具（例如 Cloud Build），则可以使用 gcloud 命令创建集群和节点池，并指定 --impersonate-service-account 标志以自动执行创建操作。

控制台

控制台中的大多数设置都对应于集群配置文件中的字段。

  1. 在控制台中，转到创建 GKE on Bare Metal 集群页面。

    转到“创建 GKE on Bare Metal 集群”

  2. 选择您要供创建集群的 Google Cloud 项目。所选项目也会用作舰队宿主项目。该项目必须是管理员集群注册到的项目。创建用户集群后，它会自动注册到所选项目的舰队。

  3. 点击下一步，开始配置集群。

以下部分将指导您配置用户集群。

集群基本信息

输入有关集群的基本信息。

  1. 输入用户集群的名称。

  2. 在管理员集群下，从列表中选择管理员集群。

  3. 在 Google Cloud API 位置字段中，从列表中选择 Google Cloud 区域。此设置指定运行 GKE On-Prem API 的区域，以及存储以下内容的区域：

    • GKE On-Prem API 管理集群生命周期所需的用户集群元数据
    • 系统组件的 Cloud Logging 和 Cloud Monitoring 数据
    • Cloud Audit Logs 创建的管理员审核日志

    集群名称、项目和位置唯一标识 Google Cloud 中的集群。

  4. 为您的用户集群选择 GKE on Bare Metal 版本。用户集群必须是与管理员集群相同的次要版本或比管理员集群低一个次要版本。

  5. 作为集群创建者，您将获得集群的集群管理员权限。（可选）在管理员用户字段中输入将管理集群的其他用户的电子邮件地址。

    创建集群时，GKE On-Prem API 将 Kubernetes 基于角色的访问控制 (RBAC) 政策应用于集群，以授予您和其他管理用户 Kubernetes clusterrole/cluster-admin 角色，该角色提供对集群中所有名称空间中的每个资源的完全访问权限。

  6. 在节点配置部分中，指定以下内容：

    • 每个节点的最大 Pod 数量：输入可在单个节点上运行的 Pod 数上限。允许的值介于 32 - 250 之间（含边界值）。Kubernetes 会为每个节点分配一个无类别域间路由 (CIDR) 地址块，以便每个 pod 都可以有一个唯一的 IP 地址。CIDR 地址块的大小对应于每个节点的最大 pod 数。如需详细了解如何设置每个节点的最大 pod 数，请参阅 pod 网络。

    • 容器运行时：containerd 是集群唯一可用的容器运行时。

  7. 点击下一步以前往网络部分。

网络

在本部分中，您将指定集群的节点、Pod 和 Service 的 IP 地址。如果您将捆绑式负载均衡与 MetalLB 搭配使用，也需要进行相应的配置。

  1. 在控制平面节点部分中，输入每个控制平面节点的 IPv4 地址。控制平面节点用于运行系统工作负载。 通常，如果使用最简部署，此节点是 1 台机器；如果使用高可用性 (HA) 部署，则是 3 台机器。请指定奇数个节点，以通过多数仲裁实现高可用性。每次更新或升级集群时都可以更改此字段。

    根据需要点击 + 添加 IP 地址以输入更多 IP 地址。

  2. 在负载均衡器部分中，从模式列表中选择要为您的集群设置的负载均衡器。如需了解详情，请参阅负载均衡器概览。

    与 MetalLB 捆绑

    使用捆绑的 MetalLB 负载均衡器配置负载均衡。通过此选项，GKE on Bare Metal 部署第 4 层负载平衡器，这些负载平衡器在工作器节点的专用池或与控制平面相同的节点上运行。

    1. 在负载均衡器节点池部分中，选择以下任一选项：

      • 使用控制平面节点：选择此选项可在控制平面所在的节点上运行负载均衡器。

      • 创建负载均衡器节点池：如果您需要在工作器池上的专用节点池上运行负载均衡器，请选择此高级选项。负载均衡器节点池中的所有节点必须与您在负载均衡器地址池部分中配置的负载均衡器虚拟 IP (VIP) 位于相同的第 2 层子网。

        1. 在负载均衡器节点池 IP 1 字段中，输入负载均衡器节点池中某个节点的 IPv4 地址。

        2. 如需输入额外的 IP 地址，则点击 + 添加 IP 地址。

    2. 在负载均衡器地址池部分中，添加一个或多个地址池，以供 MetalLB 控制器选择并分配给 LoadBalancer 类型的 Service。您在虚拟 IP 部分指定的入站 VIP 必须位于其中一个池中。

      1. 输入地址池的名称。

      2. 以 CIDR 表示法（例如：192.0.2.0/26）或范围表示法（例如：192.0.2.64-192.0.2.72）输入 IP 地址范围。如需指定池中的单个 IP 地址，请使用 CIDR 表示法的 /32，例如 192.0.2.1/32。

      3. 如果入站 VIP 不在地址范围内，请选择 + 添加 IP 地址范围，然后输入另一个包含入站 VIP 的地址范围。

        各个池中的 IP 地址不能重叠，并且必须与集群节点位于同一子网。

      4. 在 IP 地址分配下，选择以下选项之一：

        • 自动：如果您希望 MetalLB 控制器自动将地址池中的 IP 地址分配给 LoadBalancer 类型的 Service，请选择此选项。
        • 手动：如果您打算使用池中的地址手动为 LoadBalancer 类型的 Service 指定地址，请选择此选项。

      5. 如果您希望 MetalLB 控制器不使用池中以 .0 或 .255 结尾的地址，请点击避免使用有问题的 IP 地址。这样可以避免有问题的用户设备错误地丢弃发送到这些特殊 IP 地址的流量。

      6. 完成后，请点击完成。

      7. 如果需要，请点击添加地址池。

    手动负载均衡器

    借助手动负载均衡，您可以为控制平面和数据平面流量配置自己的负载均衡解决方案。您必须先在外部负载均衡器上配置控制平面 VIP，然后才能创建集群。外部控制平面负载均衡器也可用于数据平面流量，您也可以为数据平面设置单独的负载均衡器。如需了解详情，请参阅配置手动负载均衡。

  3. 在虚拟 IP 部分中，输入以下内容：

    • 控制平面 VIP：用于发送到用户集群的 Kubernetes API 服务器的流量的目标 IP 地址。控制平面 VIP 必须与负载均衡器节点位于同一子网中，并且不得位于负载均衡器地址池的任何地址范围内。

    • 端口：用于发送到 Kubernetes API 服务器的流量的目标端口。默认值为 443。

    • Ingress VIP：要在负载均衡器上为 Ingress 代理配置的 IP 地址。输入其中一个负载均衡器地址中的地址。

  4. 在 Service 和 Pod CIDR 部分中，以 CIDR 表示法指定 Kubernetes Service 和 Pod IP 地址范围。范围不得相互重叠，也不得与您要从集群内部访问的任何集群外部地址重叠。我们建议您使用 RFC 1918 定义的专用 IP 地址范围。控制台提供了以下默认地址范围，但您可以进行更改：

    • Service CIDR：10.96.0.0/20 如果不接受默认值，请输入介于 /24 和 /12 之间的 CIDR 范围，其中 /12 提供最多 IP 地址。

    • Pod CIDR：192.168.0.0/16 如果您不接受默认值，请输入介于 /18 到 /8 之间的 CIDR 范围，其中 /8 提供最多 IP 地址。

  5. 在高级特性部分中，视需要指定以下内容：

    • 代理网址：代理服务器的 HTTP 地址。即使端口号与该方案的默认端口相同，也要填写此端口号，例如：http://my-proxy.example.local:80

    • 网址：不应通过代理服务器的 IP 地址、IP 地址范围、主机名和域名的列表（以英文逗号分隔）。当 GKE on Bare Metal 向其中一个地址、主机或网域发送请求时，请求会被直接发送。

  6. 点击下一步。

存储

GKE on Bare Metal 提供块和文件存储接口。它们具有默认选项，但您可以自定义配置。如需了解详情，请参阅配置本地存储。

  1. 您可以选择性地配置以下内容：

    • 本地卷预配工具节点装载：指定由已装载磁盘支持的本地 PersistentVolumes (PV) 的配置。您需要格式化并装载这些磁盘（可以在创建集群之前或之后执行相应操作）。

    • 本地卷预配工具共享：指定共享文件系统中子目录支持的本地 PersistentVolumes 的配置。创建集群时，系统会自动创建这些子目录。

  2. 点击下一步。

特性

为了帮助您监控集群、排查集群问题以及运行集群，以下各项会自动启用且不能停用：

创建节点池

您的集群必须至少有一个节点池来存储工作器节点。节点池是用于在此集群中创建的工作器节点组的模板。

在控制台中，配置至少一个节点池（或接受默认值），然后创建集群。您可以在创建集群后添加其他节点池。使用 gcloud CLI 时，您可以先创建集群，然后将一个或多个节点池添加到新创建的集群。

  1. 点击左侧导航栏中的默认池。

  2. 在节点池默认值部分中，输入节点池名称或接受“default-pool”作为名称。

  3. 在工作器节点部分中，输入运行集群的机器的 IP 地址。

  4. 在节点池元数据（可选）部分中，如果您要添加 Kubernetes 标签和污点，请执行以下操作：

    1. 点击 + 添加 Kubernetes 标签。输入标签的键和值。根据需要重复上述步骤。
    2. 点击 + 添加污点。输入污点的键、值和效果。根据需要重复上述步骤。

  5. 点击验证并完成以创建用户集群。创建用户集群需要 15 分钟或更长时间。控制台会在验证设置并在数据中心内创建集群时显示状态消息。

    如果配置出现问题，控制台将显示一条错误消息，该消息应该足够清晰，以便您修复配置问题并再次尝试创建集群。

gcloud CLI

您可以使用以下命令创建用户集群：

gcloud container bare-metal clusters create

创建集群后，您需要使用以下命令创建至少一个节点池：

gcloud container bare-metal node-pools create

创建集群和节点池的大多数标志都对应于用户集群配置文件中的字段。为帮助您开始使用，您可以在示例部分中测试完整命令。如需了解这些标志，请参阅示例后面的部分，或参阅 gcloud CLI 参考文档。

准备工作

您在创建用户集群时选择的 GKE on Bare Metal 版本必须是管理员集群支持的版本。此外，最新的次要版本或补丁版本在发布后的 7 到 10 天内在 GKE On-Prem API 中不可用。您可以运行 gcloud 命令来获取可在用户集群上安装的受支持版本的列表。

  1. 请务必更新组件：

    gcloud components update

  2. 获取要在用户集群上安装的可用版本列表：

    gcloud container bare-metal clusters query-version-config \
  --admin-cluster-membership=ADMIN_CLUSTER_NAME \
  --admin-cluster-membership-project=FLEET_HOST_PROJECT_ID \
  --admin-cluster-membership-location=global \
  --location=REGION

    替换以下内容：

    • ADMIN_CLUSTER_NAME：管理员集群的名称。

    • FLEET_HOST_PROJECT_ID：管理员集群注册到的项目的 ID。

    • REGION：您在 GKE On-Prem API 中注册集群时指定的 Google Cloud 区域。

我们建议您使用受支持的最高版本来获取最新的修复和改进。

示例

本部分提供了使用 MetalLB 负载均衡器创建集群的命令的示例以及使用手动负载均衡器的示例。您指定的信息因您将使用的负载均衡器类型而异。如需了解详情，请参阅负载均衡器概览。

这些示例创建集群，但不创建任何节点池。集群运行后，您必须先添加节点池，然后才能部署工作负载。

MetalLB

如果需要填写 --admin-cluster-membership 标志的 ADMIN_CLUSTER_NAME 占位符，请务必滚动。

gcloud container bare-metal clusters create USER_CLUSTER_NAME \
  --project=FLEET_HOST_PROJECT_ID \
  --admin-cluster-membership=projects/FLEET_HOST_PROJECT_ID/locations/global/memberships/ADMIN_CLUSTER_NAME \
  --location=REGION \
  --version=VERSION \
  --admin-users=YOUR_EMAIL_ADDRESS \
  --admin-users=ANOTHER_EMAIL_ADDRESS \
  --metal-lb-address-pools='pool=NAME,avoid-buggy-ips=True|False,manual-assign=True|False,addresses=IP_ADDRESS_RANGE_1;IP_ADDRESS_RANGE_2;...' \
  --control-plane-node-configs='node-ip=CP_IP_ADDRESS_1,labels=CP_KEY_1.1=CP_VALUE_1.1;CP_KEY_1.2=CP_VALUE_1.2;...' \
  --control-plane-vip=CONTROL_PLANE_VIP \
  --control-plane-load-balancer-port=CONTROL_PLANE_LB_PORT \
  --ingress-vip=INGRESS_VIP \
  --island-mode-service-address-cidr-blocks=SERVICE_CIDR_BLOCK \
  --island-mode-pod-address-cidr-blocks=POD_CIDR_BLOCK \
  --lvp-share-path=/mnt/localpv-share \
  --lvp-share-storage-class=local-shared \
  --lvp-node-mounts-config-path=/mnt/localpv-disk \
  --lvp-node-mounts-config-storage-class=local-disks

替换以下内容：

  • USER_CLUSTER_NAME：您为用户集群选择的名称。创建集群后，此名称便无法更改。 该名称必须：
    • 最多包含 40 个字符
    • 只能包含小写字母数字字符或连字符 (-)
    • 以字母字符开头
    • 以字母数字字符结尾
  • FLEET_HOST_PROJECT_ID：您要在其中创建集群的项目的 ID。指定的项目也会用作舰队宿主项目。该项目必须是管理员集群注册到的项目。创建用户集群后，它会自动注册到所选项目的舰队。集群创建后，舰队宿主项目便无法更改。
  • ADMIN_CLUSTER_NAME：管理用户集群的管理员集群的名称。在 --admin-cluster-membership 标志中，您可以使用完全指定的集群名称，格式如下： 
        projects/FLEET_HOST_PROJECT_ID/locations/ADMIN_CLUSTER_REGION/memberships/ADMIN_CLUSTER_NAME

    或者，您也可以将 --admin-cluster-membership 设置为管理员集群的名称，如示例命令所示。如果仅使用管理员集群的名称，请使用 --admin-cluster-membership-project 设置管理员集群的项目 ID，使用 --admin-cluster-membership-location 设置位置。管理员集群的位置是 global 或 Google Cloud 区域。如果您需要查找该区域，请运行 gcloud container fleet memberships list。

  • REGION：运行 GKE On-Prem API (gkeonprem.googleapis.com)、舰队服务 (gkehub.googleapis.com) 和 Connect 服务 (gkeconnect.googleapis.com) 的 Google Cloud 区域。请指定 us-west1 或其他受支持的区域。 创建集群后，此区域便无法更改。此设置指定存储以下内容的区域：
    • GKE On-Prem API 管理集群生命周期所需的用户集群元数据
    • 系统组件的 Cloud Logging 和 Cloud Monitoring 数据
    • Cloud Audit Logs 创建的管理员审核日志

    集群名称、项目和位置共同在 Google Cloud 中唯一标识集群。

  • VERSION：用户集群的 GKE on Bare Metal 版本。
  • YOUR_EMAIL_ADDRESS 和 ANOTHER_EMAIL_ADDRESS：如果您没有添加 --admin-users 标志，作为集群创建者，默认情况下您将获得集群管理员权限。但是，如果您添加 --admin-users 以将其他用户指定为管理员，则会替换默认值，并且需要同时添加您的电子邮件地址和另一个管理员的电子邮件地址。例如，如需添加两个管理员：
        --admin-users=sara@example.com \
    --admin-users=amal@example.com

    创建集群时，GKE On-Prem API 会将 Kubernetes 基于角色的访问权限控制 (RBAC) 政策应用于集群，从而向您和其他管理员用户授予 Kubernetes clusterrole/cluster-admin 角色，该角色提供对集群内所有命名空间中所有资源的完整访问权限。

MetalLB 地址池

  • --metal-lb-address-pools：指定 MetalLB 负载均衡器要使用的地址池的配置。该标志的值采用以下格式：
'pool=NAME,avoid-buggy-ips=True|False,manual-assign=True|False,addresses=IP_ADDRESS_RANGE_1;IP_ADDRESS_RANGE_2;...' \

该值的细分以关键字 pool、avoid-buggy-ip、manual-assign 和 addresses 开头；每个细分之间用英文逗号分隔。

  • pool：您为池选择的名称。

  • avoid-buggy-ips：如果将该字段设置为 True，则 MetalLB 控制器不会将以 .0 或 .255 结尾的 IP 地址分配给 Service。这样可以避免有问题的用户设备错误地丢弃发送到这些特殊 IP 地址的流量。如果未指定，则默认为 False。

  • manual-assign：如果您不希望 MetalLB 控制器自动将此池中的 IP 地址分配给 Service，请将该字段设置为 True。之后，开发者便可以创建 LoadBalancer 类型的 Service 并手动指定池中的一个地址。如果未指定，则 manual-assign 设置为 False。

  • 在 addresses 列表中：每个地址都必须是采用 CIDR 或带连字符的范围格式的范围。如需指定池中的单个 IP 地址（例如对于入站流量 VIP 地址），请使用 /32（采用 CIDR 表示法，例如，192.0.2.1/32）。

请注意以下语法规则：

  • 用英文单引号将整个值括起来。
  • 不允许使用空格。
  • 用英文分号分隔每个 IP 地址范围。

您可以指定多个标志实例，如以下示例所示：

--metal-lb-address-pools='pool=pool1,avoid-buggy-ips=False,manual-assign=True,addresses=192.0.2.0/26;192.0.2.64-192.0.2.72'
--metal-lb-address-pools='pool=pool2,avoid-buggy-ips=True,manual-assign=True,addresses=10.251.133.0/24;10.251.134.80/32'

MetalLB 节点

  • （可选）--metal-lb-load-balancer-node-configs：默认情况下，负载均衡器在控制平面所在的节点上运行。如果您需要在专用工作器节点池上运行负载均衡器，请为每个节点指定此标志。负载均衡器节点池中的所有节点都必须与负载均衡器虚拟 IP (VIP) 位于同一个第 2 层子网中。

    该标志的值采用以下格式：

    'node-ip=LB_IP_ADDRESS_1,labels=LB_KEY_1.1=LB_VALUE_1.1;LB_KEY_1.2=LB_VALUE_1.2;...' \

    该值的细分以关键字 node-ip 和 labels 开头；每个细分之间用英文逗号分隔。

    • node-ip：负载均衡器节点池中节点的 IP 地址。您只能为每个标志指定一个 node-ip。如果您需要指定多个节点，请分别为每个节点添加该标志。

    • labels：关联到节点的一个或多个键值对。

    请注意以下语法规则：

    • 用英文单引号将整个值括起来。
    • 不允许使用空格。
    • 使用英文分号分隔 labels 细分中的每个键值对。

    如果您指定了 --metal-lb-load-balancer-node-configs，则可以选择添加以下标志：

    • --metal-lb-load-balancer-node-labels：使用此标志可将标签添加到负载均衡器节点池中的所有节点。使用英文逗号分隔键值对列表。

      --metal-lb-load-balancer-node-labels=KEY_1=VALUE_1,KEY_2=VALUE_2

    • --metal-lb-load-balancer-node-taints：使用此标志可将污点添加到负载均衡器节点池中的所有节点。每个污点都是与相应效果关联的键值对，必须是以下项之一：PreferNoSchedule、NoSchedule 或 NoExecute。

      --metal-lb-load-balancer-node-taints=KEY_1=VALUE_1:EFFECT_1,KEY_2=VALUE_2:EFFECT_2

    以下示例将三个节点添加到负载均衡器节点池。所有节点都带有 lb-pool-key=lb-pool-value 标签，并具有污点 dedicated=experimental:PreferNoSchedule

    --metal-lb-load-balancer-node-configs='node-ip=192.0.2.1' \
--metal-lb-load-balancer-node-configs='node-ip=192.0.2.2,labels=key2.1=value2.1' \
--metal-lb-load-balancer-node-configs='node-ip=192.0.2.3,labels=key3.1=value3.1;key3.2=value3.2' \
--metal-lb-load-balancer-node-labels=lb-pool-key=lb-pool-value \
--metal-lb-load-balancer-node-taints=dedicated=experimental:PreferNoSchedule \

控制平面节点

  • --control-plane-node-configs：控制平面节点的 IPv4 地址。控制平面节点运行系统工作负载。请为每个控制平面节点指定此标志。 通常，如果使用最简部署，则有一台机器；如果使用高可用性 (HA) 部署，则有三台机器。请指定奇数个节点，以通过多数仲裁实现高可用性。您可以在更新或升级集群时更改这些地址。

    该标志的值采用以下格式：

      'node-ip=CP_IP_ADDRESS_1,labels=CP_KEY_1.1=CP_VALUE_1.1;CP_KEY_1.2=CP_VALUE_1.2;...' \

    该值的各部分分别以关键字 node-ip 和 labels 开头。每个细分之间用英文逗号分隔。

  • node-ip：控制平面节点的 IP 地址。您只能为每个标志指定一个 node-ip。如果您需要指定多个节点，请分别为每个节点添加该标志。
  • labels：关联到节点的一个或多个键值对。

    请注意以下语法规则：

    • 用英文单引号将整个值括起来。
    • 不允许使用空格。
    • 使用英文分号分隔 labels 部分中的每个键值对。

    （可选）添加以下标志：

  • --control-plane-node-labels：使用此标志可将标签添加到所有控制平面节点。使用英文逗号分隔键值对列表。 
      --control-plane-node-labels=KEY_1=VALUE_1,KEY_2=VALUE_2
  • --control-plane-node-taints：使用此标志可将污点添加到所有控制平面节点。每个污点都是与相应效果关联的键值对，必须是以下项之一：PreferNoSchedule、NoSchedule 或 NoExecute。

    以下示例将三个节点添加到控制平面节点。所有节点都带有 cp-node-pool-key=cp-node-pool-value 标签，并且具有污点 dedicated=experimental:PreferNoSchedule。

      --control-plane-node-configs='node-ip=192.0.2.1' \
  --control-plane-node-configs='node-ip=192.0.2.2,labels=key2.1=value2.1' \
  --control-planer-node-configs='node-ip=192.0.2.3,labels=key3.1=value3.1;key3.2=value3.2' \
  --control-plane-node-labels=cp-node-pool-key=cp-node-pool-value \
  --control-plane-node-taints=dedicated=experimental:PreferNoSchedule \

虚拟 IP

  • CONTROL_PLANE_VIP：您已选择在负载均衡器上为用户集群的 Kubernetes API 服务器配置的 IP 地址。

    示例：--control-plane-vip=203.0.113.3

  • CONTROL_PLANE_LB_PORT：负载均衡器在此端口上为 Kubernetes API 服务器提供服务。

    示例：-control-plane-load-balancer-port=443

  • INGRESS_VIP：您选择在负载均衡器上为 Ingress 代理配置的 IP 地址。

    示例：--ingress-vip=10.251.134.80

    Ingress VIP 的 IP 地址必须属于某一个 MetalLB 地址池。

服务 CIDR 和 Pod CIDR

  • SERVICE_CIDR_BLOCK：用于集群中 Service 的 IP 地址范围（采用 CIDR 格式）。CIDR 范围必须介于 /24 和 /12 之间，其中 /12 提供的 IP 地址最多。

    示例：--island-mode-service-address-cidr-blocks=10.96.0.0/20

  • POD_CIDR_BLOCK：用于集群中 Pod 的 IP 地址范围（采用 CIDR 格式）。CIDR 范围必须介于 /18 和 /8 之间，其中 /8 提供的 IP 地址最多。

    示例：--island-mode-pod-address-cidr-blocks=192.168.0.0/16

存储空间

  1. --lvp-share-path：宿主机路径，可以在其中创建子目录。系统会为每个子目录创建一个本地 PersistentVolume (PV)。
  2. --lvp-share-storage-class：这是用于创建永久性卷的 StorageClass。StorageClass 在创建集群期间创建。
  3. --lvp-node-mounts-config-path：宿主机路径，可以在其中发现已装载的磁盘。系统会为每个装载创建一个本地 PersistentVolume (PV)。
  4. --lvp-node-mounts-config-storage：在创建集群的过程中创建 PV 所使用的存储类别。

如需详细了解存储，请参阅配置本地存储。

手动

借助手动负载均衡，您可以为控制平面和数据平面流量配置自己的负载均衡解决方案。您必须先在外部负载均衡器上配置控制平面 VIP，然后才能创建集群。外部控制平面负载均衡器也可用于数据平面流量，您也可以为数据平面设置单独的负载均衡器。如需了解详情，请参阅配置手动负载均衡。

如果需要填写 --admin-cluster-membership 标志的 ADMIN_CLUSTER_NAME 占位符，请务必滚动。

gcloud container bare-metal clusters create USER_CLUSTER_NAME \
  --project=FLEET_HOST_PROJECT_ID \
  --admin-cluster-membership=projects/FLEET_HOST_PROJECT_ID/locations/global/memberships/ADMIN_CLUSTER_NAME \
  --location=REGION \
  --version=VERSION \
  --admin-users=YOUR_EMAIL_ADDRESS \
  --admin-users=ANOTHER_EMAIL_ADDRESS \
  --enable-manual-lb \
  --control-plane-node-configs='node-ip=CP_IP_ADDRESS_1,labels=CP_KEY_1.1=CP_VALUE_1.1;CP_KEY_1.2=CP_VALUE_1.2;...' \
  --control-plane-vip=CONTROL_PLANE_VIP \
  --control-plane-load-balancer-port=CONTROL_PLANE_LB_PORT \
  --ingress-vip=INGRESS_VIP \
  --island-mode-service-address-cidr-blocks=SERVICE_CIDR_BLOCK \
  --island-mode-pod-address-cidr-blocks=POD_CIDR_BLOCK \
  --lvp-share-path=/mnt/localpv-share \
  --lvp-share-storage-class=local-shared \
  --lvp-node-mounts-config-path=/mnt/localpv-disk \
  --lvp-node-mounts-config-storage-class=local-disks

替换以下内容：

  • USER_CLUSTER_NAME：您为用户集群选择的名称。创建集群后，此名称便无法更改。 该名称必须：
    • 最多包含 40 个字符
    • 只能包含小写字母数字字符或连字符 (-)
    • 以字母字符开头
    • 以字母数字字符结尾
  • FLEET_HOST_PROJECT_ID：您要在其中创建集群的项目的 ID。指定的项目也会用作舰队宿主项目。该项目必须是管理员集群注册到的项目。创建用户集群后，它会自动注册到所选项目的舰队。集群创建后，舰队宿主项目便无法更改。
  • ADMIN_CLUSTER_NAME：管理用户集群的管理员集群的名称。在 --admin-cluster-membership 标志中，您可以使用完全指定的集群名称，格式如下： 
        projects/FLEET_HOST_PROJECT_ID/locations/ADMIN_CLUSTER_REGION/memberships/ADMIN_CLUSTER_NAME

    或者，您也可以将 --admin-cluster-membership 设置为管理员集群的名称，如示例命令所示。如果仅使用管理员集群的名称，请使用 --admin-cluster-membership-project 设置管理员集群的项目 ID，使用 --admin-cluster-membership-location 设置位置。管理员集群的位置是 global 或 Google Cloud 区域。如果您需要查找该区域，请运行 gcloud container fleet memberships list。

  • REGION：运行 GKE On-Prem API (gkeonprem.googleapis.com)、舰队服务 (gkehub.googleapis.com) 和 Connect 服务 (gkeconnect.googleapis.com) 的 Google Cloud 区域。请指定 us-west1 或其他受支持的区域。 创建集群后，此区域便无法更改。此设置指定存储以下内容的区域：
    • GKE On-Prem API 管理集群生命周期所需的用户集群元数据
    • 系统组件的 Cloud Logging 和 Cloud Monitoring 数据
    • Cloud Audit Logs 创建的管理员审核日志

    集群名称、项目和位置共同在 Google Cloud 中唯一标识集群。

  • VERSION：用户集群的 GKE on Bare Metal 版本。
  • YOUR_EMAIL_ADDRESS 和 ANOTHER_EMAIL_ADDRESS：如果您没有添加 --admin-users 标志，作为集群创建者，默认情况下您将获得集群管理员权限。但是，如果您添加 --admin-users 以将其他用户指定为管理员，则会替换默认值，并且需要同时添加您的电子邮件地址和另一个管理员的电子邮件地址。例如，如需添加两个管理员：
        --admin-users=sara@example.com \
    --admin-users=amal@example.com

    创建集群时，GKE On-Prem API 会将 Kubernetes 基于角色的访问权限控制 (RBAC) 政策应用于集群，从而向您和其他管理员用户授予 Kubernetes clusterrole/cluster-admin 角色，该角色提供对集群内所有命名空间中所有资源的完整访问权限。

控制平面节点

  • --control-plane-node-configs：控制平面节点的 IPv4 地址。控制平面节点运行系统工作负载。请为每个控制平面节点指定此标志。 通常，如果使用最简部署，则有一台机器；如果使用高可用性 (HA) 部署，则有三台机器。请指定奇数个节点，以通过多数仲裁实现高可用性。您可以在更新或升级集群时更改这些地址。

    该标志的值采用以下格式：

      'node-ip=CP_IP_ADDRESS_1,labels=CP_KEY_1.1=CP_VALUE_1.1;CP_KEY_1.2=CP_VALUE_1.2;...' \

    该值的各部分分别以关键字 node-ip 和 labels 开头。每个细分之间用英文逗号分隔。

  • node-ip：控制平面节点的 IP 地址。您只能为每个标志指定一个 node-ip。如果您需要指定多个节点，请分别为每个节点添加该标志。
  • labels：关联到节点的一个或多个键值对。

    请注意以下语法规则：

    • 用英文单引号将整个值括起来。
    • 不允许使用空格。
    • 使用英文分号分隔 labels 部分中的每个键值对。

    （可选）添加以下标志：

  • --control-plane-node-labels：使用此标志可将标签添加到所有控制平面节点。使用英文逗号分隔键值对列表。 
      --control-plane-node-labels=KEY_1=VALUE_1,KEY_2=VALUE_2
  • --control-plane-node-taints：使用此标志可将污点添加到所有控制平面节点。每个污点都是与相应效果关联的键值对，必须是以下项之一：PreferNoSchedule、NoSchedule 或 NoExecute。

    以下示例将三个节点添加到控制平面节点。所有节点都带有 cp-node-pool-key=cp-node-pool-value 标签，并且具有污点 dedicated=experimental:PreferNoSchedule。

      --control-plane-node-configs='node-ip=192.0.2.1' \
  --control-plane-node-configs='node-ip=192.0.2.2,labels=key2.1=value2.1' \
  --control-planer-node-configs='node-ip=192.0.2.3,labels=key3.1=value3.1;key3.2=value3.2' \
  --control-plane-node-labels=cp-node-pool-key=cp-node-pool-value \
  --control-plane-node-taints=dedicated=experimental:PreferNoSchedule \

虚拟 IP

  • CONTROL_PLANE_VIP：您已选择在负载均衡器上为用户集群的 Kubernetes API 服务器配置的 IP 地址。

    示例：--control-plane-vip=203.0.113.3

  • CONTROL_PLANE_LB_PORT：负载均衡器在此端口上为 Kubernetes API 服务器提供服务。

    示例：-control-plane-load-balancer-port=443

  • INGRESS_VIP：您选择在负载均衡器上为 Ingress 代理配置的 IP 地址。

    示例：--ingress-vip=10.251.134.80

    Ingress VIP 的 IP 地址必须属于某一个 MetalLB 地址池。

服务 CIDR 和 Pod CIDR

  • SERVICE_CIDR_BLOCK：用于集群中 Service 的 IP 地址范围（采用 CIDR 格式）。CIDR 范围必须介于 /24 和 /12 之间，其中 /12 提供的 IP 地址最多。

    示例：--island-mode-service-address-cidr-blocks=10.96.0.0/20

  • POD_CIDR_BLOCK：用于集群中 Pod 的 IP 地址范围（采用 CIDR 格式）。CIDR 范围必须介于 /18 和 /8 之间，其中 /8 提供的 IP 地址最多。

    示例：--island-mode-pod-address-cidr-blocks=192.168.0.0/16

存储空间

  1. --lvp-share-path：宿主机路径，可以在其中创建子目录。系统会为每个子目录创建一个本地 PersistentVolume (PV)。
  2. --lvp-share-storage-class：这是用于创建永久性卷的 StorageClass。StorageClass 在创建集群期间创建。
  3. --lvp-node-mounts-config-path：宿主机路径，可以在其中发现已装载的磁盘。系统会为每个装载创建一个本地 PersistentVolume (PV)。
  4. --lvp-node-mounts-config-storage：在创建集群的过程中创建 PV 所使用的存储类别。

如需详细了解存储，请参阅配置本地存储。

在运行 gcloud 命令创建集群之前，您可能需要添加 --validate-only 以验证您在 gcloud 命令的标志中指定的配置。准备好创建集群后，请移除此标志并运行该命令。

创建用户集群需要 15 分钟或更长时间。您可以在 Google Cloud 控制台的 GKE 集群页面上查看该集群。

如需查看标志及其说明的完整列表，请参阅 gcloud CLI 参考文档。

创建节点池

创建集群后，您至少需要创建一个节点池才能部署工作负载。 节点池是用于在此集群中创建的工作器节点组的模板。使用 gcloud CLI 时，您可以先创建集群，然后将一个或多个节点池添加到新创建的集群。

gcloud container bare-metal node-pools create NODE_POOL_NAME \
  --cluster=USER_CLUSTER_NAME \
  --project=FLEET_HOST_PROJECT_ID \
  --location=REGION \
  --node-configs='node-ip=NP_IP_ADDRESS_1,labels=NP_KEY_1.1=NP_VALUE_1.1;NP_KEY_1.2=NP_VALUE_1.2;...'

替换以下内容：

  • NODE_POOL_NAME：您为节点池选择的名称。该名称必须：

    • 最多包含 40 个字符
    • 只能包含小写字母数字字符或连字符 (-)
    • 以字母字符开头
    • 以字母数字字符结尾

  • USER_CLUSTER_NAME：新创建的用户集群的名称。

  • FLEET_HOST_PROJECT_ID：集群在其中注册的项目的 ID。

  • REGION：您在创建集群时指定的 Google Cloud 区域。

  • --node-configs：工作器节点机器的 IPv4 地址。请为每个节点指定此标志。该标志的值采用以下格式：

    'node-ip=NP_IP_ADDRESS_1,labels=NP_KEY_1.1=NP_VALUE_1.1;NP_KEY_1.2=NP_VALUE_1.2;...' \

    该值的细分以关键字 node-ip 和 labels 开头；每个细分之间用英文逗号分隔。

    • node-ip：工作器节点的 IP 地址。您只能为每个标志指定一个 node-ip。请为节点池中的每个节点分别添加此标志。

    • labels：关联到节点的一个或多个键值对。

    请注意以下语法规则：

    • 用英文单引号将整个值括起来。
    • 不允许使用空格。
    • 使用英文分号分隔 labels 细分中的每个键值对。

    您可以选择性地指定以下内容：

    • --node-labels=KEY=VALUE,...：应用于池中每个节点的 Kubernetes 标签（键值对）的英文逗号分隔列表。

    • --node-taints=KEY=VALUE:EFFECT,... 应用于池中每个节点的 Kubernetes 污点的逗号分隔列表。污点是与相应效果关联的键值对。污点用于 Pod 调度的容忍。为 EFFECT 指定以下之一：NoSchedule、PreferNoSchedule、NoExecute。

以下示例在 user-cluster- 上创建名为 default-pool 的节点池，并为该节点池添加两个节点。两个节点都带有 node-pool-key=node-pool-value 标签，并且具有污点 dedicated=experimental:PreferNoSchedule

gcloud container bare-metal node-pools create default-pool \
  --cluster=user-cluster-1  \
  --project=example-project-12345 \
  --location=us-west1 \
  --node-configs='node-ip=10.200.0.10' \
  --node-configs='node-ip=10.200.0.11,labels=key2.1=value2.1' \
  --node-labels=node-pool-key=node-pool-value \
  --node-taints=dedicated=experimental:PreferNoSchedule

如需了解详情，请参阅 gcloud CLI 参考文档。

Terraform

准备工作

您在创建用户集群时选择的 GKE on Bare Metal 版本必须是管理员集群支持的版本。此外，最新的次要版本或补丁版本在发布后的 7 到 10 天内在 GKE On-Prem API 中不可用。您可以运行 gcloud 命令来获取可在用户集群上安装的受支持版本的列表。

  1. 请务必更新组件：

    gcloud components update

  2. 获取要在用户集群上安装的可用版本列表：

    gcloud container bare-metal clusters query-version-config \
  --admin-cluster-membership=ADMIN_CLUSTER_NAME \
  --admin-cluster-membership-project=FLEET_HOST_PROJECT_ID \
  --admin-cluster-membership-location=global \
  --location=REGION

    替换以下内容：

    • ADMIN_CLUSTER_NAME：管理员集群的名称。

    • FLEET_HOST_PROJECT_ID：管理员集群注册到的项目的 ID。

    • REGION：您在 GKE On-Prem API 中注册集群时指定的 Google Cloud 区域。

我们建议您使用受支持的最高版本来获取最新的修复和改进。

示例

您可以使用以下基本配置示例来创建具有捆绑式 MetalLB 负载均衡器的用户集群。如需了解详情，请参阅 google_gkeonprem_bare_metal_cluster 参考文档。

  1. 克隆 anthos-samples 代码库并切换到 Terraform 示例所在的目录：

    git clone https://github.com/GoogleCloudPlatform/anthos-samples
cd anthos-samples/anthos-onprem-terraform/abm_user_cluster_metallb

    该示例提供了一个传入 main.tf 的示例变量文件。

  2. 复制 terraform.tfvars.sample 文件：

    cp terraform.tfvars.sample terraform.tfvars

    
project_id          = "PROJECT_ID"
region              = "ON_PREM_API_REGION"
admin_cluster_name  = "ADMIN_CLUSTER_NAME"
bare_metal_version  = "VERSION"
admin_user_emails   = ["YOUR_EMAIL_ADDRESS", "ADMIN_2_EMAIL_ADDRESS"]
cluster_name        = "abm-user-cluster-metallb"
control_plane_ips   = ["10.200.0.4"]
worker_node_ips     = ["10.200.0.5", "10.200.0.6"]
control_plane_vip   = "10.200.0.50"
ingress_vip         = "10.200.0.51"
lb_address_pools    = [
    { name = "lbpool_1", addresses = ["10.200.0.51-10.200.0.70"] }
]

  3. 修改 terraform.tfvars 中的参数值并保存该文件。

    以下列表介绍了这些变量：

    • project_id：项目 ID，您将在此项目中创建集群。指定的项目也会用作舰队宿主项目。该项目必须是管理员集群注册到的项目。创建用户集群后，它会自动注册到所选项目的舰队。集群创建后，舰队宿主项目便无法更改。

    • region：运行 GKE On-Prem API 的 Google Cloud 区域。请指定 us-west1 或其他受支持的区域。

    • admin_cluster_name：管理用户集群的管理员集群的名称。

    • bare_metal_version：用户集群的 GKE on Bare Metal 版本。指定的版本必须与管理员集群相同，或者最多只能比管理员集群低一个次要版本。

    • cluster_name：您为用户集群选择的名称。创建集群后，此名称便无法更改。该名称必须：

      • 最多包含 40 个字符
      • 只能包含小写字母数字字符或连字符 (-)
      • 以字母字符开头
      • 以字母数字字符结尾

    • control_plane_ips：控制平面节点的一个或多个 IPv4 地址列表。控制平面节点用于运行系统工作负载。通常，如果使用最简部署，则有一台机器；如果使用高可用性 (HA) 部署，则有三台机器。请指定奇数个节点，以通过多数仲裁实现高可用性。您可以在更新或升级集群时更改这些地址。

    • worker_node_ips：工作器节点机器的一个或多个 IPv4 地址列表。

    • control_plane_vip：您已选择在负载均衡器上为用户集群的 Kubernetes API 服务器配置的虚拟 IP 地址 (VIP)。

    • ingress_vip：您已选择在负载均衡器上为 Ingress 代理配置的 IP 地址。

    • lb_address_pools：定义 MetalLB 负载均衡器要使用的地址池的映射列表。Ingress VIP 必须在其中一个池内。

    • admin_user_emails：将被授予集群管理员权限的用户的电子邮件地址列表。如果您打算管理集群，请务必添加您的电子邮件地址。

    创建集群时，GKE On-Prem API 会将 Kubernetes 基于角色的访问权限控制 (RBAC) 政策应用于集群，以便为管理员用户授予 Kubernetes clusterrole/cluster-admin 角色，该角色提供对集群内所有命名空间中所有资源的完整访问权限。此角色还允许用户使用其 Google 身份登录控制台。

  4. 将更改保存在 terraform.tfvars 中。

  5. 初始化并创建 Terraform 方案：

    terraform init

    Terraform 会安装任何所需的库，例如 Google Cloud 提供程序。

  6. 检查配置，并根据需要进行更改：

    terraform plan

  7. 应用 Terraform 方案以创建用户集群：

    terraform apply

    创建用户集群需要 15 分钟或更长时间。您可以在 Google Cloud 控制台的 GKE 集群页面上查看该集群。

连接到用户集群

在控制台中创建用户集群时，系统会为该集群配置 Kubernetes 基于角色的访问权限控制 (RBAC) 政策，以便您可以使用 Google Cloud 身份登录集群。使用 gcloud CLI 创建用户集群时，如果未添加 --admin-users 标志，则默认情况下，系统会为您授予这些 RBAC 政策。如果您添加 --admin-users 以将其他用户指定为管理员，则会替换默认值，并且需要同时添加您的电子邮件地址和另一个管理员的电子邮件地址。如需详细了解所需的 IAM 和 RBAC 政策，请参阅设置 Google 身份验证。

所有集群都有一个规范端点。此端点公开了 kubectl 和其他服务用于通过 TCP 端口 443 与集群控制平面通信的 Kubernetes API 服务器。此端点无法通过公共互联网访问。如果您通过 VPC 访问集群的专用端点，则可以直接连接到专用端点并生成 kubeconfig 文件。否则，您可以使用 Connect 网关。

如需通过命令行访问用户集群，您需要一个 kubeconfig 文件。您可以通过以下两种方法获取 kubeconfig 文件：

  • 使用 Connect 网关从安装了 Google Cloud CLI 的计算机访问集群。在这种情况下，kubectl 使用 Connect 网关的 kubeconfig，它可代表您将流量安全转发到专用端点。

  • 如需直接访问专用端点，请在管理员工作站上创建 kubeconfig 文件并从管理员工作站管理集群。

请务必等到 Google Cloud 控制台指示用户集群状态为健康。

Connect 网关

  1. initialize gcloud CLI 以用于队列宿主项目，或运行以下命令以使用您的 Google 账号登录，将舰队宿主项目设置为默认项目并更新组件：

    gcloud auth login
gcloud config set project PROJECT_ID
gcloud components update

  2. 提取用于与 Connect 网关进行交互的集群凭据。在以下命令中，将 MEMBERSHIP_NAME 替换为您的集群名称。在 GKE on Bare Metal 中，成员资格名称与集群名称相同。

    gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

    此命令会返回一个特殊的特定于 Connect 网关的 kubeconfig，可让您通过网关连接到集群。

获得必要的凭据后，您可以照常使用 kubectl 针对任何 Kubernetes 集群运行命令，并且不需要指定 kubeconfig 文件的名称，例如：

kubectl get namespaces

管理员工作站

使用 bmctl get credentials 命令检索新建的用户集群的 kubeconfig 文件。

bmctl get credentials --cluster CLUSTER_NAME --admin-kubeconfig ADMIN_KUBECONFIG_PATH

替换以下内容：

  • CLUSTER_NAME：目标用户集群的名称。

  • ADMIN_KUBECONFIG_PATH：管理员集群 kubeconfig 文件的路径。

包含用户集群凭据的 kubeconfig 将写入文件 bmctl-workspace/CLUSTER_NAME/CLUSTER_NAME-TIMESTAMP-kubeconfig。文件名中的 TIMESTAMP 表示文件的创建日期和时间。

由于此文件包含集群的身份验证凭据，因此您应该将其存储在具有受限访问权限的安全位置。

后续步骤