使用 GKE 插件进行安装


本页面介绍如何使用 Config Connector 插件在 Google Kubernetes Engine (GKE) 集群上安装 Config Connector。

如果您使用的是 GKE on Google Cloud,我们建议您使用此插件安装 Config Connector。如需详细了解其他安装选项,请参阅选择安装类型

准备工作

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

使用以下任一方法设定默认的 gcloud 设置:

  • 使用 gcloud init(如果您想要在系统引导下完成默认设置)。
  • 使用 gcloud config(如果您想单独设置项目 ID、区域和地区)。

使用 gcloud init

如果您收到 One of [--zone, --region] must be supplied: Please specify location 错误,请完成本部分。

  1. 运行 gcloud init 并按照说明操作:

    gcloud init

    如果您要在远程服务器上使用 SSH,请使用 --console-only 标志来防止命令启动浏览器:

    gcloud init --console-only
  2. 按照说明授权 gcloud 使用您的 Google Cloud 帐号。
  3. 创建新配置或选择现有配置。
  4. 选择 Google Cloud 项目。
  5. 为可用区级集群选择默认 Compute Engine 可用区,或为区域级集群或 Autopilot 集群选择区域。

使用 gcloud config

  • 设置默认项目 ID
    gcloud config set project PROJECT_ID
  • 如果您使用的是可用区级集群,请设置默认计算可用区
    gcloud config set compute/zone COMPUTE_ZONE
  • 如果您使用的是 Autopilot 集群或区域级集群,请设置默认计算区域
    gcloud config set compute/region COMPUTE_REGION
  • gcloud 更新到最新版本:
    gcloud components update

安装 Config Connector 插件

通过创建新 GKE 集群或在现有集群上启用 Config Connector 插件,您就可以使用该插件。安装 Config Connector 插件后,使用 Google 服务帐号和命名空间配置 Config Connector 安装。

要求

Config Connector 插件有以下要求:

设置 GKE 集群

您可以在新集群或现有集群上使用 Config Connector 插件。

创建启用了 Config Connector 插件的新集群

您可以使用 gcloud 工具或 Google Cloud Console 创建 GKE 集群。

gcloud

如需使用 gcloud 命令行工具创建集群,请运行以下命令:

gcloud container clusters create CLUSTER_NAME \
    --release-channel CHANNEL \
    --addons ConfigConnector \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --enable-stackdriver-kubernetes

请替换以下内容:

  • CLUSTER_NAME 替换为您的 GKE 集群的名称。
  • CHANNEL 替换为 GKE 发布渠道,支持 rapidregular
  • PROJECT_ID 替换为 Google Cloud 项目 ID。

Cloud Console

如需使用 Google Cloud Console 创建集群,请执行以下步骤:

  1. 访问 Cloud Console 中的 Google Kubernetes Engine 菜单。

    访问 Google Kubernetes Engine 菜单

  2. 点击创建。此时会显示创建一个 Kubernetes 集群页面。

  3. 为集群指定名称

  4. 选择支持的主版本

  5. 根据需要配置集群的其余部分。

  6. 在导航窗格的集群下,点击安全

  7. 选中启用 Workload Identity 复选框。

  8. 在左侧的导航窗格中,点击集群下的功能

  9. 选中启用 Config Connector 复选框。

  10. 点击创建

创建集群后,请转至创建身份

在现有集群上启用 Config Connector 插件

您可以使用 gcloud 或 Google Cloud Console 在现有 GKE 集群上启用 Config Connector 插件。

前提条件

在现有集群上启用 Config Connector 插件需要满足以下前提条件:

  • 您需要一个满足 Config Connector 插件要求的集群。
  • 在要安装 Config Connector 的集群上设置 Workload Identity

如需为节点池启用 Workload Identity,请使用 gcloud 命令行工具:

gcloud container node-pools update NODE_POOL \
    --workload-metadata=GKE_METADATA \
    --cluster CLUSTER_NAME

请替换以下内容:

  • NODE_POOL 替换为您的节点池的名称
  • CLUSTER_NAME 替换为您的集群的名称
启用 Config Connector 插件

您可以使用 gcloud 命令行工具或 Google Cloud Console 在现有 GKE 集群中启用 Config Connector 插件。

gcloud

如需在现有 GKE 集群中启用 Config Connector 插件,请使用 gcloud 命令行工具:

gcloud container clusters update CLUSTER_NAME \
    --update-addons ConfigConnector=ENABLED

CLUSTER_NAME 替换为 GKE 集群的名称。

Cloud Console

  1. 访问 Cloud Console 中的 Google Kubernetes Engine 菜单。

    访问 Google Kubernetes Engine 菜单

  2. 选择要在其中安装 Config Connector 的集群。此时会显示集群详情页面。

  3. 功能部分下,找到 Config Connector 行,然后点击 修改

  4. 选中启用 Config Connector 复选框,然后点击保存更改以更新您的集群。

创建身份

Config Connector 通过使用 Identity and Access Management (IAM) 服务帐号进行身份验证以及使用 GKE 的 Workload Identity 将 IAM 服务帐号与 Kubernetes 服务帐号绑定来创建和管理 Google Cloud 资源。

如需创建身份,请完成以下步骤:

  1. 创建 IAM 服务帐号。 如果您希望使用现有服务帐号,则可以使用该帐号并跳过此步骤。

    如需创建服务帐号,请使用以下命令:
      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
    SERVICE_ACCOUNT_NAME 替换为您的服务帐号的名称。
  2. 如需详细了解如何创建服务帐号,请参阅创建和管理服务帐号

  3. 向 IAM 服务帐号授予对项目的提升权限:
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/owner"
    替换以下内容:
    • PROJECT_ID 替换为您的项目 ID。
    • SERVICE_ACCOUNT_NAME 替换为您的服务帐号的名称。
  4. 在 IAM 服务帐号与 Config Connector 运行的预定义 Kubernetes 服务帐号之间创建 IAM 政策绑定:
    gcloud iam service-accounts add-iam-policy-binding \
    SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
        --member="serviceAccount:PROJECT_ID.svc.id.goog[cnrm-system/cnrm-controller-manager]" \
        --role="roles/iam.workloadIdentityUser"
    替换以下内容:
    • SERVICE_ACCOUNT_NAME 替换为您的服务帐号的名称。
    • PROJECT_ID 替换为您的项目 ID。

配置 Config Connector

要完成安装,请为 ConfigConnector CustomResource 创建配置文件,然后使用 kubectl apply 命令应用该配置文件。Config Connector Operator 在集群中安装 Google Cloud Resource CRD 和 Config Connector 组件。

要配置 Operator,请完成以下步骤:

  1. 将以下 YAML 文件复制到名为 configconnector.yaml 的文件中:
    # configconnector.yaml
    apiVersion: core.cnrm.cloud.google.com/v1beta1
    kind: ConfigConnector
    metadata:
      # the name is restricted to ensure that there is only one
      # ConfigConnector resource installed in your cluster
      name: configconnector.core.cnrm.cloud.google.com
    spec:
     mode: cluster
     googleServiceAccount: "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"
    
    替换以下内容:
    • SERVICE_ACCOUNT_NAME 替换为您的服务帐号的名称。
    • PROJECT_ID 替换为您的项目 ID。
  2. 使用 kubectl apply 将配置应用到集群:
      kubectl apply -f configconnector.yaml

指定创建资源的位置

Config Connector 可以按项目、文件夹或组织整理资源,这与使用 Google Cloud 整理资源的方式相同。

在使用 Config Connector 创建资源之前,必须先配置创建资源的位置。为了确定创建资源的位置,Config Connector 会在资源配置或现有命名空间中使用注释。如需了解详情,请参阅整理资源

如果您没有可用于此目的的命名空间,请使用 kubectl 创建一个命名空间。
kubectl create namespace NAMESPACE

NAMESPACE 替换为您的命名空间名称。 例如 config-connector

选择一个标签页以便选择 Config Connector 创建资源的位置。

项目

如需在特定项目中创建资源,请运行以下命令:

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/project-id=PROJECT_ID

请替换以下内容:

  • NAMESPACE 替换为您的命名空间名称。
  • PROJECT_ID 替换为 Google Cloud 项目 ID。

Folder

如需在特定文件夹中创建资源,请运行以下命令:

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/folder-id=FOLDER_ID

请替换以下内容:

  • NAMESPACE 替换为您的命名空间名称。
  • FOLDER_ID 替换为您的 Google Cloud 文件夹 ID。

组织

如需在特定组织中创建资源,请运行以下命令:

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/organization-id=ORGANIZATION_ID

请替换以下内容:

  • NAMESPACE 替换为您的命名空间名称。
  • ORGANIZATION_ID 替换为您的 Google Cloud 组织 ID。

为命名空间添加注释时,Config Connector 将在相应的项目、文件夹或组织中创建资源。如需详细了解 Config Connector 如何使用 Kubernetes 命名空间,请参阅 Kubernetes 命名空间和 Google Cloud 项目

验证安装

Config Connector 在命名空间 cnrm-system 中运行其所有组件。您可以通过运行以下命令来验证 Pod 是否准备就绪:

kubectl wait -n cnrm-system \
      --for=condition=Ready pod --all

如果正确安装了 Config Connector,则输出类似于以下内容:

pod/cnrm-controller-manager-0 condition met

升级 Config Connector

Config Connector 插件随 GKE 集群一起升级到新的次要版本。无论何时进行升级,集群中的资源都会保留。

卸载 Config Connector

如需卸载 Config Connector,请完成以下步骤:

  1. 使用 kubectl delete 移除 Config Connector CRD 和控制器组件:

    kubectl delete ConfigConnector configconnector.core.cnrm.cloud.google.com --wait=true
    
  2. 使用 gcloud 工具或 Google Cloud Console 在集群中停用 Config Connector 插件:

    gcloud

    要使用 gcloud 停用 Config Connector 插件,请运行以下命令:

    gcloud container clusters update CLUSTER_NAME --update-addons ConfigConnector=DISABLED
    

    CLUSTER_NAME 替换为安装了 Config Connector 插件的集群的名称。

    Cloud Console

    要从 Google Cloud Console 中停用 Config Connector 插件,请执行以下步骤。

    1. 转到 Google Cloud Console 上的“Google Kubernetes Engine”集群页面,然后选择要更新的集群。

      访问 Google Kubernetes Engine 菜单

    2. 点击修改。系统会显示“修改集群”屏幕。

    3. 点击插件

    4. 选择 Config Connector,然后选择已停用

    5. 点击保存以更新您的集群。

问题排查

以下部分提供有关 Config Connector 安装的问题排查提示。

排查 Config Connector 插件安装问题

如果您无法成功启用 Config Connector 插件,则会显示以下错误消息:Node version 1.15.x-gke.x s unsupported。要解决此错误,请验证 GKE 集群版本是否符合要求。如需获取集群的所有有效版本,请运行以下命令:

gcloud container get-server-config --format "yaml(validMasterVersions)" \
    --zone ZONE

ZONE 替换为 Compute Engine 区域。

从列表中选择符合要求的版本。如果停用 Workload IdentityKubernetes Engine Monitoring,系统也会显示错误消息。请确保启用这些功能,以修复错误。

排查资源协调权限问题

如果 Config Connector 无法成功协调资源,并且日志包含错误消息 The caller does not have permission, forbidden.,则说明您的 GKE 集群和/或节点池可能未启用 Workload Identity。

如需进行调查,请完成以下步骤:

  1. 将以下 Pod 配置保存为 wi-test.yaml
    apiVersion: v1
    kind: Pod
    metadata:
      name: workload-identity-test
      namespace: cnrm-system
    spec:
      containers:
      - image: google/cloud-sdk:slim
        name: workload-identity-test
        command: ["sleep","infinity"]
      serviceAccountName: cnrm-controller-manager
    
  2. 在您的 GKE 集群中创建 Pod:
    kubectl apply -f wi-test.yaml
    
  3. 在 Pod 中打开交互式会话:
    kubectl exec -it workload-identity-test \
      --namespace cnrm-system \
      -- /bin/bash
    
  4. 列出您的身份:
    gcloud auth list
    
  5. 验证列出的身份是否与绑定到您的资源的 Google 服务帐号相匹配。

    如果改为显示 Compute Engine 默认服务帐号,则说明未在 GKE 集群和/或节点池上启用 Workload Identity。

  6. 退出交互式会话,然后从 GKE 集群中删除 Pod:
    kubectl delete pod workload-identity-test \
    --namespace cnrm-system
    

后续步骤