使用 kubectl 手动安装 Config Sync（不推荐）

本页面介绍如何使用 kubectl 命令安装 Config Sync。ConfigManagement Operator 是一个控制器，用于管理 Kubernetes 集群中的 Config Sync。请按照以下步骤在您要使用 Config Sync 管理的每个集群中安装并配置 Operator。

准备工作

本部分介绍了在使用 kubectl 安装 Config Sync 之前必须满足的前提条件。

准备本地环境

在安装 Operator 之前，请先完成以下任务，以确保您已准备好本地环境：

  • 创建或访问可信来源。

  • 安装并初始化 Google Cloud CLI，它提供了以下说明中使用的 gcloud、gsutil、kubectl 和 nomos 命令。如果您使用 Cloud Shell，则系统会预安装 Google Cloud CLI。

  • Google Cloud CLI 默认不安装 kubectl。如需安装 kubectl，请使用以下命令：

    gcloud components install kubectl

  • 使用 gcloud auth login 命令向 Google Cloud 进行身份验证，以便您可以下载 Config Sync 的组件。

准备集群

创建或有权访问满足 Config Sync 要求的 Google Kubernetes Engine (GKE) Enterprise 版本集群。

准备权限

安装 Config Sync 的 Google Cloud 用户需要具有 IAM 权限才能在您的集群中创建新角色。如果需要，请使用以下命令授予这些角色：

gcloud container clusters get-credentials CLUSTER_NAME

kubectl create clusterrolebinding cluster-admin-binding \
    --clusterrole cluster-admin --user USER_ACCOUNT

替换以下内容：

  • CLUSTER_NAME：您的集群名称
  • USER_ACCOUNT：您的 Google Cloud 账号的电子邮件地址

根据您在本地系统上配置 Google Cloud CLI 的方式，您可能需要添加 --project 和 --zone 字段。

如果您需要使用 gcpserviceaccount 作为身份验证类型来授予运营商对 OCI 的访问权限，为了创建政策绑定，您还必须拥有 iam.serviceAccounts.setIamPolicy 权限。您可以通过授予 Service Account Admin (roles/iam.serviceAccountAdmin) IAM 角色来获取此权限。您也可以使用自定义角色或其他预定义角色来获取此权限。

如需详细了解如何授予角色，请参阅管理访问权限。

注册集群

要在 Config Sync 中注册集群，请完成以下步骤：

  1. 部署 Operator
  2. 向 Operator 授予对以下其中一项的只读权限：
  3. 配置 Operator

部署 Operator

确保满足所有前提条件后，您可以通过下载并应用 YAML 清单来部署 Operator。

  1. 使用以下命令下载最新版本的 Operator 清单。如需改为下载特定版本，请参阅下载。

    gsutil cp gs://config-management-release/released/latest/config-management-operator.yaml config-management-operator.yaml

  2. 应用这些清单：

    kubectl apply -f config-management-operator.yaml

如果失败是由于 ConfigManagement 对象有问题（不是因为 YAML 或 JSON 语法错误所致），则该对象可能会在集群中实例化，但无法正常运行。在这种情况下，您可以使用 nomos status 命令检查该对象中的错误。

对于没有问题的有效安装，其状态为 PENDING 或 SYNCED。

对于无效的安装，其状态为 NOT CONFIGURED，并且系统会列出以下错误之一：

  • missing git-creds Secret
  • missing required syncRepo field
  • git-creds Secret is missing the key specified by secretType

为解决此问题，请更正配置错误。根据错误类型，您可能需要将 ConfigManagement 清单重新应用到集群。

如果问题的原因是您忘记创建 git-creds Secret，则 Config Sync 会在您创建该 Secret 后立即检测到它，这样您就无需重新应用配置。

向 Operator 授予只读权限

如果您将配置存储在 Git 中，则必须向 Operator 授予对 Git 的只读权限。如果您将配置存储为 OCI 映像，则必须向 Operator 授予对 OCI 的只读权限。 如果您将配置存储在 Helm 中，则必须向 Operator 授予对 Helm 的只读权限。

向 Operator 授予对 Git 的只读权限

Config Sync 需要 Git 代码库的只读权限，以便读取提交到代码库的配置，并将其应用到您的集群。

如果您的代码库无需进行身份验证即可提供只读权限，您可以继续配置 Config Sync 并使用 none 作为身份验证类型。例如，如果您无需登录即可使用网页界面浏览代码库，或者如果您可以使用 git clone 在本地创建代码库的克隆而无需提供凭据或使用已保存的凭据，则无需进行身份验证。在这种情况下，您不需要创建 Secret。

不过，大多数用户都需要创建凭据，因为对其代码库的读取权限会受到限制。如果需要凭据，则凭据会存储在每个注册集群的 git-creds Secret 中（除非您使用的是 Google 服务账号）。Secret 必须是命名 git-creds，因为这是一个固定值。

Config Sync 支持以下身份验证机制：

  • SSH 密钥对 (ssh)
  • Cookiefile (cookiefile)
  • 令牌 (token)
  • Google 服务帐号 (gcpserviceaccount)
  • Compute Engine 默认服务账号 (gcenode)

您选择的机制取决于您的代码库支持的内容。通常，我们推荐您使用 SSH 密钥对。GitHub 和 Bitbucket 都支持使用 SSH 密钥对。但是，如果您使用的是 Cloud Source Repositories 中的代码库，我们建议您使用 Google 服务账号，因为其流程更简单。如果您的组织托管代码库，并且您不知道其支持哪些身份验证方法，请与您的管理员联系。

如需将 Cloud Source Repositories 中的代码库用作 Config Sync 代码库，请完成以下步骤以检索 Cloud Source Repositories 网址：

  1. 列出所有代码库：

    gcloud source repos list

  2. 在输出中，复制您要使用的代码库的网址。例如：

    REPO_NAME  PROJECT_ID  URL
my-repo    my-project  https://source.developers.google.com/p/my-project/r/my-repo-csr

    在下一部分中配置 Config Sync 时，您需要使用此网址。如果您使用 Google Cloud 控制台配置 Config Sync，则可以在网址字段中添加网址。如果您使用 Google Cloud CLI 配置 Config Sync，请将网址添加到配置文件的 syncRepo 字段中。

SSH 密钥对

SSH 密钥对由两个文件组成，即公钥和私钥。公钥通常具有 .pub 扩展名。

要使用 SSH 密钥对，请完成以下步骤：

  1. 创建 SSH 密钥对，以允许 Config Sync 向您的 Git 代码库进行身份验证。如果您需要向代码库验证身份以克隆代码库或从中读取内容，则需要执行此步骤。如果安全管理员为您提供密钥对，请跳过此步骤。您可以对所有集群使用一个密钥对，也可以对每个集群各使用一个密钥对，具体取决于您的安全性和合规性要求。

    以下命令会创建 4096 位 RSA 密钥。建议不要使用较小的值：

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

    替换以下内容：

    • GIT_REPOSITORY_USERNAME：您希望 Config Sync 用于向代码库进行身份验证的用户名
    • /path/to/KEYPAIR_FILENAME：密钥对的路径

    如果您使用的是第三方 Git 代码库主机（如 GitHub），或者想要将服务账号用于 Cloud Source Repositories，我们建议您使用一个单独的账号。

  2. 配置您的代码库以识别新创建的公钥。 请参阅 Git 托管服务提供商的文档。为方便起见，我们提供了一些常用的 Git 托管服务提供商的说明：

  3. 将私钥添加到集群中的新 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 替换为私钥（即不含 .pub 后缀的密钥）的名称。

  4. （推荐）如需配置使用 SSH 身份验证进行已知主机检查，可以将已知主机密钥添加到 git_creds Secret 的 data.known_hosts 字段中。如需停用 known_hosts 检查，您可以从 Secret 中移除 known_hosts 字段。如需添加已知主机密钥，请运行以下命令：

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

    然后，在 data 下添加已知主机条目：

    known_hosts: KNOWN_HOSTS_KEY

  5. 从本地磁盘中删除私钥或以其他方式保护私钥。

  6. 配置 Config Sync 并添加 Git 代码库的网址时，请使用 SSH 协议。如果您使用的是 Cloud Source Repositories 中的代码库，则必须在输入网址时使用以下格式：

    ssh://EMAIL@source.developers.google.com:2022/p/PROJECT_ID/r/REPO_NAME

    替换以下内容：

    • EMAIL：您的 Google Cloud 用户名
    • PROJECT_ID：代码库所在 Google Cloud 项目的 ID
    • REPO_NAME：代码库的名称

Cookiefile

获取 cookiefile 的过程取决于您代码库的配置。如需查看示例，请参阅 Cloud Source Repositories 文档中的生成静态凭据。凭据通常存储在您的主目录下的 .gitcookies 文件中，也可能由安全管理员提供给您。

要使用 cookiefile，请完成以下步骤：

  1. 创建并获取 cookiefile 后，将其添加到集群的新 Secret 中。

    如果您不使用 HTTPS 代理，请使用以下命令创建 Secret：

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

    如果您需要使用 HTTPS 代理，请运行以下命令，将其与 cookiefile 添加到 Secret 中：

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

    替换以下内容：

    • 将 /path/to/COOKIEFILE 替换为适当的路径和文件名
    • 将 HTTPS_PROXY_URL 替换为您在与 Git 代码库通信时使用的 HTTPS 代理的网址

  2. 如果您仍需在本地使用 cookiefile，请保护好其内容。否则，请将其删除。

令牌

如果您的组织不允许使用 SSH 密钥，您可能更倾向于使用令牌。借助 Config Sync，您可以使用 GitHub 的个人访问令牌 (PAT)、GiLab 的 PAT 或部署键，或 Bitbucket 的应用专用密码作为令牌。

如需使用您的令牌创建 Secret，请完成以下步骤：

  1. 使用 GitHub、GitLab 或 Bitbucket 创建令牌：

  2. 创建并获取令牌后，将其添加到集群的新 Secret 中。

    如果您不使用 HTTPS 代理，请使用以下命令创建 Secret：

    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：您在上一步中创建的令牌。

    如果您需要使用 HTTPS 代理，请运行以下命令，将其与 username 和 token 添加到 Secret 中：

    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：您在上一步中创建的令牌。
    • 将 HTTPS_PROXY_URL 替换为您在与 Git 代码库通信时使用的 HTTPS 代理的网址。

  3. 如果您仍需在本地使用令牌，请保护好令牌。否则，请将其删除。

Google 服务账号

如果您的代码库在 Cloud Source Repositories 中，并且您的集群使用 GKE Workload Identity 或舰队 Workload Identity，您可以使用 Google 服务帐号向 Config Sync 授予对代管式集群所在项目中的代码库的访问权限。

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

  2. 向 Google 服务帐号授予 Cloud Source Repositories Reader (roles/source.reader) IAM 角色。如需详细了解 Cloud Source Repositories 角色和权限，请参阅授予查看代码库的权限。

    • 如果相同的权限适用于项目中的所有代码库，则授予项目范围的权限。

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

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

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

  3. 如果您使用 Google Cloud 控制台配置 Config Sync，请选择 Workload Identity 作为身份验证类型，然后添加您的服务账号电子邮件地址。

    如果您使用 Google Cloud CLI 配置 Config Sync，请将 gcpserviceaccount 添加为 secretType，然后将您的服务账号电子邮件添加到 gcpServiceAccountEmail 中。

  4. 配置 Config Sync 后，在 Kubernetes 服务帐号与 Google 服务帐号之间创建 IAM 政策绑定。在您首次配置 Config Sync 之前，系统不会创建 Kubernetes 服务账号。

    如果您使用注册到舰队的集群，则只需为每个舰队创建一次政策绑定。在舰队中注册的所有集群共享相同的 Workload Identitypool。根据舰队的“相同性”概念，如果您将 IAM 政策添加到一个集群中的 Kubernetes 服务帐号，则同一舰队中其他集群上的同一命名空间中的 Kubernetes 服务帐号也将获得相同的 IAM 政策。

    此绑定允许 Config Sync 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

替换以下内容：

  • PROJECT_ID：组织的项目 ID。
  • FLEET_HOST_PROJECT_ID：如果您使用的是 GKE Workload Identity，则它与 PROJECT_ID 相同。如果您使用的是舰队 Workload Identity，则这是集群注册到的舰队的项目 ID。
  • GSA_NAME：您要用来连接到 Artifact Registry 的自定义 Google 服务账号。该服务账号必须具有 Artifact Registry Reader (roles/artifactregistry.reader) IAM 角色。
  • KSA_NAME：协调器的 Kubernetes 服务账号。
    • 对于根代码库，如果 RootSync 名称为 root-sync，请使用 root-reconciler。否则，请使用 root-reconciler-ROOT_SYNC_NAME。如果您使用 Google Cloud 控制台或 Google Cloud CLI 安装 Config Sync，Config Sync 会自动创建名为 root-sync 的 RootSync 对象。
  • REPOSITORY：代码库的名称。
  • POLICY_FILE：具有 Identity and Access Management 政策的 JSON 或 YAML 文件。

Compute Engine 默认服务帐号

如果您的代码库位于 Cloud Source Repositories 中，并且您的集群是 GKE on Google Cloud 且停用了 Workload Identity，则您可以使用 gcenode 作为身份验证类型。

如果您使用 Google Cloud 控制台配置 Config Sync，请选择 Google Cloud Repository 作为身份验证类型。

如果您使用 Google Cloud CLI 配置 Config Sync，请将 gcenode 添加为 secretType。

选择 Google Cloud Repository 或 gcenode 可让您使用 Compute Engine 默认服务帐号。您必须将 Cloud Source Repositories Reader (roles/source.reader) IAM 角色授予 Compute Engine 默认服务帐号。如需详细了解 Cloud Source Repositories 角色和权限，请参阅授予查看代码库的权限。

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 替换为组织的项目编号。

向 Operator 授予对 OCI 的只读权限

Config Sync 需要具有 Artifact Registry 中存储的 OCI 映像的只读权限，才能读取映像中包含的配置并将其应用到您的集群。

如果您的映像无需进行身份验证即可提供只读权限，您可以继续配置 Config Sync 并使用 none 作为身份验证类型。例如，如果您的映像是公开的，互联网上的任何人都可以访问，那么您无需进行身份验证。

不过，大多数用户都需要创建凭据才能访问受限映像。Config Sync 支持以下身份验证机制：

  • Kubernetes 服务帐号 (k8sserviceaccount)
  • Google 服务帐号 (gcpserviceaccount)

  • Compute Engine 默认服务账号 (gcenode)

Kubernetes 服务账号

如果您将 OCI 映像存储在 Artifact Registry 中，并且集群使用 GKE Workload Identity 或舰队 Workload Identity，则可以在 1.17.2 版及更高版本中使用 k8sserviceaccount 作为身份验证类型。由于可以简化配置过程，因此推荐此选项而非 gcpserviceaccount。

  1. 将 Artifact Registry Reader (roles/artifactregistry.reader) IAM 角色授予包含 Workload Identity 池的 Kubernetes 服务帐号。如需详细了解 Artifact Registry 角色和权限，请参阅配置 Artifact Registry 的角色和权限。

    • 如果相同的权限适用于项目中的所有代码库，则授予项目范围的权限。

      gcloud projects add-iam-policy-binding PROJECT_ID \
      --role=roles/artifactregistry.reader \
      --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]"

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

      gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
   --location=LOCATION \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
   --project=PROJECT_ID

    替换以下内容：

    • PROJECT_ID：组织的项目 ID。
    • FLEET_HOST_PROJECT_ID：如果您使用的是 GKE Workload Identity，则它与 PROJECT_ID 相同。如果您使用的是舰队 Workload Identity，则这是集群注册到的舰队的项目 ID。
    • KSA_NAME：协调器的 Kubernetes 服务账号。
      • 对于根代码库，如果 RootSync 名称为 root-sync，请使用 root-reconciler。否则，请使用 root-reconciler-ROOT_SYNC_NAME。如果您使用 Google Cloud 控制台或 Google Cloud CLI 安装 Config Sync，Config Sync 会自动创建名为 root-sync 的 RootSync 对象。
    • REPOSITORY：代码库的 ID。
    • LOCATION：代码库的单区域或多区域位置。

Google 服务账号

如果您将 OCI 映像存储在 Artifact Registry 中，并且您的集群使用 GKE Workload Identity 或舰队 Workload Identity，则您可以使用 gcpserviceaccount 作为身份验证类型。从版本 1.17.2 开始，建议改用 k8sserviceaccount。此选项消除了创建 Google 服务帐号以及关联的 IAM 政策绑定的额外步骤。

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

  2. 向 Google 服务帐号授予 Artifact Registry Reader (roles/artifactregistry.reader) IAM 角色。如需详细了解 Artifact Registry 角色和权限，请参阅配置 Artifact Registry 的角色和权限。

    • 如果相同的权限适用于项目中的所有代码库，则授予项目范围的权限。

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

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

      gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
   --location=LOCATION \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --project=PROJECT_ID

  3. 通过运行以下命令，在 Kubernetes 服务账号和 Google 服务账号之间创建 IAM 政策绑定：

    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

替换以下内容：

  • PROJECT_ID：组织的项目 ID。
  • FLEET_HOST_PROJECT_ID：如果您使用的是 GKE Workload Identity，则它与 PROJECT_ID 相同。如果您使用的是舰队 Workload Identity，则这是集群注册到的舰队的项目 ID。
  • GSA_NAME：您要用来连接到 Artifact Registry 的自定义 Google 服务账号。该服务账号必须具有 Artifact Registry Reader (roles/artifactregistry.reader) IAM 角色。
  • KSA_NAME：协调器的 Kubernetes 服务账号。
    • 对于根代码库，如果 RootSync 名称为 root-sync，请使用 root-reconciler。否则，请使用 root-reconciler-ROOT_SYNC_NAME。如果您使用 Google Cloud 控制台或 Google Cloud CLI 安装 Config Sync，Config Sync 会自动创建名为 root-sync 的 RootSync 对象。
  • REPOSITORY：代码库的 ID。
  • LOCATION：代码库的单区域或多区域位置。

Compute Engine 默认服务帐号

如果您将 Helm 图表存储在 Artifact Registry 中，并且您的集群是 GKE on Google Cloud，并且停用了 Workload Identity，则可以使用 gcenode 作为身份验证类型。Config Sync 使用 Compute Engine 默认服务账号。您必须向 Compute Engine 默认服务账号授予对 Artifact Registry 的读取权限。

  1. 运行以下命令，向 Compute Engine 服务账号授予对 Artifact Registry 的读取权限：

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

    将 PROJECT_ID 替换为组织的项目 ID，并将 PROJECT_NUMBER 替换为组织的项目编号。

为证书授权机构配置 Operator

对于使用非可信证书授权机构 (CA) 颁发的证书进行配置的 Git 服务器，Config Sync 可以配置为使用 CA 证书来验证与 Git 服务器的 HTTPS 连接。CA 证书必须包含完整的 SSL 证书（根/中间/叶）。如果您的 Git 服务器已在使用可信 CA，或者没有通过 HTTPS 进行连接，则可以跳过此步骤并且无需设置 caCertSecretRef。

RootSync

  1. 提取用于为 Git 服务器颁发证书的 CA 证书，并将其保存到一个文件中。

  2. 对于 RootSync 对象，必须在 config-management-system 命名空间中创建 Secret。例如：

    kubectl create ns config-management-system && 
    
kubectl create secret generic ROOT_CA_CERT_SECRET_NAME 
    
 --namespace=config-management-system 
    
 --from-file=cert=/path/to/CA_CERT_FILE

  3. 配置 Operator 时，将 RootSync 对象中 spec.git.caCertSecretRef.name 字段的值设置为 ROOT_CA_CERT_SECRET_NAME。

RepoSync

  1. 提取用于为 Git 服务器颁发证书的 CA 证书，并将其保存到一个文件中。

  2. 对于 RepoSync 对象，必须在 RepoSync 所在的命名空间中创建 Secret。例如：

    kubectl create ns REPO_SYNC_NAMESPACE && 
    
kubectl create secret generic NAMESPACE_CA_CERT_SECRET_NAME 
    
 --namespace=REPO_SYNC_NAMESPACE 
    
 --from-file=cert=/path/to/CA_CERT_FILE

  3. 配置 RepoSync 时，将 RepoSync 对象中 spec.git.caCertSecretRef.name 字段的值设置为 NAMESPACE_CA_CERT_SECRET_NAME。

向 Operator 授予对 Helm 的只读权限

Config Sync 需要具备对 Helm 代码库的只读权限，以便可以读取代码库中的 Helm 图表并将其安装到您的集群中。

如果您的代码库无需进行身份验证即可提供只读权限，您可以继续配置 Config Sync 并使用 none 作为身份验证类型。例如，如果您的 Helm 代码库是公开提供的，可供互联网上的任何人访问，那么便无需进行身份验证。

但是，大多数用户都需要创建凭据才能访问私有 Helm 代码库。Config Sync 支持以下身份验证机制：

  • 令牌 (token)
  • Kubernetes 服务帐号 (k8sserviceaccount)
  • Google 服务帐号 (gcpserviceaccount)
  • Compute Engine 默认服务账号 (gcenode)

令牌

使用 Helm 代码库用户名和密码创建 Secret：

kubectl create secret generic SECRET_NAME \
    --namespace=config-management-system \
    --from-literal=username=USERNAME \
    --from-literal=password=PASSWORD

替换以下内容：

  • SECRET_NAME：您要为 Secret 指定的名称。
  • USERNAME：Helm 代码库用户名。
  • PASSWORD：Helm 代码库密码。

配置 ConfigManagement Operator 时，您将使用为 spec.helm.secretRef.name 选择的 Secret 名称。

Kubernetes 服务账号

如果您将 Helm 图表存储在 Artifact Registry 中，并且集群使用 GKE Workload Identity 或舰队 Workload Identity，则可以在 1.17.2 版及更高版本中使用 k8sserviceaccount 作为身份验证类型。由于可以简化配置过程，因此推荐此选项而非 gcpserviceaccount。

  1. 将 Artifact Registry Reader (roles/artifactregistry.reader) IAM 角色授予包含 Workload Identity 池的 Kubernetes 服务帐号。如需详细了解 Artifact Registry 角色和权限，请参阅配置 Artifact Registry 的角色和权限。

    • 如果相同的权限适用于项目中的所有代码库，则授予项目范围的权限。

      gcloud projects add-iam-policy-binding PROJECT_ID \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]"

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

      gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
   --location=LOCATION \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
   --project=PROJECT_ID

    替换以下内容：

    • PROJECT_ID：组织的项目 ID。
    • FLEET_HOST_PROJECT_ID：如果您使用的是 GKE Workload Identity，则它与 PROJECT_ID 相同。如果您使用的是舰队 Workload Identity，则这是集群注册到的舰队的项目 ID。
    • KSA_NAME：协调器的 Kubernetes 服务账号。
      • 对于根代码库，如果 RootSync 名称为 root-sync，请使用 root-reconciler。否则，请使用 root-reconciler-ROOT_SYNC_NAME。
    • REPOSITORY：代码库的 ID。
    • LOCATION：代码库的单区域或多区域位置。

Google 服务账号

如果您将 Helm 图表存储在 Artifact Registry 中，并且集群使用 GKE Workload Identity 或舰队 Workload Identity，则可以使用 gcpserviceaccount 作为身份验证类型。从版本 1.17.2 开始，建议改用 k8sserviceaccount。此选项消除了创建 Google 服务帐号以及关联的 IAM 政策绑定的额外步骤。

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

  2. 向 Google 服务帐号授予 Artifact Registry Reader (roles/artifactregistry.reader) IAM 角色。如需详细了解 Artifact Registry 角色和权限，请参阅配置 Artifact Registry 的角色和权限。

    • 如果相同的权限适用于项目中的所有代码库，则授予项目范围的权限。

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

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

      gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
   --location=LOCATION \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --project=PROJECT_ID

  3. 通过运行以下命令，在 Kubernetes 服务账号和 Google 服务账号之间创建 IAM 政策绑定：

    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

替换以下内容：

  • PROJECT_ID：组织的项目 ID。
  • FLEET_HOST_PROJECT_ID：如果您使用的是 GKE Workload Identity，则它与 PROJECT_ID 相同。如果您使用的是舰队 Workload Identity，则这是集群注册到的舰队的项目 ID。
  • GSA_NAME：您要用来连接到 Artifact Registry 的自定义 Google 服务账号。该服务账号必须具有 Artifact Registry Reader (roles/artifactregistry.reader) IAM 角色。
  • KSA_NAME：协调器的 Kubernetes 服务账号。
    • 对于根代码库，如果 RootSync 名称为 root-sync，请使用 root-reconciler。否则，请使用 root-reconciler-ROOT_SYNC_NAME。
  • REPOSITORY：代码库的 ID。
  • LOCATION：代码库的单区域或多区域位置。

Compute Engine 默认服务帐号

如果您将 Helm 图表存储在 Artifact Registry 中，并且您的集群是 GKE on Google Cloud，并且停用了 Workload Identity，则可以使用 gcenode 作为身份验证类型。Config Sync 使用 Compute Engine 默认服务账号。您必须向 Compute Engine 默认服务账号授予对 Artifact Registry 的读取权限。您可能需要授予 storage-ro 访问权限范围才能授予对拉取映像的只读权限。

  1. 向 Compute Engine 服务账号授予对 Artifact Registry 的读取权限：

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

    将 PROJECT_ID 替换为组织的项目 ID，并将 PROJECT_NUMBER 替换为组织的项目编号。

配置 Operator

如需配置从根代码库进行同步，您需要在 ConfigManagement 对象中启用多代码库模式，并创建一个用于将根代码库同步到集群的 RootSync 对象。您只能为每个集群创建一个根代码库，而且该代码库可以是非结构化代码库或分层代码库。

  1. 如果您使用的是 Config Sync 准入 webhook（准入 webhook 默认处于停用状态），并且要在专用集群中安装 Config Sync，请添加防火墙规则以允许端口 10250。Config Sync 准许网络钩子使用端口 10250 来防止偏移。

  2. 创建名为 config-management.yaml 的文件并将以下 YAML 文件复制到其中：

    # config-management.yaml
apiVersion: configmanagement.gke.io/v1
kind: ConfigManagement
metadata:
  name: config-management
spec:
  # The `enableMultiRepo` field is set to true to enable RootSync and RepoSync APIs.
  enableMultiRepo: true
  preventDrift: PREVENT_DRIFT

    替换以下内容：

    • PREVENT_DRIFT：如果设置为 true，则允许 Config Sync 准入网络钩子通过拒绝将有冲突的更改推送到活跃集群来防止偏移。默认设置为 false。 无论此字段的值如何，Config Sync 始终会修复偏移。

  3. 应用更改：

    kubectl apply -f config-management.yaml

  4. 请等待 RootSync 和 RepoSync CRD 可用：

    until kubectl get customresourcedefinitions rootsyncs.configsync.gke.io reposyncs.configsync.gke.io; do date; sleep 1; echo ""; done

  5. 将以下清单之一保存为 root-sync.yaml。请使用与配置的来源类型对应的清单版本。

    Git

    # root-sync.yaml
apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: ROOT_SYNC_NAME
  namespace: config-management-system
spec:
  sourceType: git
  sourceFormat: ROOT_FORMAT
  git:
    repo: ROOT_REPOSITORY
    revision: ROOT_REVISION
    branch: ROOT_BRANCH
    dir: ROOT_DIRECTORY
    auth: ROOT_AUTH_TYPE
    gcpServiceAccountEmail: ROOT_EMAIL
    secretRef:
      name: ROOT_SECRET_NAME
    noSSLVerify: ROOT_NO_SSL_VERIFY
    caCertSecretRef:
      name: ROOT_CA_CERT_SECRET_NAME

    替换以下内容：

    • ROOT_SYNC_NAME：添加 RootSync 对象的名称。
    • ROOT_FORMAT：添加 unstructured 以使用非结构化代码库，或添加 hierarchy 以使用分层代码库。 这些值区分大小写。此字段是可选字段，默认值为 hierarchy。我们建议您添加 unstructured，因为您可以采用这种格式以最适合您的方式整理配置。
    • ROOT_REPOSITORY：添加要用作根代码库的 Git 代码库的网址。您可以输入使用 HTTPS 或 SSH 协议的网址。例如，https://github.com/GoogleCloudPlatform/anthos-config-management-samples 使用 HTTPS 协议。此字段为必填字段。
    • ROOT_REVISION：添加要与之同步的 Git 修订版本（标记或哈希）。此字段是可选字段，默认值为 HEAD。从 Config Sync 1.17.0 版开始，您还可以在 revision 字段中指定分支名称。在 1.17.0 或更高版本中使用哈希时，它必须是完整的哈希，而不能是缩写形式。
    • ROOT_BRANCH：添加要从中同步的代码库的分支。此字段是可选字段，默认值为 master。从 Config Sync 1.17.0 版开始，建议使用 revision 字段指定分支名称，以简单化。如果同时指定了 revision 字段和 branch 字段，则 revision 的优先级高于 branch。
    • ROOT_DIRECTORY：添加 Git 代码库中指向您要同步的配置所在的根目录的路径。此字段是可选字段，默认值为代码库的根目录 (/)。

    • ROOT_AUTH_TYPE：添加以下身份验证类型之一：

      • none：不使用身份验证
      • ssh：使用 SSH 密钥对
      • cookiefile：使用 cookiefile
      • token：使用令牌
      • gcpserviceaccount：使用 Google 服务账号访问 Cloud Source Repositories。
      • gcenode：使用 Google 服务账号访问 Cloud Source Repositories。请仅在集群中未启用 Workload Identity 时选择此选项。

      如需详细了解这些身份验证类型，请参阅授予 Config Sync 对 Git 的只读权限。

      此字段为必填字段。

    • ROOT_EMAIL：如果您已将 gcpserviceaccount 添加为 ROOT_AUTH_TYPE，请添加您的 Google 服务账号电子邮件地址。例如 acm@PROJECT_ID.iam.gserviceaccount.com。

    • ROOT_SECRET_NAME：添加 Secret 的名称。如果设置了此字段，您必须将 Secret 的公钥添加到 Git 提供商。此字段是可选字段。

    • ROOT_NO_SSL_VERIFY：如需停用 SSL 证书验证，请将此字段设置为 true。默认值为 false。

    • ROOT_CA_CERT_SECRET_NAME：添加 Secret 的名称。如果设置了此字段，您的 Git 提供商必须使用由此证书授权机构 (CA) 颁发的证书。Secret 必须在名为 cert 的密钥下提供 CA 证书。此字段是可选字段。

      如需详细了解如何为 CA 证书配置 Secret 对象，请参阅为证书授权机构配置 Operator

    如需了解字段的说明以及可添加到 spec 字段的字段的完整列表，请参阅 RootSync 字段。

    此清单会创建一个使用 Git 作为来源的 RootSync 对象。

    OCI

    # root-sync.yaml
apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: ROOT_SYNC_NAME
  namespace: config-management-system
spec:
  sourceType: oci
  sourceFormat: ROOT_FORMAT
  oci:
    image: ROOT_IMAGE
    dir: ROOT_DIRECTORY
    auth: ROOT_AUTH_TYPE
    gcpServiceAccountEmail: ROOT_EMAIL

    替换以下内容：

    • ROOT_SYNC_NAME：添加 RootSync 对象的名称。
    • ROOT_FORMAT：添加 unstructured 以使用非结构化代码库，或添加 hierarchy 以使用分层代码库。这些值区分大小写。此字段是可选字段，默认值为 hierarchy。我们建议您添加 unstructured，因为您可以采用这种格式以最适合您的方式整理配置。
    • ROOT_IMAGE：要用作根代码库的 OCI 映像的网址，例如 LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME。默认情况下，映像是从 latest 标记中拉取的，但您也可以通过 TAG 或 DIGEST 拉取映像。在 PACKAGE_NAME 中指定 TAG 或 DIGEST：
      • 如需通过 TAG 拉取： LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME:TAG
      • 如需通过 DIGEST 拉取： LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME@sha256:DIGEST
    • ROOT_DIRECTORY：添加代码库中指向您要同步的配置所在的根目录的路径。此字段是可选字段，默认值为代码库的根目录 (/)。

    • ROOT_AUTH_TYPE：添加以下身份验证类型之一：

      • none：不使用身份验证
      • gcenode：使用 Compute Engine 默认服务账号访问 Artifact Registry 中的映像。请仅在集群中未启用 Workload Identity 时选择此选项。
      • gcpserviceaccount：使用 Google 服务账号访问映像。

      此字段为必填字段。

    • ROOT_EMAIL：如果您已将 gcpserviceaccount 添加为 ROOT_AUTH_TYPE，请添加您的 Google 服务账号电子邮件地址。例如 acm@PROJECT_ID.iam.gserviceaccount.com。

    如需了解字段的说明以及可添加到 spec 字段的字段的完整列表，请参阅 RootSync 字段。

    此清单会创建一个使用 OCI 映像作为来源的 RootSync 对象。

    Helm

    # root-sync.yaml
apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: ROOT_SYNC_NAME
  namespace: config-management-system
spec:
  sourceType: helm
  sourceFormat: ROOT_FORMAT
  helm:
    repo: ROOT_HELM_REPOSITORY
    chart: HELM_CHART_NAME
    version: HELM_CHART_VERSION
    releaseName: HELM_RELEASE_NAME
    namespace: HELM_RELEASE_NAMESPACE
    values:
      foo:
        bar: VALUE_1
      baz:
      - qux: VALUE_2
        xyz: VALUE_3
    includeCRDs: HELM_INCLUDE_CRDS
    auth: ROOT_AUTH_TYPE
      gcpServiceAccountEmail: ROOT_EMAIL
      secretRef:
        name: ROOT_SECRET_NAME

    替换以下内容：

    • ROOT_SYNC_NAME：添加 RootSync 对象的名称。
    • ROOT_FORMAT：添加 unstructured 以使用非结构化代码库，或添加 hierarchy 以使用分层代码库。这些值区分大小写。此字段是可选字段，默认值为 hierarchy。我们建议您添加 unstructured，因为您可以采用这种格式以最适合您的方式整理配置。
    • ROOT_HELM_REPOSITORY：要用作根代码库的 Helm 代码库的网址。您可以输入使用 HTTPS 或 SSH 协议的网址。例如，https://github.com/GoogleCloudPlatform/anthos-config-management-samples 使用 HTTPS 协议。此字段为必填字段。
    • HELM_CHART_NAME：添加 Helm 图表的名称。此字段为必填字段。
    • HELM_CHART_VERSION：您的图表的版本。此字段是可选字段。如果未指定任何值，则使用最新版本。
    • HELM_RELEASE_NAME：Helm 版本的名称。此字段是可选字段。
    • HELM_RELEASE_NAMESPACE：版本的目标命名空间。它只会为模板中包含 namespace: {{ .Release.Namespace }} 的资源设置命名空间。此字段是可选字段。如果未指定任何值，则使用默认命名空间 config-management-system。
    • HELM_INCLUDE_CRDS：如果您希望 Helm 模板同时也生成 CustomResourceDefinition，则设置为 true。此字段是可选字段。如果未指定任何值，则默认为 false，并且不会生成 CRD。
    • VALUE：用于替换 Helm 图表随附的默认值的值。 设置此字段的格式方式与 helm 图表的 values.yaml 文件相同。此字段是可选字段。

    • ROOT_AUTH_TYPE：添加以下身份验证类型之一：

      • none：不使用身份验证
      • token：使用用户名和密码访问私有 Helm 代码库。
      • gcenode：使用 Compute Engine 默认服务账号访问 Artifact Registry 中的映像。请仅在集群中未启用 Workload Identity 时选择此选项。
      • gcpserviceaccount：使用 Google 服务账号访问映像。

      此字段为必填字段。

    • ROOT_EMAIL：如果您已将 gcpserviceaccount 添加为 ROOT_AUTH_TYPE，请添加您的 Google 服务账号电子邮件地址。例如 acm@PROJECT_ID.iam.gserviceaccount.com。

    • ROOT_SECRET_NAME：添加 Secret 名称（如果 token 为 ROOT_AUTH_TYPE）。此字段是可选字段。

    如需了解字段的说明以及可添加到 spec 字段的字段的完整列表，请参阅 RootSync 字段。

    此清单会创建一个使用 Helm 作为来源的 RootSync 对象。

  6. 应用更改：

    kubectl apply -f root-sync.yaml

验证根代码库的同步状态

您可以使用 nomos status 命令检查根代码库的同步状态：

nomos status

您应该会看到类似于以下示例的输出：

my_managed_cluster-1
  --------------------
  <root>   git@github.com:foo-corp/acme/admin@main
  SYNCED   f52a11e4

验证 RootSync 安装

创建 RootSync 对象时，Config Sync 会创建一个具有 root-reconciler 前缀的协调器。协调器是部署为 Deployment 的 Pod。 它会将清单从 Git 代码库同步到集群。

您可以通过检查根协调器的部署状态来验证 RootSync 对象是否正常工作：

kubectl get -n config-management-system deployment \
    -l configsync.gke.io/sync-name=ROOT_SYNC_NAME

将 ROOT_SYNC_NAME 替换为 RootSync 的名称。

您应该会看到类似于以下示例的输出：

NAME              READY   UP-TO-DATE   AVAILABLE   AGE
root-reconciler   1/1     1            1           3h42m

如需查看探索 RootSync 对象状态的其他方法，请参阅监控 RootSync 和 RepoSync 对象。

完成根代码库的配置后，您可以选择配置从多个代码库同步。如果您希望代码库中包含要跨集群同步到特定命名空间的命名空间级配置，则这些代码库非常有用。

升级 Config Sync

如需升级 Config Sync，请为每个已注册的集群运行以下命令：

  1. 下载新版本的 Config Sync 清单和 nomos 命令。

  2. 应用 Config Sync 清单：

    kubectl apply -f config-management-operator.yaml

    此命令会更新 ConfigManagement Operator 映像。Kubernetes 会检索新版本并使用新版本重启 Config Sync Pod。Config Sync 启动时，会运行协调循环，以应用新映像中捆绑的一组清单。这样会更新并重启每个组件 Pod。

  3. 将所有客户端上的 nomos 命令替换为新版本。此更改可以确保 nomos 命令始终能够获取所有注册集群的状态，并且能够验证这些集群的配置。

卸载 Config Sync

如需卸载 Config Sync，请完成以下步骤：

  1. 中央管理员应移除根代码库：

    1. 按照问题排查说明取消管理或删除由 RootSync 对象管理的资源。

    2. 通过运行以下命令删除 RootSync 对象：

      kubectl delete -f root-sync.yaml

  2. 移除所有代码库。

  3. 移除 config-management.yaml 文件中的 spec.enableMultiRepo 字段。

  4. 将 config-management.yaml 文件应用到您的集群。

如果要完全卸载 Config Sync，请参阅移除 ConfigManagement Operator。

后续步骤