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

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

须知事项

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

准备本地环境

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

  • 创建或有权访问可靠来源。

  • 安装并初始化 Google Cloud CLI，它提供了以下说明中使用的 gcloud、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 作为身份验证类型向 Operator 授予对 OCI 的访问权限，那么若要创建政策绑定，您还必须具有 iam.serviceAccounts.setIamPolicy 权限。您可以通过授予 Service Account Admin (roles/iam.serviceAccountAdmin) IAM 角色来获取此权限。您也可以使用自定义角色或其他预定义角色来获取此权限。

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

注册集群

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

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

部署 Operator

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

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

    gcloud storage 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 Federation for GKE 或舰队 Workload Identity Federation for GKE，则您可以使用 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 Federation for GKE 作为身份验证类型，然后添加您的服务账号电子邮件地址。

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

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

    如果您使用注册到舰队的集群，则只需为每个舰队创建一次政策绑定。在一个舰队中注册的所有集群共享同一个 Workload Identity Federation for GKE 池。舰队具有相同性概念，如果您将 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 Federation for GKE，则此 ID 与 PROJECT_ID 相同。如果您使用的是舰队 Workload Identity Federation for GKE，则这是集群注册到的舰队的项目 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 中，并且集群是停用了 Workload Identity Federation for GKE 的 GKE 集群，则可以使用 gcenode 作为身份验证类型。

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

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

选择 Google Cloud Repository 或 gcenode 之后，您便可以使用 Compute Engine 默认服务账号。您必须向 Compute Engine 默认服务账号授予 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: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 Federation for GKE 或舰队 Workload Identity Federation for GKE，则可以使用 k8sserviceaccount 作为身份验证类型（在 1.17.2 版及更高版本中）。由于此选项简化了配置流程，因此建议您使用此选项，而不是 gcpserviceaccount。

  1. 向使用 Workload Identity Federation for GKE 池的 Kubernetes 服务账号授予 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: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 Federation for GKE，则此 ID 与 PROJECT_ID 相同。如果您使用的是舰队 Workload Identity Federation for GKE，则这是集群注册到的舰队的项目 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 Federation for GKE 或舰队 Workload Identity Federation for GKE，则可以使用 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 Federation for GKE，则此 ID 与 PROJECT_ID 相同。如果您使用的是舰队 Workload Identity Federation for GKE，则这是集群注册到的舰队的项目 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 中，并且集群是停用了 Workload Identity Federation for GKE 的 GKE 集群，则可以使用 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) 颁发的证书进行配置的服务器，Config Sync 可以配置为使用 CA 证书来验证与服务器的 HTTPS 连接。Git、Helm 和 OCI 服务器都支持此操作。CA 证书必须包含完整的 SSL 证书（根证书/中间证书/叶证书）。如果您的服务器已在使用可信 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 对象中 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 对象中 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 Federation for GKE 或舰队 Workload Identity Federation for GKE，则可以使用 k8sserviceaccount 作为身份验证类型（在 1.17.2 版及更高版本中）。由于此选项简化了配置流程，因此建议您使用此选项，而不是 gcpserviceaccount。

  1. 向使用 Workload Identity Federation for GKE 池的 Kubernetes 服务账号授予 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: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 Federation for GKE，则此 ID 与 PROJECT_ID 相同。如果您使用的是舰队 Workload Identity Federation for GKE，则这是集群注册到的舰队的项目 ID。
    • KSA_NAME：协调器的 Kubernetes 服务账号。
      • 对于根代码库，如果 RootSync 名称为 root-sync，请使用 root-reconciler。否则，请使用 root-reconciler-ROOT_SYNC_NAME。
    • REPOSITORY：制品库的 ID。
    • LOCATION：制品库的单区域级或多区域级位置。

Google 服务账号

如果您将 Helm 图表存储在 Artifact Registry 中，并且集群使用 GKE Workload Identity Federation for GKE 或舰队 Workload Identity Federation for GKE，则可以使用 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 Federation for GKE，则此 ID 与 PROJECT_ID 相同。如果您使用的是舰队 Workload Identity Federation for GKE，则这是集群注册到的舰队的项目 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 中，并且集群是停用了 Workload Identity Federation for GKE 的 GKE 集群，则可以使用 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 Federation for GKE 时选择此选项。

      如需详细了解这些身份验证类型，请参阅授予 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 对象，请参阅配置证书授权机构

    如需了解字段的说明以及可添加到 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
    caCertSecretRef:
      name: ROOT_CA_CERT_SECRET_NAME

    替换以下内容：

    • 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 Federation for GKE 时选择此选项。
      • gcpserviceaccount：使用 Google 服务账号访问映像。

      此字段为必填字段。

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

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

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

    如需了解字段的说明以及可添加到 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
    caCertSecretRef:
      name: ROOT_CA_CERT_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 Federation for GKE 时选择此选项。
      • gcpserviceaccount：使用 Google 服务账号访问映像。

      此字段为必填字段。

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

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

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

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

    如需了解字段的说明以及可添加到 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 启动时，会运行一条协调循环语句 (reconcile loop)，用于应用新映像中捆绑的一组清单。这样会更新并重启每个组件 Pod。

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

卸载 Config Sync

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

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

    1. 如果您已启用 webhook 并希望保留资源，请为已弃用的资源停用偏移防范。如果您尚未启用网络钩子，则无需执行任何其他步骤来保留资源。

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

      kubectl delete -f root-sync.yaml

  2. 移除所有代码库。

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

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

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

后续步骤