此页面由 Cloud Translation API 翻译。

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

本页面介绍如何对 Config Sync 进行身份验证，以访问您的 Git 代码库。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)：不建议使用，因为此方法仅在停用适用于 GKE 的工作负载身份联合时有效。支持 Git、OCI 和 Helm。
Helm 和 OCI 的 Google 服务账号：受支持，但不建议使用，因为 Kubernetes 服务账号方法所需的配置更少。

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

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

准备工作

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

准备或有权访问一个 Git 代码库，您可以在其中存储希望 Config Sync 同步的配置文件。如需了解详情，请参阅以下资源：
- 将配置添加到可靠来源：有关配置的概念性信息。
- GitOps 最佳实践：有关组织和管理代码库的提示和一般最佳实践。
- 使用非结构化代码库：有关使用和组织非结构化代码库的建议。
创建或有权访问 GKE 集群。在创建集群之前，请查看 Config Sync 的集群配置要求和建议。

使用 SSH 密钥对

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

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

创建 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：密钥对文件的路径。
配置您的代码库以识别新创建的公钥。请参阅 Git 托管服务提供商的文档。您可以在以下列表中找到一些常用 Git 托管服务提供商的说明：

使用私钥创建 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 替换为私钥的名称。

可选，但建议执行：如需在使用 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 代码库的只读权限，请完成以下步骤：

从 Git 提供商处生成令牌。如需了解相关说明，请参阅 Git 托管服务提供商的文档。您可以在以下列表中找到一些常用 Git 托管服务提供商的说明：
- GitHub：创建 PAT。向令牌授予 repo 范围，以便其可以从私有代码库中读取内容。由于您将 PAT 绑定到 GitHub 账号，因此我们还建议您创建机器用户并将 PAT 绑定到该机器用户。
- GitLab：创建 PAT 或创建部署令牌。
- Bitbucket：创建应用专用密码。
创建或获取令牌后，将其添加到集群的新 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
```
注意：如果您需要使用代理，请传递 --from-literal=https_proxy=HTTPS_PROXY_URL 标志。

替换以下内容：
- USERNAME：您要使用的用户名。
- TOKEN：您在上一步中创建的令牌。

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

使用 Google 服务账号

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

您的代码库位于 Secure Source Manager 或 Cloud Source Repositories 中。
您的集群已启用适用于 GKE 的工作负载身份联合或舰队工作负载身份联合。

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

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

您也可以通过自定义角色或其他预定义角色来获取所需的权限。
如果您还没有服务账号，请创建一个服务账号。
根据您使用的代码库类型，向 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，则可以使用 Compute Engine 服务账号进行身份验证，而无需使用 Google 服务账号。此方法仅适用于 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 代码库 (gcenode) 作为身份验证类型。

使用 GitHub 应用

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

按照 GitHub 上的说明预配 GitHub 应用，并向其授予从您的代码库读取数据的权限。
使用客户端 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 连接到可靠来源相关的问题，请查看以下问题排查主题：

向 Config Sync 授予对 Git 代码库的访问权限 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

选择身份验证方法

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

准备工作

使用 SSH 密钥对

使用 cookiefile

使用令牌

使用 Google 服务账号

Secure Source Manager

Cloud Source Repositories

使用 Compute Engine 默认服务账号

使用 GitHub 应用

客户端 ID

应用 ID

问题排查

后续步骤

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