配置 GKE 节点服务账号

Google Kubernetes Engine (GKE) 节点使用 Identity and Access Management (IAM) 服务账号来执行日志记录和为工作负载拉取容器映像等任务。本文档向平台管理员和安全工程师介绍了如何针对特定使用情形向服务账号授予角色，以及如何创建自定义服务账号，而不是使用默认服务账号。如需了解详情，请参阅节点服务账号。

准备工作

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

• 启用 Google Kubernetes Engine API。
启用 Google Kubernetes Engine API
• 如果您要使用 Google Cloud CLI 执行此任务，请安装并初始化 gcloud CLI。 如果您之前安装了 gcloud CLI，请通过运行 gcloud components update 命令来获取最新版本。较早版本的 gcloud CLI 可能不支持运行本文档中的命令。
  注意：对于现有 gcloud CLI 安装，请务必设置 compute/region 属性。如果您主要使用可用区级集群，请改为设置 compute/zone。通过设置默认位置，您可以避免 gcloud CLI 中出现如下错误：One of [--zone, --region] must be supplied: Please specify location。如果集群的位置与您设置的默认位置不同，您可能需要在某些命令中指定位置。

所需的角色

如需获得管理 IAM 服务账号和角色所需的权限，请让管理员向您授予以下 IAM 角色：

• 集群项目的 Security Admin (roles/iam.securityAdmin)
• 在单独的项目中配置服务账号： 服务账号项目的 Security Admin (roles/iam.securityAdmin)

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

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

授予 GKE 所需的最低角色

GKE 使用关联到节点的 IAM 服务账号来运行日志记录和监控等系统任务。这些节点服务账号必须至少拥有项目的 Kubernetes Engine Default Node Service Account (roles/container.defaultNodeServiceAccount) 角色。默认情况下，GKE 会将 Compute Engine 默认服务账号（在您的项目中自动创建）用作节点服务账号。

如果您的组织强制执行 iam.automaticIamGrantsForDefaultServiceAccounts 组织政策限制，则项目中的默认 Compute Engine 服务账号可能无法自动获得 GKE 所需的权限。

注意：如果您的组织是在 2024 年 5 月 3 日或之后创建的，则默认情况下系统会强制执行此限制条件。

以下部分介绍了如何向默认 Compute Engine 服务账号或您创建的新自定义服务账号授予 roles/container.defaultNodeServiceAccount 角色。

最佳实践：

为节点创建自定义服务账号，而不是使用默认的 Compute Engine 服务账号。

配置默认的 Compute Engine 服务账号

如需向 Compute Engine 默认服务账号授予 roles/container.defaultNodeServiceAccount 角色，请完成以下步骤：

控制台

1. 前往欢迎页面：

   前往“欢迎”页面

2. 在项目编号字段中，点击 复制到剪贴板。
3. 转到 IAM 页面：

   转到 IAM

4. 点击 授予访问权限。
5. 在新的主账号字段中，指定以下值：

   [e-mail]

   将 PROJECT_NUMBER 替换为您复制的项目编号。
6. 在选择角色菜单中，选择 Kubernetes Engine Default Node Service Account 角色。
7. 点击保存。

gcloud

1. 找到您的 Google Cloud 项目编号：

   gcloud projects describe PROJECT_ID \
       --format="value(projectNumber)"

   将 PROJECT_ID 替换为您的项目 ID。

   输出内容类似如下：

   12345678901
   

2. 将 roles/container.defaultNodeServiceAccount 角色授予 Compute Engine 默认服务账号：

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:[e-mail]" \
       --role="roles/container.defaultNodeServiceAccount"

   将 PROJECT_NUMBER 替换为上一步中的项目编号。

配置自定义节点服务账号

如需创建自定义服务账号并向其授予 GKE 所需的角色，请完成以下步骤：

控制台

1. 转到服务账号页面：

   转到“服务账号”

2. 点击 创建服务账号。
3. 输入服务账号的名称。 服务账号 ID 字段会根据名称自动生成服务账号的唯一 ID。
4. 点击创建并继续。
5. 在选择角色菜单中，选择 Kubernetes Engine Default Node Service Account 角色。
6. 点击完成。

gcloud

1. 创建服务账号：

   gcloud iam service-accounts create SA_NAME

   将 SA_NAME 替换为可标识服务账号的唯一名称。

2. 向服务账号授予 Kubernetes Engine Default Node Service Account (roles/container.defaultNodeServiceAccount) 角色：

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
       --role=roles/container.defaultNodeServiceAccount

   替换以下内容：

   • PROJECT_ID：您的 Google Cloud 项目 ID。
   • SA_NAME：您创建的服务账号的名称。

Terraform

创建 IAM 服务账号并向其授予项目的 roles/container.defaultNodeServiceAccount 角色：

resource "google_service_account" "default" {
  account_id   = "gke-node-service-account"
  display_name = "GKE node service account"
}

data "google_project" "project" {
}

resource "google_project_iam_member" "default" {
  project = data.google_project.project.project_id
  role    = "roles/container.defaultNodeServiceAccount"
  member  = "serviceAccount:${google_service_account.default.email}"
}

Config Connector

注意：此步骤需要使用 Config Connector。按照安装说明在您的集群上安装配置连接器。

1. 如需创建服务账号，请下载以下资源并将其保存为 service-account.yaml：
   apiVersion: iam.cnrm.cloud.google.com/v1beta1
   kind: IAMServiceAccount
   metadata:
     name: [SA_NAME]
   spec:
     displayName: [DISPLAY_NAME]

   替换以下内容：

   • [SA_NAME]：新服务账号的名称。
   • [DISPLAY_NAME]：服务账号的显示名称。
2. 创建服务账号：

   kubectl apply -f service-account.yaml

3. 将 roles/logging.logWriter 角色应用到服务账号：
   1. 下载以下资源并将其保存为 policy-logging.yaml。
      apiVersion: iam.cnrm.cloud.google.com/v1beta1
      kind: IAMPolicyMember
      metadata:
        name: policy-logging
      spec:
        member: serviceAccount:[SA_NAME]@[PROJECT_ID].iam.gserviceaccount.com
        role: roles/logging.logWriter
        resourceRef:
          kind: Project
          name: [PROJECT_ID]

      替换以下内容：

      • 将 [SA_NAME] 替换为服务账号的名称。
      • [PROJECT_ID]：您的 Google Cloud 项目 ID。
   2. 将角色应用到服务账号：

      kubectl apply -f policy-logging.yaml

4. 将 roles/monitoring.metricWriter 角色应用到服务账号：
   1. 下载以下资源并将其保存为 policy-metrics-writer.yaml。将 [SA_NAME] 和 [PROJECT_ID] 替换为您自己的信息。
      apiVersion: iam.cnrm.cloud.google.com/v1beta1
      kind: IAMPolicyMember
      metadata:
        name: policy-metrics-writer
      spec:
        member: serviceAccount:[SA_NAME]@[PROJECT_ID].iam.gserviceaccount.com
        role: roles/monitoring.metricWriter
        resourceRef:
          kind: Project
          name: [PROJECT_ID]

      替换以下内容：

      • 将 [SA_NAME] 替换为服务账号的名称。
      • [PROJECT_ID]：您的 Google Cloud 项目 ID。
   2. 将角色应用到服务账号：

      kubectl apply -f policy-metrics-writer.yaml

5. 将 roles/monitoring.viewer 角色应用到服务账号：
   1. 下载以下资源并将其保存为 policy-monitoring.yaml。
      apiVersion: iam.cnrm.cloud.google.com/v1beta1
      kind: IAMPolicyMember
      metadata:
        name: policy-monitoring
      spec:
        member: serviceAccount:[SA_NAME]@[PROJECT_ID].iam.gserviceaccount.com
        role: roles/monitoring.viewer
        resourceRef:
          kind: Project
          name: [PROJECT_ID]

      替换以下内容：

      • 将 [SA_NAME] 替换为服务账号的名称。
      • [PROJECT_ID]：您的 Google Cloud 项目 ID。
   2. 将角色应用到服务账号：

      kubectl apply -f policy-monitoring.yaml

6. 将 roles/autoscaling.metricsWriter 角色应用到服务账号：
   1. 下载以下资源并将其保存为 policy-autoscaling-metrics-writer.yaml。
      apiVersion: iam.cnrm.cloud.google.com/v1beta1
      kind: IAMPolicyMember
      metadata:
        name: policy-autoscaling-metrics-writer
      spec:
        member: serviceAccount:[SA_NAME]@[PROJECT_ID].iam.gserviceaccount.com
        role: roles/autoscaling.metricsWriter
        resourceRef:
          kind: Project
          name: [PROJECT_ID]

      替换以下内容：

      • 将 [SA_NAME] 替换为服务账号的名称。
      • [PROJECT_ID]：您的 Google Cloud 项目 ID。
   2. 将角色应用到服务账号：

      kubectl apply -f policy-autoscaling-metrics-writer.yaml

您还可以使用此服务账号处理其他项目中的资源。如需查看相关说明，请参阅跨项目启用服务账号模拟功能。

允许主账号附加自定义服务账号

您可以在创建集群或节点池时附加自定义服务账号。如需允许主账号（例如平台管理员）使用自定义服务账号创建 GKE 资源，请向该主账号授予自定义服务账号的 Service Account User (roles/iam.serviceAccountUser) 角色。如需授予此角色，请选择以下选项之一：

控制台

1. 在 Google Cloud 控制台中，前往服务账号页面：

   转到“服务账号”

   在资源选择器中，选择包含您的自定义服务账号的项目。

2. 选中您创建的要与 GKE 节点搭配使用的自定义服务账号对应的复选框。

3. 点击 管理访问权限。 系统会打开管理访问权限窗格。

4. 点击 添加主账号。 此时会打开授予访问权限窗格。

5. 在新的主账号字段中，指定主账号，例如管理员群组。

6. 在选择角色下拉菜单中，选择服务账号用户角色。

7. 点击保存。授予访问权限窗格随即会关闭。

8. 关闭管理访问权限窗格。

gcloud

授予 roles/iam.serviceAccountUser 角色：

gcloud iam service-accounts add-iam-policy-binding \
    SA_NAME@SERVICE_ACCOUNT_PROJECT_ID.iam.gserviceaccount.com \
    --member=PRINCIPAL \
    --role=roles/iam.serviceAccountUser

替换以下内容：

• SA_NAME：自定义服务账号的名称。
• SERVICE_ACCOUNT_PROJECT_ID：包含自定义服务账号的项目 ID。
• PRINCIPAL：主账号标识符，例如 user:[e-mail]。

Config Connector

注意：此步骤需要使用 Config Connector。按照安装说明在您的集群上安装 Config Connector。

将 iam.serviceAccountUser 角色应用到您的服务账号。下载以下资源并将其保存为 policy-service-account-user.yaml。将 [SA_NAME] 和 [PROJECT_ID] 替换为您自己的信息。

apiVersion: iam.cnrm.cloud.google.com/v1beta1
kind: IAMPolicyMember
metadata:
  name: policy-service-account-user
spec:
  member: serviceAccount:[SA_NAME]@[PROJECT_ID].iam.gserviceaccount.com
  role: roles/iam.serviceAccountUser
  resourceRef:
    kind: Project
    name: [PROJECT_ID]

kubectl apply -f policy-service-account-user.yaml

向服务账号授予角色后，相应的主账号便可以使用该服务账号来创建集群和节点池。如需了解详情，请参阅以下文档：

• 创建 Autopilot 集群
• 创建区域级集群
• 向标准集群添加节点池

配置服务账号跨项目使用

如果节点服务账号与集群不在同一项目中，则集群项目中的服务代理需要对该服务账号拥有额外的权限。如需了解详情，请参阅节点服务账号和项目服务代理。

如需向不在集群项目中的节点服务账号授予所需角色，请按以下步骤操作：

1. 如需启用跨项目服务账号关联，请更新组织政策。

2. 如需向集群项目中的服务代理授予自定义服务账号的所需角色，请选择以下任一选项：

   控制台

   1. 在 Google Cloud 控制台中，打开服务账号页面。

      转到“服务账号”

   2. 选中您创建的要与 GKE 节点搭配使用的自定义服务账号对应的复选框。

   3. 点击 管理访问权限。 系统会打开管理访问权限窗格。

   4. 向集群项目中的 Compute Engine 服务代理授予 Service Account Token Creator 角色：

      1. 在管理访问权限窗格中，点击 添加主账号。 授予访问权限窗格随即会打开。

      2. 在新的主账号字段中，指定集群项目中的 Compute Engine 服务代理的电子邮件地址：

         [e-mail]
         

         将 CLUSTER_PROJECT_NUMBER 替换为集群项目的项目编号。

      3. 在选择角色菜单中，选择 Service Account Token Creator 角色。

      4. 点击保存。授予访问权限窗格随即会关闭。

   5. 向集群项目中的 GKE 服务代理授予 Service Account User 角色：

      1. 在管理访问权限窗格中，点击 添加主账号。 授予访问权限窗格随即会打开。

      2. 在新的主账号字段中，指定集群项目中 GKE 服务代理的电子邮件地址：

         [e-mail]
         

      3. 在选择角色菜单中，选择 Service Account User 角色。

      4. 点击保存。授予访问权限窗格随即会关闭。

   6. 关闭管理访问权限窗格。

   gcloud

   1. 获取集群项目的项目编号：

      gcloud projects describe CLUSTER_PROJECT_ID \
          --format='value(projectNumber)'
      

      将 CLUSTER_PROJECT_ID 替换为集群项目的项目 ID。

      输出类似于 123456789。

   2. 向集群项目中的 Compute Engine 服务代理授予自定义服务账号的 roles/iam.serviceAccountTokenCreator 角色：

      gcloud iam service-accounts add-iam-policy-binding \
          SA_NAME@SERVICE_ACCOUNT_PROJECT_ID.iam.gserviceaccount.com \
          --member=[e-mail] \
          --role=roles/iam.serviceAccountTokenCreator
      

      替换以下内容：

      • SA_NAME：自定义服务账号的名称。
      • SERVICE_ACCOUNT_PROJECT_ID：包含您的自定义服务账号的项目的项目 ID。
      • CLUSTER_PROJECT_NUMBER：集群项目的项目编号。

   3. 向集群项目中的 GKE 服务代理授予对自定义服务账号的 roles/iam.serviceAccountUser 角色：

      gcloud iam service-accounts add-iam-policy-binding \
          SA_NAME@SERVICE_ACCOUNT_PROJECT_ID.iam.gserviceaccount.com \
          --member=[e-mail] \
          --role=roles/iam.serviceAccountUser
      

允许从私有代码库拉取映像

如果您在私有 Artifact Registry 代码库中存储了映像，则必须向节点服务账号授予对这些代码库的访问权限。即使您使用默认的 Compute Engine 服务账号，如果代码库位于其他项目中，您可能也需要向该服务账号授予对代码库的访问权限。

注意： 本部分中的步骤仅向您的节点服务账号授予对相应代码库的访问权限。集群中的工作负载不会获得此访问权限。如需向 GKE 工作负载授予对 Google Cloud 资源的访问权限，请使用 Workload Identity Federation for GKE。

如需从 Artifact Registry 拉取私有映像，请向您的节点服务账号授予代码库的 Artifact Registry Reader 角色 (roles/artifactregistry.reader)。

控制台

1. 在 Google Cloud 控制台中，前往制品库页面。

   前往制品库

2. 选中您的代码库所对应的复选框。

3. 点击显示信息面板。系统会打开代码库信息窗格。

4. 在权限标签页中，点击 添加主账号。系统随即会打开授予访问权限窗格。

5. 在新的主账号字段中，指定节点服务账号的电子邮件地址。

6. 点击选择角色以打开角色选择对话框。

7. 选择 Artifact Registry Reader 角色。

8. 点击保存。

gcloud

授予对代码库的 roles/artifactregistry.reader 角色：

gcloud artifacts repositories add-iam-policy-binding REPOSITORY_NAME \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL \
    --project=REPOSITORY_PROJECT_ID \
    --role=roles/artifactregistry.reader

替换以下内容：

• REPOSITORY_NAME：Artifact Registry 代码库的名称。
• SERVICE_ACCOUNT_EMAIL：节点服务账号的电子邮件地址。
• REPOSITORY_PROJECT_ID：包含代码库的项目的项目 ID。

Config Connector

注意：此步骤需要使用 Config Connector。按照安装说明在您的集群上安装 Config Connector。

注意：这些步骤假定您使用 Config Connector 来管理 Artifact Registry 代码库。如果您的代码库（作为 Config Connector 资源）不存在，则这些步骤将不起作用。

1. 将以下清单保存为 policy-artifact-registry-reader.yaml：

   apiVersion: iam.cnrm.cloud.google.com/v1beta1
   kind: IAMPolicyMember
   metadata:
     name: policy-artifact-registry-reader
   spec:
     member: serviceAccount:"SA_NAME"@"PROJECT_ID".iam.gserviceaccount.com
     role: roles/artifactregistry.reader
     resourceRef:
       apiVersion: artifactregistry.cnrm.cloud.google.com/v1beta1
       kind: ArtifactRegistryRepository
       name: "REPOSITORY_NAME"

   替换以下内容：

   • SA_NAME：您的 IAM 服务账号的名称。
   • PROJECT_ID：您的 Google Cloud 项目 ID。
   • REPOSITORY_NAME：您的 Artifact Registry 代码库的名称。

2. 向服务账号授予 Artifact Registry Reader 角色：

   kubectl apply -f policy-artifact-registry-reader.yaml
   

后续步骤

• 创建 Autopilot 集群
• 创建区域级集群
• 向标准集群添加节点池