自定义 Config Sync 安装

借助 Config Sync，您可以通过同步来自中央可靠来源（例如 Git 代码库、OCI 映像或 Helm 图表）的配置来管理 Kubernetes 资源。如果默认安装说明不符合您的需求，您可能需要自定义 Config Sync 安装。

本页面介绍了如何执行 Config Sync 的高级安装和配置。安装过程包括以下步骤：

使用Google Cloud 控制台、Google Cloud CLI 或 Terraform 在个别集群上安装 Config Sync。
配置根代码库，包括源代码类型、格式和身份验证。
验证是否已成功安装和配置 Config Sync。

限制

Config Sync 不支持使用 Google Cloud 控制台或 Google Cloud CLI 将 helm 配置为源代码类型。您可以使用 Kubernetes API 将 RootSync 或 RepoSync 对象配置为从 Helm 代码库同步，或在其他可靠来源中进行声明。如需了解详情，请参阅 Helm 代码库的配置。

准备工作

在安装 Config Sync 之前，请准备可靠来源和合适的集群。

授予 Config Sync 对可靠来源的访问权限

为了将配置从可靠来源同步到集群，Config Sync 需要具有对代码库的只读权限。如需授权 Config Sync 读取您的配置，请完成以下步骤：

创建或有权访问包含您希望 Config Sync 将其同步到集群的配置文件的可靠来源。如需了解详情，请参阅以下资源：
- 将配置添加到可靠来源：有关配置的概念性信息。
- GitOps 最佳实践：有关组织和管理代码库的提示和一般最佳实践。
- 使用非结构化代码库：有关使用和组织非结构化代码库的建议。
如果可靠来源是公开的，则无需采取进一步操作。 Config Sync 不需要额外的权限。
如果可靠来源是私有的，请按照以下某个页面中的说明操作：
- 授予 Config Sync 对 Git 的访问权限。
- 授予 Config Sync 对 OCI 或 Helm 的访问权限。

查看集群要求

在创建集群之前，请查看集群要求。

安装 Config Sync

当您使用 Google Cloud 控制台或 Google Cloud CLI 安装 Config Sync 时，Config Sync 会自动创建名为 root-sync 的 RootSync 对象。您可以使用 kubectl 命令修改 root-sync 并添加其他 Config Sync 配置。如需了解详情，请参阅使用 kubectl 命令配置 Config Sync。

控制台

安装 Config Sync

如需安装 Config Sync，所有集群都必须注册到舰队。在 Google Cloud 控制台中安装 Config Sync 时，选择个别集群会自动将这些集群注册到舰队。

在 Google Cloud 控制台中，前往功能部分下的配置页面。

转到“配置”

点击 安装 Config Sync。
选择要使用的 Config Sync 版本。
在安装选项下，选择以下选项之一：
- Install Config Sync on entire fleet (recommended)：Config Sync 会安装在舰队中的所有集群上。
- Install Config Sync on individual clusters：Config Sync 会安装在您选择的集群上。任何所选集群都会自动注册到您的舰队。
如果您要在个别集群上安装 Config Sync，请在可用集群表中选择要安装 Config Sync 的集群。
点击 Install Config Sync（安装 Config Sync）。在设置标签页中，几分钟后，您应该会在舰队中集群的状态列中看到已启用。

部署软件包

将集群注册到舰队并安装 Config Sync 后，您可以配置 Config Sync 以从可靠来源将软件包部署到集群。您可以将同一软件包部署到多个集群，也可以将不同的软件包部署到不同的集群。您可以在部署软件包后对其进行修改，但软件包名称和同步类型等某些设置除外。如需了解详情，请参阅管理软件包。

如需部署软件包，请完成以下步骤：

在 Google Cloud 控制台中，前往 Config Sync 信息中心。

转到 Config Sync 信息中心
点击部署软件包。
在选择要部署软件包的集群表中，选择要部署软件包的集群，然后点击继续。
选择托管在 Git 上的软件包或托管在 OCI 上的软件包作为来源类型，然后点击继续。
在软件包详情部分，输入软件包名称，用于标识 RootSync 或 RepoSync 对象。
在 Sync type（同步类型）字段中，选择 Cluster scoped sync（集群级同步）或 Namespace scoped sync（命名空间级同步）作为同步类型。

集群级同步会创建 RootSync 对象，命名空间级同步会创建 RepoSync 对象。如需详细了解这些对象，请参阅 Config Sync 架构。
在来源部分，完成以下操作：
- 对于托管在 Git 代码库中的源代码，请输入以下字段：
  1. 输入您用作可靠来源的 Git 代码库的网址作为代码库网址。
  2. 可选：更新修订版本字段以检查您是否未使用默认的 HEAD。
  3. 可选：如果您不想从根代码库同步，请更新路径字段。
  4. 可选：如果您不使用默认 main 分支，请更新分支字段。
- 对于托管在 OCI 映像中的来源，请输入以下字段：
  1. 输入用作映像的可靠来源的 OCI 映像的网址。
  2. 输入要从中同步的目录的路径（相对于根目录）以作为目录。
（可选）：展开高级设置部分，完成以下操作：
1. 选择相应的身份验证类型。Config Sync 需要可靠来源的只读权限，才能读取来源中的配置文件并将它们应用于您的集群。除非您的来源不需要身份验证（例如公共代码库），否则请确保向 Config Sync 授予您的 Git 代码库、OCI 映像或 Helm 图表（仅限 gcloud CLI）的只读权限。选择您在安装 Config Sync 时配置的身份验证类型：
  
  注意：对于 OCI，您只能选择 Workload Identity 进行身份验证。
  - 无：不使用身份验证。
  - SSH：使用 SSH 密钥对进行身份验证。
  - Cookiefile：使用 cookiefile 进行身份验证。
  - 令牌：使用访问令牌或密码进行身份验证。
  - Google Cloud 代码库：使用 Google 服务账号访问 Cloud Source Repositories 代码库。请仅在集群中未启用 Workload Identity Federation for GKE 时选择此选项。
  - Workload Identity：使用 Google 服务账号访问 Cloud Source Repositories 代码库。
2. 输入数字（以秒为单位）以设置 Sync wait time（同步等待时间），这决定了 Config Sync 从可靠来源进行拉取的尝试之间的等待时间。
3. 输入 Git 代理网址，以便在与可靠来源通信时使用 HTTPS 代理。
4. 选择层次结构以更改来源格式。
  
  在大多数情况下，建议使用默认值非结构化，因为它支持您根据需要整理可靠来源。
点击部署软件包。

系统会将您重定向至 Config Sync 软件包页面。几分钟后，您应该会在配置的集群的同步状态列中看到已同步。

gcloud

在继续操作之前，请确保您已向舰队注册集群。

启用 ConfigManagement 舰队功能：

gcloud beta container fleet config-management enable

通过创建名为 apply-spec.yaml 的文件并将以下 YAML 文件复制到其中来准备配置。

您可以在创建清单时设置所需的所有可选 spec.configSync 字段，稍后再使用 kubectl 命令进行配置。您还可以将 spec.configSync.enabled 字段设置为 true，并省略可选字段。您随后可以使用 kubectl 命令创建其他 RootSync 对象或 RepoSync，以便日后使用 kubectl 命令进行全面管理。
```
# apply-spec.yaml

     applySpecVersion: 1
     spec:
       configSync:
         enabled: true
         # If you don't have a source of truth yet, omit the
         # following fields. You can configure them later.
         sourceType: SOURCE_TYPE
         sourceFormat: FORMAT
         syncRepo: REPO
         syncRev: REVISION
         secretType: SECRET_TYPE
         gcpServiceAccountEmail: EMAIL
         metricsGcpServiceAccountEmail: METRICS_EMAIL
         policyDir: DIRECTORY
         preventDrift: false
```
替换以下内容：
- SOURCE_TYPE：添加 git 以从 Git 代码库同步，添加 oci 以从 OCI 映像同步，或添加 helm 以从 Helm 图表同步。如果未指定任何值，则默认为 git。
- FORMAT：添加 unstructured 以使用非结构化代码库，或添加 hierarchy 以使用分层代码库。这些值区分大小写。此字段是可选字段，默认值为 hierarchy。我们建议您添加 unstructured，因为您可以采用这种格式以最适合您的方式整理配置。
- REPO：添加可靠来源的网址。Git 和 Helm 代码库网址使用 HTTPS 或 SSH 协议。例如 https://github.com/GoogleCloudPlatform/anthos-config-management-samples。如果您计划使用 SSH 作为 secretType，请使用 SSH 协议输入您的网址。此字段是必填字段；如果您不输入协议，则网址会被视为 HTTPS 网址。
  
  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
  注意：Config Sync 要求 OCI 层以 tar 或 tar+gzip 格式进行压缩。Config Sync 将无法识别其他格式（例如 tar+bz2）。如果从有效的 REPO 切换到格式不受支持的 OCI 映像，则系统将删除代管式资源，并且不会显示错误。
- REVISION：需与其同步的 Git 修订版本（标记或哈希）或是分支名称。使用哈希时，哈希必须是完整哈希，而不是缩写形式。
- SECRET_TYPE：以下 secretTypes 之一：
  git
  - none：不使用身份验证。
  - ssh：使用 SSH 密钥对。
  - cookiefile：使用 cookiefile。
  - token：使用令牌。
  - gcpserviceaccount：使用 Google 服务账号访问 Cloud Source Repositories 或 Secure Source Manager 代码库。如果您选择此身份验证类型，则需要在完成 Config Sync 配置后创建一个 IAM 政策绑定。如需了解详情，请参阅使用 Google 服务账号授予 Config Sync 对 Git 的访问权限部分中的 Google 服务账号标签页。
  - gcenode：使用 Google 服务账号访问 Cloud Source Repositories。请仅在集群中未启用 Workload Identity Federation for GKE 时选择此选项。
  - githubapp：使用 GitHub 应用向 GitHub 代码库进行身份验证。
  如需详细了解这些身份验证类型，请参阅授予 Config Sync 对 Git 的访问权限。
  oci
  - none：不使用身份验证
  - gcenode：使用 Compute Engine 默认服务账号访问 Artifact Registry 中的映像。请仅在集群中未启用 Workload Identity Federation for GKE 时选择此选项。
  - gcpserviceaccount：使用 Google 服务账号访问映像。
  Helm
  - token：使用令牌。
  - gcenode：使用 Compute Engine 默认服务账号访问 Artifact Registry 中的映像。请仅在集群中未启用 Workload Identity Federation for GKE 时选择此选项。
  - gcpserviceaccount：使用 Google 服务账号访问映像。
  - EMAIL：如果您已将 gcpserviceaccount 添加为 secretType，请添加您的 Google 服务账号电子邮件地址。例如 acm@PROJECT_ID.iam.gserviceaccount.com。
  - METRICS_EMAIL：用于将 Config Sync 指标导出到 Cloud Monitoring 的 Google Cloud服务账号 (GSA) 的电子邮件。GSA 应具有 Monitoring Metric Writer (roles/monitoring.metricWriter) IAM 角色。命名空间 config-management-monitoring 中的 Kubernetes ServiceAccount default 应绑定到 GSA。
  - DIRECTORY：要从中同步的目录的路径（相对于 Git 代码库的根目录）。您指定的目录的所有子目录都会包含在内并同步到集群。默认值为代码库的根目录。
如需查看可添加到 spec 字段的完整字段列表，请参阅 gcloud 字段。

注意：如果您尚未准备好可靠来源，可以将 spec.configSync.enabled 设置为 true 并省略所有其他 spec.configSync 字段，从而无需配置任何设置即可启用 Config Sync。准备好代码库后，修改 apply-spec.yaml 以添加配置设置。
应用 apply-spec.yaml 文件。如果您使用的是现有清单，则应将文件应用于您要使用上一条命令中提取的设置来配置的集群：
```
gcloud beta container fleet config-management apply \
    --membership=MEMBERSHIP_NAME \
    --config=CONFIG_YAML_PATH \
    --project=PROJECT_ID
```
替换以下内容：
- MEMBERSHIP_NAME：您在注册集群时选择的舰队成员资格名称。您可以通过 gcloud container fleet memberships list 找到该名称。
- CONFIG_YAML_PATH：apply-spec.yaml 文件的路径。
- PROJECT_ID：您的项目 ID。

Terraform

对于要配置 Config Sync 的每个集群，请应用包含 configmanagement 和 config_sync 块的 google_gkehub_feature_membership 资源块，如以下示例所示：

git

data "google_project" "default" {}

resource "google_container_cluster" "default" {
  name     = "gke-autopilot-basic"
  location = "us-central1"

  fleet {
    project = data.google_project.default.project_id
  }

  enable_autopilot = true
}

resource "google_gke_hub_feature" "configmanagement_feature" {
  name     = "configmanagement"
  location = "global"
}

resource "google_gke_hub_feature_membership" "configmanagement_feature_member" {
  location = "global"

  feature             = google_gke_hub_feature.configmanagement_feature.name
  membership          = google_container_cluster.default.fleet[0].membership_id
  membership_location = google_container_cluster.default.fleet[0].membership_location

  configmanagement {
    config_sync {
      # The field `enabled` was introduced in Terraform version 5.41.0, and
      # needs to be set to `true` explicitly to install Config Sync.
      enabled = true
      git {
        sync_repo   = "REPO"
        sync_branch = "BRANCH"
        policy_dir  = "DIRECTORY"
        secret_type = "SECRET"
      }
    }
  }
}

替换以下内容：

REPO：包含配置文件的 Git 代码库的网址。
BRANCH：代码库分支，例如 main。
DIRECTORY：Git 代码库中的路径，表示要同步的代码库的顶层目录。
SECRET：密钥身份验证类型。

oci

data "google_project" "default" {}

resource "google_container_cluster" "default" {
  name     = "gke-autopilot-basic"
  location = "us-central1"

  fleet {
    project = data.google_project.default.project_id
  }

  enable_autopilot = true
}

resource "google_gke_hub_feature" "configmanagement_feature" {
  name     = "configmanagement"
  location = "global"
}

resource "google_gke_hub_feature_membership" "configmanagement_feature_member" {
  location = "global"

  feature             = google_gke_hub_feature.configmanagement_feature.name
  membership          = google_container_cluster.default.fleet[0].membership_id
  membership_location = google_container_cluster.default.fleet[0].membership_location

  configmanagement {
    config_sync {
      # The field `enabled` was introduced in Terraform version 5.41.0, and
      # needs to be set to `true` explicitly to install Config Sync.
      enabled = true
      oci {
        sync_repo   = "REPO"
        policy_dir  = "DIRECTORY"
        secret_type = "SECRET"
      }
    }
  }
}

替换以下内容：

REPO：包含配置文件的 OCI 映像代码库的网址。
DIRECTORY：包含要同步的资源的目录的绝对路径。如需使用根目录，请将此字段留空。
SECRET：密钥身份验证类型。

对要同步的每个集群重复此过程。

如需详细了解如何使用 Terraform，请参阅针对 Config Sync 的 Terraform 支持。

配置根代码库后，您可以视需要配置从多个代码库同步，包括其他根代码库和命名空间代码库。如果您希望代码库中包含要跨集群同步到特定命名空间的命名空间级配置，则命名空间代码库非常有用。

验证安装

安装和配置 Config Sync 后，您可以验证安装是否成功完成。

gcloud

运行以下命令：

nomos status

成功安装后，状态会显示为 SYNCED 或 PENDING。

如需详细了解 nomos status 提供的信息（包括报告的错误），请参阅 nomos 命令行工具文档中的检查 Config Sync 状态。

控制台

请完成以下步骤：

在 Google Cloud 控制台中，前往功能部分下的配置页面。

转到“配置”

在软件包标签页上，检查集群表中的同步状态列。Config Sync 成功安装的状态为已安装。成功配置的可靠来源的状态为已同步。

后续步骤

了解如何升级 Config Sync。
详细了解用于配置 Config Sync 的 gcloud 命令。
了解如何配置从多个代码库同步。
使用 nomos 命令。
阅读 Config Sync 问题排查简介。
了解如何卸载 Config Sync。
查看默认 Config Sync 权限。