创建和管理集群和节点池标签

本页面简要介绍 Google Kubernetes Engine (GKE) 中的集群标签和节点池标签。

GKE 集群和节点池标签以及 Kubernetes 标签

GKE 集群和节点池标签与 Kubernetes 中的标签有所不同。这两个标签系统独立工作，不继承或共享标签。

GKE 集群和节点池标签是附加到您的资源的任意元数据，可用于跟踪使用情况和结算信息。

在 Kubernetes 中，系统分别在内部使用标签将集群组件和资源（例如 Pod 和节点）彼此关联并管理资源生命周期。您可以使用 Kubernetes API 修改 Kubernetes 标签。您还可以使用 GKE API 通过集群创建或集群更新修改节点上的 Kubernetes 标签。

什么是集群标签？

集群标签是可以分配给 Google Cloud 集群的键值对。它们可帮助您以所需的粒度组织这些资源并大规模管理费用。您可以将标签附加到各项资源，然后根据其标签对资源进行过滤。标签的相关信息会转发到结算系统，以便您按标签细分结算费用。使用内置的结算报告，您可以按资源标签对费用进行过滤和分组。您还可以使用标签来查询结算数据导出。

集群标签的要求

应用于资源的集群标签必须符合以下要求：

每个资源最多可以有 64 个集群标签。
每个集群标签都必须采用键值对形式。
键至少有 1 个字符，最多有 63 个字符，且不能为空。值可以为空，且最多包含 63 个字符。
键和值只能包含小写字母、数字字符、下划线和短划线。所有字符必须使用 UTF-8 编码，允许使用国际字符。键必须以小写字母或国际字符开头。
集群标签的键部分在单个资源内必须是唯一的。不过，您可以将同一个键用于多个资源。

这些限制适用于每个集群标签的键和值，以及带有集群标签的各个 Google Cloud 资源。您可以对一个项目的所有资源应用任意数量的集群标签。

集群标签的常见用途

以下是集群标签的一些常见使用场景：

团队或成本中心集群标签：根据团队或成本中心添加标签，以区分不同团队（例如 team:research 和 team:analytics）所拥有的集群。您可以在进行成本核算或预算时使用此类标签。
组件集群标签：例如 component:redis、component:frontend、component:ingest、component:dashboard。
环境或阶段集群标签：例如 environment:production 和 environment:test。
状态集群标签：例如 state:active、state:readytodelete、state:archive。
所有权集群标签：用于标识负责运营的团队，例如 team:shopping-cart。

结算明细：使用节点池标签按节点池细分结算费用。如需了解详情，请参阅查看集群费用明细。

我们不建议创建大量唯一标签，例如为每个 API 调用的时间戳或个别值创建标签。这种方法的问题在于，当值经常变化或键导致目录杂乱时，很难有效地过滤和报告资源。

标签和标记

标签可用作资源可查询的注释，但不能用于设置政策的条件。通过对政策进行精细控制，标记提供了一种有条件地允许或拒绝政策的方法，具体取决于资源是否具有特定的标记。如需了解详情，请参阅标记概览。

自动应用的标签

GKE 会自动将多个标签应用于集群资源。

例如，GKE 会将标签应用于 Compute Engine 实例、永久性磁盘和加速器 (TPU)。

下表列出了 GKE 自动应用于资源的标签：

标签	应用的资源
`goog-gke-node`	GKE 节点底层的 Compute Engine 虚拟机实例。
`goog-gke-volume`	挂接到 GKE 节点底层的虚拟机实例的 Compute Engine 永久性磁盘。
`goog-gke-tpu`	GKE 上的 Cloud TPU。
`goog-k8s-cluster-name`	Compute Engine 虚拟机实例和挂接到 GKE 节点底层的虚拟机实例的永久性磁盘。
`goog-k8s-cluster-location`	Compute Engine 虚拟机实例和挂接到 GKE 节点底层的虚拟机实例的永久性磁盘。
`goog-k8s-node-pool-name`	Compute Engine 虚拟机实例及其在 GKE 节点下的启动磁盘。
`goog-fleet-project`	Compute Engine 虚拟机实例和挂接到 GKE 节点底层的虚拟机实例的永久性磁盘（如果已向舰队注册集群）。

请勿修改或删除预留的标签。您对预留的标签所做的任何更改都会被系统自动协调。

标签传播

在 GKE 中，您可以将标签应用于集群和标准模式节点池。为集群添加标签后，标签会传播到集群的所有资源，例如各个节点、实例和永久性磁盘。为节点池添加标签后，标签会传播到节点池的所有资源，例如各个实例和永久性磁盘。在标准集群中，如果集群标签与节点池标签冲突（例如，标签键相同但值不同），节点池标签会覆盖集群标签。

您应用于集群或节点池的任何标签都会通过每小时运行一次的后台进程进行传播。标签最多可能需要 1 小时才能显示在与给定集群关联的所有资源上。此外，标签仅会传播到 Compute Engine 实例和挂接到 Compute Engine 实例的永久性磁盘。系统不会为工作负载、转发规则、IP 地址和未挂接的永久性磁盘等其他资源添加标签。

对于 Standard 集群，在将集群和节点池标签应用于 Compute Engine 资源时，您可以手动更改资源标签，而无需由 GKE 协调这些更改。在 Autopilot 集群中，您无法手动修改 Compute Engine 资源上的标签，因为 GKE 会为您管理节点。但是，我们建议通过 GKE 管理这些标签。GKE 不会移除这些 Compute Engine 资源上的现有标签，除非它们与自动应用的标签冲突。

准备工作

在开始之前，请确保您已执行以下任务：

启用 Google Kubernetes Engine API。

启用 Google Kubernetes Engine API

如果您要使用 Google Cloud CLI 执行此任务，请安装并初始化 gcloud CLI。如果您之前安装了 gcloud CLI，请运行 gcloud components update 以获取最新版本。
注意：对于现有 gcloud CLI 安装，请务必设置 compute/region 和 compute/zone 属性。通过设置默认位置，您可以避免 gcloud CLI 中出现以下错误：One of [--zone, --region] must be supplied: Please specify location。

获取 API 请求的标签指纹

如果您使用 Google Cloud 控制台或 gcloud CLI，则可以跳过此步骤。

使用 GKE API 更新或添加集群标签时，您必须在请求中提供最新的集群标签指纹，以防止与其他请求发生任何冲突。

如需获取最新的集群标签指纹，请对相应集群运行 GET 请求。例如：

GET https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster

输出类似于以下内容：

200 OK

{

 "name": "mycluster",
 "description": "production-cluster",
 "initialNodeCount": 3,
 ...
 "resourceLabels": {
    "environment": "production",
    ...
  },
  "labelFingerprint": "p1ty_9HoBk0="
}

在此输出中，labelFingerprint 属性是集群标签指纹。

创建带标签的集群

您可以使用 gcloud CLI、Google Cloud 控制台、GKE API 或 Terraform 创建带标签的 Autopilot 和 Standard 集群。

gcloud

运行以下命令以创建带有标签的 Autopilot 集群：

gcloud container clusters create-auto CLUSTER_NAME \
    --labels=KEY=VALUE

或者，运行以下命令以创建带有标签的标准集群：

gcloud container clusters create CLUSTER_NAME \
    --labels=KEY=VALUE

替换以下内容：

CLUSTER_NAME：集群的名称。
KEY：标签键值对的键。
VALUE：标签的键值对值。

控制台

如需在创建集群时添加标签，请执行以下操作：

转到 Google Cloud 控制台中的 Google Kubernetes Engine 页面。

转到 Google Kubernetes Engine
点击创建。
对于 Autopilot 或 Standard，点击配置。
配置集群。
在导航窗格的集群下，点击元数据。
点击 添加标签。
添加标签。
点击创建。

API

如需在创建集群时添加标签，请在为 projects.zones.clusters.create 提供的 cluster 对象中指定 resourceLabels 对象。

Terraform

如需使用 Terraform 创建带标签的 Autopilot 集群，请参阅以下示例：

resource "google_container_cluster" "default" {
  name     = "gke-autopilot-labels"
  location = "us-central1"

  enable_autopilot = true

  resource_labels = {
    foo = "bar"
  }

  # Set `deletion_protection` to `true` will ensure that one cannot
  # accidentally delete this instance by use of Terraform.
  deletion_protection = false
}

如需使用 Terraform 创建带标签的 Standard 集群，请参阅以下示例：

resource "google_container_cluster" "default" {
  name               = "gke-standard-regional-labels"
  location           = "us-west1"
  initial_node_count = 2

  resource_labels = {
    foo = "bar"
  }

  # Set `deletion_protection` to `true` will ensure that one cannot
  # accidentally delete this instance by use of Terraform.
  deletion_protection = false
}

如需详细了解如何使用 Terraform，请参阅针对 GKE 的 Terraform 支持。

为现有集群添加或更新标签

您可以使用 gcloud CLI、Google Cloud 控制台或 GKE API 为现有 Autopilot 和标准集群添加或更新标签。

gcloud

运行以下命令：

gcloud container clusters update CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --update-labels=KEY=VALUE

替换以下内容：

CLUSTER_NAME：您的集群的名称。
COMPUTE_REGION：新集群的 Compute Engine 区域。对于可用区级 Standard 集群，请使用 --zone=COMPUTE_ZONE。
KEY：标签键值对的键。
VALUE：标签的键值对值。

更新的标签会覆盖集群上的所有现有标签。如果集群具有您要保留的现有标签，您必须包含这些标签以及要添加的任何新标签。

控制台

如需添加或更新标签，请执行以下操作：

转到 Google Cloud 控制台中的 Google Kubernetes Engine 页面。

转到 Google Kubernetes Engine
在集群详情页面上，选中要修改的一个或多个集群对应的复选框。
点击标签。
添加或更新标签。
点击保存。

API

使用最新的指纹和要应用的完整标签列表向集群的 resourceLabels 方法发出 POST 请求。

与元数据和标记类似，如果集群具有您想要保留的现有标签，则必须在请求中添加这些标签以及要添加的任何新标签。

例如，以下代码段向 resourceLabels 方法发出请求：

POST https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster/resourceLabels

{
 "resourceLabels": {
  "environment": "production",
  "an-existing-tag": ""
 },
 "labelFingerprint": "42WmSpB8rSM="
}

移除集群标签

您可以使用 gcloud CLI、Google Cloud 控制台或 GKE API 从 Autopilot 和标准集群中移除标签。

gcloud

运行带有 --remove-labels 标志的 update 命令：

gcloud container clusters update CLUSTER_NAME \
    --remove-labels=KEYS

请替换以下内容：

CLUSTER_NAME：集群的名称。
KEYS：要移除的标签的键列表（以英文逗号分隔）。

控制台

如需移除标签，请执行以下操作：

转到 Google Cloud 控制台中的 Google Kubernetes Engine 页面。

转到 Google Kubernetes Engine
在集群列表中，选中要修改的一个或多个集群对应的复选框。
点击标签。
点击要删除的标签的值字段旁的 删除项。
点击保存。

API

向相应集群的 resourceLabels 方法发出 POST 请求。提供当前的 labelsFingerprint 和一个空的标签列表以移除所有标签，或提供您要保留的标签列表（去掉您要移除的标签）。例如：

Request

POST https://container.googleapis.com/v1/projects/myproject/zones/us-central1-f/clusters/example-cluster/resourceLabels

{
 "resourceLabels": { },
 "labelFingerprint": "42WmSpB8rSM="
}

创建带标签的标准节点池

您可以使用 gcloud CLI、Google Cloud 控制台或 GKE API 在标准集群中创建带有标签的节点池。

gcloud

运行以下命令：

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

请替换以下内容：

NODE_POOL_NAME：节点池的名称。
CLUSTER_NAME：集群的名称。
COMPUTE_REGION：集群的 Compute Engine 区域。对于可用区级集群，请使用 --zone=COMPUTE_ZONE。
KEY：标签键值对的键。
VALUE：标签的键值对值。

API

如需在创建节点池时添加标签，请在您提供给 projects.zones.clusters.nodePools.create 的节点池对象中指定 resourceLabels 对象。

控制台

如需向新节点池添加标签，请执行以下操作：

转到 Google Cloud 控制台中的 Google Kubernetes Engine 页面。

转到 Google Kubernetes Engine
在集群详情页面上，点击要修改的集群的名称。
点击 添加节点池。
配置新节点池。
在导航窗格中，点击元数据。
点击 添加标签。
添加标签。
点击创建。

添加或更新现有节点池的标签

您可以使用 gcloud CLI、Google Cloud 控制台或 GKE API 为现有节点池添加或更新标签。

gcloud

运行以下命令：

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

请替换以下内容：

NODE_POOL_NAME：节点池的名称。
CLUSTER_NAME：集群的名称。
COMPUTE_REGION：集群的 Compute Engine 区域。对于可用区级集群，请使用 --zone=COMPUTE_ZONE。
KEY：标签键值对的键。
VALUE：标签的键值对值。

标签更新会覆盖节点池上的任何现有标签。如果节点池具有您要保留的现有标签，您必须包含这些标签以及要添加的任何新标签。

API

如需在修改节点池时添加标签，请在您提供给 projects.zones.clusters.nodePools.update 的节点池对象中指定 resourceLabels 对象。

控制台

如需添加或更新标签，请执行以下操作：

转到 Google Cloud 控制台中的 Google Kubernetes Engine 页面。

转到 Google Kubernetes Engine
在集群列表中，点击您要修改的节点池的集群名称。
在节点池部分中，点击要修改的节点池的名称。
点击修改
在标签部分中，添加或更新标签。
点击保存。

移除节点池标签

您可以使用 gcloud CLI、Google Cloud 控制台或 GKE API 从节点池中移除标签。

gcloud

运行以下命令：

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --labels=KEY=VALUE

请替换以下内容：

NODE_POOL_NAME：节点池的名称。
CLUSTER_NAME：集群的名称。
COMPUTE_REGION：集群的 Compute Engine 区域。对于可用区级集群，请使用 --zone=COMPUTE_ZONE。
KEY：标签键值对的键。
VALUE：标签的键值对值。

标签更新会覆盖节点池上的任何现有标签。如果节点池已有要保留的标签，则必须排除要移除的任何标签。如果您要移除所有标签，请使用 --labels=（不带键值对）。

API

如需在修改节点池时添加标签，请在您提供给 projects.zones.clusters.nodePools.update 的节点池对象中指定 resourceLabels 对象。提供一个空的标签列表以移除所有标签，或提供您要保留的标签列表。省略要移除的标签。

控制台

如需从节点池中移除标签，请执行以下操作：

转到 Google Cloud 控制台中的 Google Kubernetes Engine 页面。

转到 Google Kubernetes Engine
在集群列表中，点击您要修改的节点池的集群名称。
在节点池部分中，点击要修改的节点池的名称。
点击要删除的标签的值字段旁的 删除项。
点击保存。

后续步骤

阅读 GKE 概览。