向 Config Sync 授予对 Git 代码库的访问权限

本页面介绍了如何向 Helm 代码库验证 Config Sync 的身份。 Config Sync 需要具有可靠来源的只读权限，才能读取您的配置、将其应用于集群并保持同步。

选择身份验证方法

您使用的身份验证方法取决于来源类型支持的方法。

下表总结了可与 Config Sync 搭配使用的身份验证方法：

方法 支持的来源 说明 限制
无身份验证 Git、OCI、Helm 无需额外设置。 仅当可靠来源为公开时才有效。
SSH 密钥对 Git 大多数 Git 提供商都支持此方法。 需要密钥管理。OCI 或 Helm 不支持此方法。
token Git、Helm 大多数 Git 提供商都支持此方法。如果您的组织不允许使用 SSH 密钥，则这是一个很好的替代方案。支持 Helm 的用户名和密码。 需要令牌管理。令牌可能会过期。OCI 不支持此方法。
Kubernetes 服务账号 OCI、Helm 使用 IAM 直接向 Kubernetes 服务账号授予 Artifact Registry 访问权限。需要在集群上启用 Workload Identity Federation for GKE。 Git 不支持此方法。
Google 服务账号 Git 使用 IAM，避免将凭证存储在 Kubernetes Secret 中。建议用于 Secure Source Manager 和 Cloud Source Repositories。需要在集群上启用 Workload Identity Federation for GKE。 需要在集群上安装 Config Sync 之前和之后进行配置。托管在 Secure Source Manager 或 Cloud Source Repositories 之外的代码库不支持此方法。
GitHub 应用 Git 与 GitHub 直接集成。允许精细权限。 仅在 GitHub 中托管的代码库支持此方法。仅在 Config Sync 1.19.1 版及更高版本中受支持。

Config Sync 还支持以下身份验证方法；不过，只有在无法使用上表中列出的选项之一时，才建议使用这些方法：

  • cookiefile：可能并非所有 Git 提供商都支持此选项。OCI 或 Helm 不支持此方法。
  • Compute Engine 默认服务账号 (gcenode)：不建议使用，因为此方法仅在 Workload Identity Federation for GKE 停用时有效。Git、OCI 和 Helm 支持此方法。
  • Helm 和 OCI 的 Google 服务账号：受支持，但不建议使用，因为 Kubernetes 服务账号方法所需的配置较少。

使用舰队软件包进行身份验证

如果您使用舰队软件包，则无需按照本页面上的说明操作。舰队软件包使用 Cloud Build 向 Git 进行身份验证，这意味着您只需为每个项目进行一次身份验证，而无需每次在集群上安装 Config Sync 时都授予访问权限。

准备工作

在向 Config Sync 授予对 Git 代码库的只读权限之前，请完成以下任务：

使用 SSH 密钥对

SSH 密钥对由两个文件组成，即公钥和私钥。 Config Sync 不支持创建口令。您可以对所有集群使用一个密钥对，也可以对每个集群各使用一个密钥对，具体取决于您的安全性和合规性要求。

如需使用 SSH 密钥对向 Config Sync 授予对 Git 代码库的只读权限，请完成以下步骤：

  1. 创建 SSH 密钥对，或让安全管理员提供 SSH 密钥对。 如果您需要创建 SSH 密钥对，请运行以下命令来创建 4096 位 RSA 密钥：

    ssh-keygen -t rsa -b 4096 \
  -C "GIT_REPOSITORY_USERNAME" \
  -N '' \
  -f /path/to/KEYPAIR_FILENAME

    替换以下内容：

    • GIT_REPOSITORY_USERNAME：您希望 Config Sync 用于向代码库进行身份验证的用户名。如果您使用的是第三方 Git 代码库主机（如 GitHub），或者想要将服务账号用于 Secure Source Manager，我们建议您使用单独的账号进行身份验证。
    • /path/to/KEYPAIR_FILENAME：密钥对文件的路径。

  2. 配置您的代码库以识别新创建的公钥。 请参阅 Git 托管服务提供商的文档。您可以在以下列表中找到一些常用 Git 托管服务提供商的说明：

  3. 使用私钥创建 git-creds Secret：

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-file=ssh=/path/to/KEYPAIR_PRIVATE_KEY_FILENAME

    将 /path/to/KEYPAIR_PRIVATE_KEY_FILENAME 替换为私钥的名称。

  4. 可选，但建议执行：如需在使用 SSH 身份验证时配置已知主机检查，请将已知主机密钥添加到 git_creds Secret 中的 data.known_hosts 字段。

    1. 如需添加已知主机密钥，请运行以下命令：

      kubectl edit secret git-creds --namespace=config-management-system

    2. 如需在 data 下添加 known_hosts 条目，请运行以下命令：

        known_hosts: KNOWN_HOSTS_KEY

      将 KNOWN_HOSTS_KEY 替换为已知主机密钥。

    如需停用 known_hosts 检查，请从 Secret 中移除 known_hosts 字段。

安装 Config Sync 时，请使用 SSH 密钥对 (ssh) 作为身份验证类型。

输入 Git 代码库的网址时，该网址必须采用 SSH 协议格式。 网址的格式因 Git 提供商而异。

使用 cookiefile

获取 cookiefile 的过程取决于您代码库的配置。一般来说，凭证存储在主目录下的 .gitcookies 文件中，或者由安全管理员提供。

如需使用 cookiefile 向 Config Sync 授予对 Git 代码库的只读权限，请完成以下步骤：

创建并获取 cookiefile 后，将其添加到集群的新 Secret 中。出于安全考虑，我们建议您使用 HTTPS：

kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace=config-management-system \
  --from-file=cookie_file=/path/to/COOKIEFILE

将 /path/to/COOKIEFILE 替换为您的路径和文件名。

安装 Config Sync 时，请使用 cookiefile (cookiefile) 作为身份验证类型。

使用令牌

如果您的组织不允许使用 SSH 密钥，您可能更倾向于使用令牌。

如需使用令牌向 Config Sync 授予对 Git 代码库的只读权限，请完成以下步骤：

  1. 从 Git 提供商处生成令牌。如需查看相关说明，请参阅 Git 托管服务提供商的文档。您可以在以下列表中找到一些常用 Git 托管服务提供商的说明：

  2. 创建或获取令牌后，将其添加到集群的新 Secret 中。出于安全考虑，我们建议您使用 HTTPS：

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace=config-management-system \
  --from-literal=username=USERNAME \
  --from-literal=token=TOKEN

    替换以下内容：

    • USERNAME：您要使用的用户名。
    • TOKEN：您在上一步中创建的令牌。

安装 Config Sync 时，请使用令牌 (token) 作为身份验证类型。

使用 Google 服务账号

您可以使用 Google 服务账号向 Config Sync 授予对托管式集群所在项目中的代码库的访问权限。您必须满足以下要求：

如需使用 Google 服务账号向 Config Sync 授予对 Git 代码库的只读权限，请完成以下步骤：

  1. 如需获得创建政策绑定所需的权限，请让您的管理员为您授予服务账号的 Service Account Admin (roles/iam.serviceAccountAdmin) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

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

  2. 如果您还没有服务账号，请创建一个服务账号。

  3. 根据您使用的代码库类型，向 Google 服务账号授予 IAM 角色：

    Secure Source Manager

    向 Google 服务账号授予 Secure Source Manager Instance Accessor (roles/securesourcemanager.instanceAccessor) 和 Secure Source Manager Repo Reader (roles/securesourcemanager.repoReader) IAM 角色：

    • 如果项目中的所有代码库都应用相同的权限，请授予项目范围的权限：

      gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/securesourcemanager.instanceAccessor \
  --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

      gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/securesourcemanager.repoReader \
  --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

      替换以下内容：

      • PROJECT_ID：您的项目 ID。
      • GSA_NAME：您要连接到 Secure Source Manager 的 Google 服务账号的名称。

    • 如需授予代码库特有的权限，请参阅 Secure Source Manager 文档中的向用户授予代码库级角色。

    安装 Config Sync 时，请使用 Workload Identity (gcpserviceaccount) 作为身份验证类型。您还必须添加服务账号邮箱。

    Secure Source Manager 要求代码库网址采用特定格式：https://SSM_INSTANCE_ID-PROJECT_NUMBER-git.INSTANCE_LOCATION.sourcemanager.dev/PROJECT_ID/REPO_NAME.git。

    Cloud Source Repositories

    向 Google 服务账号授予 Cloud Source Repositories Reader (roles/source.reader) IAM 角色：

    • 如果项目中的所有代码库都应用相同的权限，请授予项目范围的权限：

      gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

      替换以下内容：

      • PROJECT_ID：您的项目 ID。
      • GSA_NAME：您要连接到 Cloud Source Repositories 的 Google 服务账号的名称。

    • 如果您希望服务账号对项目中的每个代码库拥有不同级别的访问权限，请授予代码库特有的权限：

      gcloud source repos set-iam-policy REPOSITORY POLICY_FILE --project=PROJECT_ID

      替换以下内容：

      • PROJECT_ID：您的项目 ID。
      • REPOSITORY：代码库的名称。
      • POLICY_FILE：包含 Identity and Access Management 政策的 JSON 或 YAML 文件。

    安装 Config Sync 时，请使用 Workload Identity (gcpserviceaccount) 作为身份验证类型。 您还必须添加服务账号邮箱。

必须在配置 Config Sync 之后完成以下步骤，因为在您首次配置 Config Sync 之前，系统不会创建 Kubernetes 服务账号。您只需为每个舰队执行一次此操作。 如需创建绑定以允许 Kubernetes 服务账号充当 Google 服务账号，请运行以下命令：

gcloud iam service-accounts add-iam-policy-binding \
    GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.workloadIdentityUser \
    --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
    --project=PROJECT_ID

替换以下内容：

  • FLEET_HOST_PROJECT_ID：如果您使用的是 Workload Identity Federation for GKE，则此值与 PROJECT_ID 相同。如果您使用的是舰队 Workload Identity Federation for GKE，请使用集群注册到的舰队的项目 ID 作为值。
  • GSA_NAME：您要用于连接到 Secure Source Manager 或 Cloud Source Repositories 的自定义 Google 服务账号。
  • KSA_NAME：协调器的 Kubernetes 服务账号。 在大多数情况下，该值为 root-sync，因为使用 Google Cloud 控制台或 Google Cloud CLI 安装 Config Sync 时，Config Sync 会自动创建一个名为 root-sync 的 RootSync 对象。 否则，使用 root-reconciler-ROOT_SYNC_NAME 作为值。

如果您在使用 Google 服务账号连接到 Config Sync 时遇到问题，请参阅排查 Google 服务账号的权限问题。

使用 Compute Engine 默认服务账号

如果您未启用 Workload Identity Federation for GKE，则除了 Google 服务账号，还可以使用 Compute Engine 服务账号进行身份验证。只有 Secure Source Manager 和 Cloud Source Repositories 中的代码库支持此方法。

如需使用 Compute Engine 默认服务账号向 Config Sync 授予对代码库的只读权限，请向该默认服务账号授予 roles/source.reader 角色：

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com"

替换以下内容：

  • PROJECT_ID：您的项目 ID
  • PROJECT_NUMBER：您的项目编号。

安装 Config Sync 时，请使用 Google Cloud Repository (gcenode) 作为身份验证类型。

使用 GitHub 应用

如果您的代码库位于 GitHub 中，您可以使用 GitHub 应用将代码库连接到 Config Sync：

  1. 按照 GitHub 上的说明预配 GitHub 应用，并向其授予从您的代码库读取数据的权限。

  2. 使用客户端 ID 或应用 ID 将 GitHub 应用配置添加到集群的的新 Secret 中：

    客户端 ID 

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace=config-management-system \
  --from-literal=github-app-client-id=CLIENT_ID \
  --from-literal=github-app-installation-id=INSTALLATION_ID \
  --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
  --from-literal=github-app-base-url=BASE_URL
    • 将 CLIENT_ID 替换为 GitHub 应用的客户端 ID。
    • 将 INSTALLATION_ID 替换为 GitHub 应用的安装 ID。
    • 将 /path/to/GITHUB_PRIVATE_KEY 替换为包含私钥的文件的名称。
    • 将 BASE_URL 替换为 GitHub API 端点的基础网址。仅当代码库未托管在 www.github.com 时才需要此值。否则，可以省略此参数，使其默认为 https://api.github.com/。

    应用 ID 

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-literal=github-app-application-id=APPLICATION_ID \
    --from-literal=github-app-installation-id=INSTALLATION_ID \
    --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
    --from-literal=github-app-base-url=BASE_URL
    • 将 APPLICATION_ID 替换为 GitHub 应用的应用 ID。
    • 将 INSTALLATION_ID 替换为 GitHub 应用的安装 ID。
    • 将 /path/to/GITHUB_PRIVATE_KEY 替换为包含私钥的文件的名称。
    • 将 BASE_URL 替换为 GitHub API 端点的基础网址。仅当代码库未托管在 www.github.com 时才需要此值。否则，可以省略此参数，使其默认为 https://api.github.com/。

安装 Config Sync 时，请使用 GitHub 应用 (githubapp) 作为身份验证类型。

问题排查

如需帮助排查与将 Config Sync 连接到可靠来源相关的问题，请查看以下问题排查主题：

后续步骤