安装 Config Sync

Config Sync Operator 是一个控制器，用于管理 Kubernetes 集群中的 Config Sync。请按照以下步骤在您要使用 Config Sync 管理的每个集群中安装并配置 Operator。

准备工作

本部分介绍了您在 GKE 上安装 Config Sync 之前必须满足的前提条件。

准备本地环境

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

安装并初始化 Cloud SDK，它提供了以下说明中使用的 gcloud、gsutil、kubectl、nomos 命令。如果您使用 Cloud Shell，则系统会预安装 Cloud SDK。
Cloud SDK 默认不安装 kubectl。如需安装 kubectl，请使用以下命令：
```
gcloud components install kubectl
```
使用 gcloud auth login 命令向 Google Cloud 进行身份验证，以便您可以下载 Config Sync 的组件。

准备集群

您的集群必须运行 GKE 1.14.x 或更高版本。

准备权限

安装 Config Sync 的 Google Cloud 用户需要 Identity and Access Management (IAM) 权限才能在集群中创建新角色。

注册集群

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

部署 Operator
向 Operator 授予对 Git 的只读权限
配置 Operator

部署 Operator

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

使用以下命令下载最新版本的 Operator CRD。若要改为下载特定版本，请参阅下载。

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

应用 CRD：

kubectl apply -f config-sync-operator.yaml

如果此操作失败，请参阅问题排查。

向 Operator 授予对 Git 的只读权限

Config Sync 需要 Git 代码库的只读权限，以便读取提交到代码库的配置，并将其应用到您的集群。如果需要凭据，则凭据会存储在每个注册集群的 git-creds Secret 中。

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

不过，大多数用户都需要创建凭据，因为对其代码库的读取权限会受到限制。Config Sync 支持以下身份验证机制：

SSH 密钥对
cookiefile
令牌
Google 服务帐号（仅限 Google Source Repository）

您选择的机制取决于您的代码库支持的内容。如果所有机制都可用，建议使用 SSH 密钥对。GitHub、Cloud Source Repositories、Bitbucket 都支持使用 SSH 密钥对。如果您的组织托管代码库，并且您不知道其支持哪些身份验证方法，请与您的管理员联系。

SSH 密钥对

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

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

创建 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，我们建议您使用一个单独的帐号。

注意：您必须创建不带密码的 SSH 密钥。Config Sync 不支持 SSH 密钥密码。
配置您的代码库以识别新创建的公钥。请参阅 Git 托管服务提供商的文档。为方便起见，我们提供了一些常用的 Git 托管服务提供商的说明：
- Cloud Source Repositories
- Bitbucket
- GitHub 我们建议您创建单独的部署密钥，以提供对单个 GitHub 代码库的只读权限。
- GitLab

将私钥添加到集群中的新 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 后缀的密钥）的名称。

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

cookiefile

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

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

创建并获取 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

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

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

令牌

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

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

使用 GitHub 或 Bitbucket 创建令牌。
- GitHub：创建 PAT。向令牌授予 repo 范围，以便其可以从私有代码库中读取内容。由于您将 PAT 绑定到 GitHub 帐号，因此我们还建议您创建机器用户并将 PAT 绑定到该机器用户。
- Bitbucket：创建应用专用密码。

创建并获取令牌后，将其添加到集群的新 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：添加您在上一步中创建的令牌。

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

Google 服务帐号

如果您的代码库在 Cloud Source Repositories 中，您可以使用 secretType: gcenode 向 Config Sync 授予对代管式集群所属项目中的代码库的访问权限。

前提条件

在开始之前，请确保满足以下前提条件。

集群中节点的访问权限范围必须包含 cloud-source-repos-ro。默认情况下，Compute Engine 默认服务帐号 PROJECT_ID-compute@developer.gserviceaccount.com 对同一项目的代码库拥有 source.reader 访问权限，但如果需要，您可以使用以下命令添加角色：
```
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
  --role roles/source.reader
```
替换以下内容：
- PROJECT_ID：添加您的组织的项目 ID。
- PROJECT_NUMBER：添加您的组织的项目编号。
集群中节点的访问权限范围必须包含 cloud-source-repos-ro。要添加此范围，您可以在创建集群时指定的 --scopes 列表中包含 cloud-source-repos-ro，或在创建集群时使用 cloud-platform 范围：
```
gcloud container clusters create example-cluster --scopes=cloud-platform
```

使用 Cloud Source Repositories 作为 SyncRepo

满足这些前提条件后，在配置 Operator 时将 spec.git.syncRepo 设置为所需 Cloud Source Repositories 的网址。

要使用 Cloud Source Repositories 作为 SyncRepo，请完成以下步骤：

列出所有代码库：
```
gcloud source repos list
```

在输出中，复制您要使用的代码库的网址：

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

将该网址添加为 syncRepo。例如：

spec.git.syncRepo: https://source.developers.google.com/p/my-project/r/my-repo-csr

将 Cloud Source Repositories 与 Workload Identity 搭配使用

如果在集群上启用了 Workload Identity，则需要执行其他步骤才能使用 secretType: gcenode。完成上述步骤并在以下部分配置 Config Sync 后，在 Kubernetes 服务帐号和 Google 服务帐号之间创建 IAM 政策绑定。在您首次配置 Config Sync 之前，系统不会创建 Kubernetes 服务帐号。

此绑定允许 Config Sync Kubernetes 服务帐号充当 Compute Engine 默认服务帐号：

gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[config-management-system/importer]" \
  PROJECT_NUMBER-compute@developer.gserviceaccount.com

替换以下内容： * PROJECT_ID：您的组织的项目 ID * PROJECT_NUMBER：您的组织的项目编号

创建绑定后，使用 Compute Engine 默认服务帐号的电子邮件地址将 annotation 添加到 Config Sync Kubernetes 服务帐号：

kubectl annotate serviceaccount -n config-management-system importer \
  iam.gke.io/gcp-service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

将 PROJECT_NUMBER 替换为您的组织的项目编号。

配置 Operator

如需配置 Config Sync 的行为，请为 ConfigManagement CustomResource 创建配置文件，然后使用 kubectl apply 命令应用该配置文件：

创建文件 config-management.yaml 并将以下 YAML 文件复制到其中。
```
# config-management.yaml

apiVersion: configmanagement.gke.io/v1
kind: ConfigManagement
metadata:
  name: config-management
spec:
  # clusterName is required and must be unique among all managed clusters
  clusterName: CLUSTER_NAME
  git:
    syncRepo: REPO
    syncBranch: BRANCH
    secretType: TYPE
    policyDir: "DIRECTORY"
```
替换以下内容：
- CLUSTER_NAME：添加您要应用此配置的已注册集群的名称。
- REPO：添加用作可靠来源的 Git 代码库的网址。此字段是必填字段。
- BRANCH：添加需与其同步的代码库分支。默认值为主分支。
- TYPE：添加以下某个 SecretTypes：
  - none
  - ssh
  - cookiefile
  - token
  - gcenode
- DIRECTORY：添加代码库中要同步的政策层次结构顶部的路径。默认值为代码库的根目录。
注意：如果要将 config-management.yaml 存储在 Git 代码库中，则必须将 policyDir 设置为一个子目录，并将所有配置放在该子目录中。请勿将 config-management.yaml 文件放在 policyDir 子目录中。

如需查看可添加到 spec 字段的字段的完整列表，请参阅以下适用于 Git 代码库的配置部分。请勿更改 spec 字段之外的配置值。
使用 kubectl apply 命令应用配置：
```
kubectl apply -f config-management.yaml
```
您可能需要为每个集群或每种类型的集群创建单独的配置文件。您可以使用 --context 选项指定集群：
```
kubectl apply -f config-management1.yaml --context=CLUSTER_NAME
```
将 CLUSTER_NAME 替换为您要使用的集群的名称。

适用于 Git 代码库的配置

键	说明
`spec.git.syncRepo`	用作可靠数据源的 Git 代码库的网址。必需。
`spec.git.syncBranch`	要从中同步的代码库的分支。默认值：`master`。
`spec.git.policyDir`	Git 代码库中的路径，表示要同步的代码库的顶层目录。默认值：代码库的根目录。
`spec.git.syncWait`	连续的同步操作之间的时长（以秒为单位）。默认值：15。
`spec.git.syncRev`	要获取的 Git 修订版本（标记或哈希）。默认值：HEAD。
`spec.git.secretType`	为访问 Git 代码库而配置的 Secret 类型，`ssh`、`cookiefile`、`token`、`gcenode` 或 `none` 之一。必需。
`spec.sourceFormat`	设置为 `unstructured` 时，配置 non-hierarchical repo。默认值：`hierarchy`。

Git 代码库的代理配置

如果贵组织的安全政策要求您通过 HTTP(S) 代理路由流量，则可以将 Config Sync 配置为使用代理的 URI 与 Git 主机进行通信。

键	说明
`spec.git.proxy.httpProxy`	httpProxy 定义了一个用于访问 Git 代码库的 HTTP_PROXY 环境变量。
`spec.git.proxy.httpsProxy`	httpsProxy 定义了一个用于访问 Git 代码库的 HTTPS_PROXY 环境变量。

如果同时指定了 httpProxy 和 httpsProxy 字段，则将忽略 httpProxy。

适用于 ConfigManagement 对象行为的配置

键	说明
`spec.clusterName`	集群的用户定义的名称，由 ClusterSelector 用来将集群组合在一起。在 Config Sync 安装环境中是唯一的。

验证安装

您可以使用 nomos status 命令检查 Operator 是否已成功安装。对于没有问题的有效安装，其状态为 PENDING 或 SYNCED。对于无效或不完整的安装，其状态为 NOT INSTALLED 或 NOT CONFIGURED。输出还包括报告的所有错误。

Operator 部署成功之后，将在位于 kube-system 命名空间中的名称以 config-management-operator 开头的 Pod 中运行。Pod 可能需要一些时间来初始化。验证 Pod 是否正在运行：

kubectl -n kube-system get pods | grep config-management

如果 Pod 正在运行，则命令的响应类似（但不等同于）如下所示：

config-management-operator-6f988f5fdd-4r7tr 1/1 Running 0 26s

您还可以验证 config-management-system 命名空间是否存在：

kubectl get ns | grep 'config-management-system'

此命令的输出类似如下所示：

config-management-system Active 1m

如果命令没有返回类似于此处所示内容的输出，请查看日志来了解出现的问题：

kubectl -n kube-system logs -l k8s-app=config-management-operator

您也可以使用 kubectl get events 检查 Config Sync 是否已创建任何事件。

kubectl get events -n kube-system

可能存在未被立即检测到的无效配置，例如 git-creds Secret 缺失或无效。如需了解问题排查步骤，请参阅本主题的“问题排查”部分中的有效但不正确的 ConfigManagement 对象。

升级 Config Sync 版本

本部分提供了有关升级到当前版本的一般说明。在升级之前，请先阅读版本说明，看看是否有任何特定的说明。

为每个注册的集群运行下文所述的命令。

下载新版本的 Operator 清单和 nomos 命令。
应用 Operator 清单：
```
kubectl apply -f config-sync-operator.yaml
```
此命令会更新 Operator 映像。Kubernetes 会检索新版本并使用新版本重启 Operator Pod。Operator 启动时，会运行一条协调循环语句 (reconcile loop)，用于应用新映像中捆绑的一组清单。这样会更新并重启每个组件 Pod。
将所有客户端上的 nomos 或 nomos.exe 命令替换为新版本。这样可以确保 nomos 命令始终能够获取所有注册集群的状态，并且能够验证这些集群的配置。

从集群中卸载 Operator

请按照以下说明从集群中卸载 Operator。对于您不想再使用 Config Sync 管理的每个集群，您必须按照以下步骤操作。

从集群中删除 ConfigManagement 对象：
```
kubectl delete configmanagement --all
```
该命令会进行以下操作：
- Config Sync 在集群中创建的任何 ClusterRole 和 ClusterRoleBinding 都将从集群中删除。
- Config Sync 安装的任何准入控制器配置都将被删除。
- 除了 git-creds Secret 以外，config-management-system 命名空间的内容将被删除。如果没有 config-management-system 命名空间，则 Config Sync 无法运行。由 Config Sync 创建或修改的任何 CustomResourceDefinition 都将从创建或修改了这些对象的集群中移除。运行 Operator 所需的 CustomResourceDefinition (CRD) 仍然存在，因为从 Kubernetes 的角度看，它们是由安装 Operator 的用户添加的。有关移除这些内容的信息将在下一步中介绍。
此时，Operator 仍然存在于您的集群中，但不执行任何操作。

如果您使用的是 GKE 并且决定不再需要使用 Config Sync，则可按照以下步骤卸载 Operator：
1. 在上一步中删除 ConfigManagement 对象后，验证 config-management-system 命名空间是否为空。等待直到 kubectl -n config-management-system get all 命令返回 No resources found.。
2. 删除 config-management-system 命名空间：
```
kubectl delete ns config-management-system
```
3. 删除 ConfigManagement CustomResourceDefinition：
```
kubectl delete crd configmanagements.configmanagement.gke.io
```
4. 删除 kube-system 命名空间中的所有 Config Sync 对象：
```
kubectl -n kube-system delete all -l k8s-app=config-management-operator
```

问题排查

以下几个部分将帮助您排查 Config Sync 安装问题。

CPU 不足

kubectl get events 的输出可能包含类型为 FailedScheduling 的事件。事件类似如下示例：

LAST SEEN   TYPE      REASON              OBJECT                                             MESSAGE
9s          Warning   FailedScheduling    pod/config-management-operator-74594dc8f6    0/1 nodes are available: 1 Insufficient cpu.

要修复此错误，请选择以下选项之一：

将节点添加到现有 GKE 节点池。
创建具有更大节点的节点池。

错误：尝试授予额外的特权

如果您收到以下错误：

Error from server (Forbidden): error when creating "config-sync-operator.yaml": clusterroles.rbac.authorization.k8s.io "config-management-operator" is forbidden: attempt to grant extra privileges: [...] ruleResolutionErrors=[]

（在您尝试应用 config-management-operator.yaml 文件时）则说明您拥有的权限少于安装所需的权限。【译者注：本处文字与上面的两段文字是一个整体】查看准备权限，以确保您拥有所需权限。

有效但不正确的 ConfigManagement 对象

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

对于没有问题的有效安装，其状态为 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 后立即检测到它，这样您就无需重新应用配置。

后续步骤

试用快速入门。
了解如何创建配置。
使用 nomos 命令。