管理现有集群对象

当 Config Sync 管理集群对象时，它会监视代码库中影响此对象的配置组，并确保它们始终同步。本主题介绍如何开始管理现有对象以及如何停止管理当前受管理的对象而不删除该对象。

如果集群中某个对象具有 configmanagement.gke.io/managed: enabled 注释并且其 configsync.gke.io/resource-id 注释正确（该注释跟踪对象的组、种类、命名空间和名称信息），则该对象由 Config Sync 管理。

命名空间级对象的 configsync.gke.io/resource-id 注释的格式为 GROUP_KIND_NAMESPACE_NAME，集群级对象的格式为 GROUP_KIND_NAME。

以下流程图描述了导致对象变为受管或非受管对象的一些情况：

如何使用 Config Sync 管理或取消管理 Kubernetes 对象

该图包含三个独立的流：1) 开始管理对象，2) 停止管理对象，3) 删除受管对象。

  1. 我想开始管理对象。此对象具有清单吗？换句话说，该对象在代码库中是否有配置？
    • 否：请为此对象创建配置。Config Sync 设置注释 configmanagement.gke.io/managed: enabled，设置 configsync.gke.io/resource-id 注释以与对象匹配，然后开始管理对象。
    • 是：配置是否设置了以下注释？ configmanagement.gke.io/managed: disabled
      • 否：默认情况下管理该对象。
      • 是：修改配置以移除 configmanagement.gke.io/managed: disabled 注释。更改被推送到源代码库后，Config Sync 会发现更改，应用注释 configmanagement.gke.io/managed: enabled 和 configsync.gke.io/resource-id，然后应用配置。
  2. 我想停止管理对象，但不想将其删除。
    • 在代码库中修改该对象的配置，并设置注释 configmanagement.gke.io/managed: disabled。检测到配置更改时，Config Sync 会停止管理该对象。
  3. 我想停止管理对象并将其删除。
    • 从代码库中删除该对象的配置。当您删除先前管理的对象的配置时，Config Sync 将从该配置适用的所有集群或命名空间中删除该对象。

除了 configmanagement.gke.io/managed: enabled 注释和 configsync.gke.io/resource-id 注释之外，Config Sync 还将标签 app.kubernetes.io/managed-by: configmanagement.gke.io 应用于其管理的所有对象。使用此标签，您可以轻松列出 Config Sync 管理的所有对象。

为什么不手动应用注释？

Config Sync 使用声明式模型，通过从代码库中读取所需的配置，将配置更改应用于集群。如果您尝试手动应用注释（使用 kubectl 命令或 Kubernetes API），则 Config Sync 会自动使用代码库的内容覆盖手动应用的注释。

准备工作

以下示例是基于 Config Sync 使用入门构建的。在开始执行以下步骤之前，请按照快速入门执行操作并完成探索和测试 Config Sync 安装之前的所有步骤。

列出所有受管对象

如需列出给定集群或命名空间上由 Config Sync 管理的所有对象，请使用如下所示的标签选择器：

kubectl get object-type -n namespace -l "app.kubernetes.io/managed-by=configmanagement.gke.io"

如需列出未受 Config Sync 管理的所有对象，请使用如下所示的标签选择器：

kubectl get object-type -n namespace -l "app.kubernetes.io/managed-by!=configmanagement.gke.io"

例如，以下命令列出了 gamestore 命名空间中受 Config Sync 管理的 RoleBinding：

kubectl get rolebindings -n gamestore \
    -l "app.kubernetes.io/managed-by=configmanagement.gke.io"

输出内容类似如下：

NAME                              ROLE                                          AGE
configsync.gke.io:ns-reconciler   ClusterRole/configsync.gke.io:ns-reconciler   34h
gamestore-admin                   ClusterRole/admin                             34h
gamestore-webstore-admin          ClusterRole/webstore-admin                    34h

以下命令列出了 kube-system 命名空间中未受 Config Sync 管理的 RoleBinding：

kubectl get rolebindings -n kube-system \
    -l "app.kubernetes.io/managed-by!=configmanagement.gke.io"

输出内容类似如下：

NAME                                             AGE
fluentd-gcp-scaler-binding                       2d21h
gce:cloud-provider                               2d21h
heapster-binding                                 2d21h
metrics-server-auth-reader                       2d21h
system::leader-locking-kube-controller-manager   2d21h
system::leader-locking-kube-scheduler            2d21h
system:controller:bootstrap-signer               2d21h
system:controller:cloud-provider                 2d21h
system:controller:token-cleaner                  2d21h

开始管理现有对象

在安装 Config Sync 之前，您可以为现有 Kubernetes 对象（例如集群中已存在的命名空间）创建配置。但是，除非对象具有注释 configmanagement.gke.io/managed: enabled 并且具有正确的 configsync.gke.io/resource-id 注释，否则此配置将被忽略。对于现有对象，您需要手动应用该注释。

需要特别注意的是，对于命名空间对象，Config Sync 将应用可在未加注释的命名空间中创建新对象的配置，并将 configmanagement.gke.io/managed: enabled 和 configsync.gke.io/resource-id 注释应用于这些对象。但是，Config Sync 会拒绝修改或移除集群中任何未加注释的集群级对象。这种情况在处理一段时间内的配置更改部分的图表中进行了说明。

以下示例演示了如何管理现有角色对象。首先，您需要手动创建一个角色，然后开始使用 Config Sync 管理该角色。

  1. 在 gamestore 命名空间中创建 myrole 角色：

    kubectl create role -n gamestore myrole --verb=get --resource=pods

  2. 查看 myrole 角色授予的权限：

    kubectl describe role -n gamestore myrole
     
    Name:         myrole
Labels:       <none>
Annotations:  <none>
PolicyRule:
  Resources  Non-Resource URLs  Resource Names  Verbs
  ---------  -----------------  --------------  -----
  pods       []                 []              [get]

    此角色仅有权 get Pod。

  3. 此时，该角色存在于集群中，但 Config Sync 不知道该角色。

    1. 在终端中，前往您的代码库的本地克隆。

    2. 使用以下命令为 myrole 创建 YAML 清单，并将此清单保存到名为 gamestore-myrole.yaml 的新文件中。

      kubectl get role myrole -n gamestore -o yaml > gamestore-myrole.yaml

    3. 修改 gamestore-myrole.yaml 文件。

      1. 移除 metadata 键下除 name 和 namespace 以外的其他所有字段。
      2. 在 rules.verbs 列表字段中的 get 后添加 list 谓词。

      保存更改。生成的文件包含以下内容：

      apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: myrole
  namespace: gamestore
rules:
- apiGroups:
  - ""
  resources:
  - pods
  verbs:
  - get
  - list

    4. 将更改提交至代码库。

    5. ConfigManagement Operator 注意到提交需要一些时间，请稍等片刻。要验证 myrole 角色现在是否受 Config Sync 管理，请再次运行 kubectl describe。

      kubectl describe role myrole -n gamestore

请注意注释 configmanagement.gke.io/managed: enabled，它表示对象受 Config Sync 管理；以及注释 configsync.gke.io/resource-id，它跟踪组、种类、命名空间和名称信息。另请注意显示代码库中路径和文件名的注释（对象最近发生的配置更改由这些注释导致）以及表示提交的 Git 哈希。

Name:         myrole
Labels:       app.kubernetes.io/managed-by=configmanagement.gke.io
              configsync.gke.io/declared-version=v1
Annotations:  config.k8s.io/owning-inventory: config-management-system_root-sync
              configmanagement.gke.io/cluster-name: my-cluster
              configmanagement.gke.io/managed: enabled
              configmanagement.gke.io/source-path: config-sync-quickstart/multirepo/root/gamestore-myrole.yaml
              configmanagement.gke.io/token: 747b843a7ddbd945c0616034a935cf648b58e7b5
              configsync.gke.io/declared-fields: {"f:rules":{}}
              configsync.gke.io/git-context: {"repo":"https://github.com/GoogleCloudPlatform/anthos-config-management-samples","branch":"main","rev":"HEAD"}
              configsync.gke.io/manager: :root
              configsync.gke.io/resource-id: rbac.authorization.k8s.io_role_gamestore_myrole
PolicyRule:
  Resources  Non-Resource URLs  Resource Names  Verbs
  ---------  -----------------  --------------  -----
  pods       []                 []              [get list]

停止管理代管式对象

此示例演示了如何停止管理 Config Sync 目前正在管理的对象，例如开始管理现有对象中所述的 myrole 角色。

  1. 修改您的代码库本地克隆中的 config-sync-quickstart/multirepo/root/rolebinding-gamestore-webstore-admin.yaml 文件，然后添加与以下粗体字匹配的 annotations: 部分：

     kind: RoleBinding
 apiVersion: rbac.authorization.k8s.io/v1
 metadata:
   annotations:
     configmanagement.gke.io/managed: disabled
   name: gamestore-webstore-admin
   namespace: gamestore
 subjects:
 - kind: ServiceAccount
   name: ns-reconciler-gamestore
   namespace: config-management-system
 roleRef:
   kind: ClusterRole
   name: webstore-admin
   apiGroup: rbac.authorization.k8s.io

    保存文件。

  2. 根据您的更改创建 Git 提交，并将提交推送到您的代码库。

  3. Config Sync 发现和应用新提交需要一些时间，请稍等片刻。

  4. 使用以下命令验证 gamestore-webstore-admin RoleBinding 的注释和标签是否为空。Config Sync 不会在对象上将 configmanagement.gke.io/managed 注释设置为 disabled。

    kubectl get rolebinding gamestore-webstore-admin -n gamestore -o yaml

    apiVersion: rbac.authorization.k8s.io/v1
metadata:
  annotations:
  name: gamestore-webstore-admin
  namespace: gamestore
subjects:
- kind: ServiceAccount
  name: ns-reconciler-gamestore
  namespace: config-management-system
roleRef:
  kind: ClusterRole
  name: webstore-admin
  apiGroup: rbac.authorization.k8s.io

验证该对象现已停用后，您可以从代码库中移除该配置，并验证这个当前不受管理的对象是否未从命名空间中删除。如果要再次管理该对象，则必须将其配置添加回您的代码库。因此，您可能要取消管理对象，并将其配置保留在代码库中。

由于对象不受管理，因此新集群或现有集群上不会创建或重新创建对象，并且即使对象已存在也不会被移除。如需继续管理您先前已停止管理的对象，请参阅下一个示例：继续管理先前已停止管理的对象。

继续管理先前已停止管理的对象

此示例演示如何继续管理如停止管理现有对象部分中所述，先前从管理中移除的对象。此示例假设您未移除 gamestore-webstore-admin RoleBinding 的配置。

  1. 如果您在上次提交时从您的代码库中删除了 gamestore-webstore-admin RoleBinding，请执行以下步骤。

    1. 使用 git revert 还原上次提交：

      git revert HEAD~1

      系统会要求您确认还原操作。

    2. 将还原提交推送到您的代码库中。

      git push

  2. 修改您的代码库本地克隆中的 config-sync-quickstart/multirepo/root/rolebinding-gamestore-webstore-admin.yaml 文件并移除 configmanagement.gke.io/managed: disabled 注释。保存文件。

  3. 提交并推送您的更改。Config Sync 会执行以下操作：

    • 注意更改
    • 应用 configmanagement.gke.io/managed: enabled 注释和 configsync.gke.io/resource-id 注释；此对象现已受管理。
    • 应用配置，正如任何受管对象一样。

  4. 如需验证该对象现在是否已经受到管理，请列出其注释：

    kubectl get rolebinding gamestore-webstore-admin -n gamestore -o yaml
     
    apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  annotations:
    configmanagement.gke.io/cluster-name: my-cluster
    configmanagement.gke.io/managed: enabled
    configsync.gke.io/resource-id: rbac.authorization.k8s.io_rolebinding_gamestore_gamestore-webstore-admin
...

停止管理命名空间

您可以采用与停止管理任意类型的对象相同的方式停止管理命名空间。如果要停止管理命名空间中的其他资源，请执行以下步骤：

  1. 将 configmanagement.gke.io/managed:disabled 注释添加到命名空间配置和同一命名空间中的所有配置。 命名空间中的所有对象都必须具有此注解。

  2. 提交更改并将更改推送到代码库。等待 Operator 与代码库同步。

  3. 从代码库中删除不受管理的资源。

如果代管式配置的配置存在于非代管式命名空间目录中，则协调器会记录错误，但其他配置会继续正常同步。

删除代管式资源

如果您从可靠来源中移除单个资源，当 Config Sync 接下来从可靠来源同步时，该对象将从集群中删除。或者，您可以启用删除传播，以便批量删除对象。

逐个删除对象

Config Sync 采用默认行为时，您从可靠来源中移除对象后，当 Config Sync 从可靠来源同步时，该对象将从集群中删除。

您可以使用多种方法检查 Config Sync 的状态或特定对象的状态：

批量删除对象

默认情况下，删除 RootSync 或 RepoSync 会导致 Config Sync 放弃之前从可靠来源应用的对象。或者，您可以启用删除传播，以删除所有先前应用的对象。

如果您在 RootSync 或 RepoSync 对象上启用删除传播，然后删除该对象，则 Config Sync 会自动删除该 RootSync 或 RepoSync 管理的每个对象。

删除传播可以帮助您在需要时更轻松地清理资源，例如，您要迁移到新的命名空间或集群、在演示或实验后需要清理资源，或是要卸载应用。

删除传播选项

删除传播默认处于停用状态。如需启用删除传播，请将 configsync.gke.io/deletion-propagation-policy: Foreground 注解添加到 RootSync 或 RepoSync 对象，如以下示例所示：

# example-rootsync.yaml
apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: example-rootsync
  namespace: config-management-system
  annotations:
    configsync.gke.io/deletion-propagation-policy: Foreground
spec:
  sourceType: git
  sourceFormat: unstructured
  git:
    repo: https://github.com/GoogleCloudPlatform/anthos-config-management-samples
    branch: init
    dir: config-sync-quickstart/multirepo/root
    auth: none
    period: 30s

或者，您可以通过运行以下命令来更新现有 RootSync 或 RepoSync 以使用删除传播：

RootSync

kubectl patch RootSync ROOTSYNC_NAME \
  --namespace config-management-system \
  --type merge \
  --patch '{"metadata":{"annotations":{"configsync.gke.io/deletion-propagation-policy":"Foreground"}}}'

将 ROOTSYNC_NAME 替换为您要更新的 RootSync 的名称。

RepoSync

kubectl patch RepoSync REPOSYNC_NAME \
  --namespace config-management-system \
  --type merge \
  --patch '{"metadata":{"annotations":{"configsync.gke.io/deletion-propagation-policy":"Foreground"}}}'

将 REPOSYNC_NAME 替换为您要更新的 RepoSync 的名称。

如需停用删除传播，请移除注解或将值更改为 configsync.gke.io/deletion-propagation-policy: Orphan：

RootSync

kubectl patch RootSync ROOTSYNC_NAME \
  --namespace config-management-system \
  --type merge \
  --patch '{"metadata":{"annotations":{"configsync.gke.io/deletion-propagation-policy":"Orphan"}}}'

将 ROOTSYNC_NAME 替换为您要更新的 RootSync 的名称。

RepoSync

kubectl patch RepoSync REPOSYNC_NAME \
  --namespace config-management-system \
  --type merge \
  --patch '{"metadata":{"annotations":{"configsync.gke.io/deletion-propagation-policy":"Orphan"}}}'

传播对象删除

此示例展示了如何对 RootSync 或 RepoSync 对象应用删除传播，然后删除 RootSync 或 RepoSync 以删除 RootSync 或 RepoSync 管理的所有对象。

RootSync

  1. 将注解应用于 RootSync 对象以启用删除传播：

    kubectl patch RootSync example-rootsync \
  --namespace config-management-system \
  --type merge \
  --patch '{"metadata":{"annotations":{"configsync.gke.io/deletion-propagation-policy":"Foreground"}}}'

  2. 删除 RootSync 对象，并等待 Config Sync 将其删除：

    kubectl delete RootSync example-rootsync --namespace config-management-system --wait

    删除 RootSync 可能需要几分钟时间才能完成。

RepoSync

  1. 将注解应用于 RepoSync 对象以启用删除传播：

    kubectl patch RepoSync example-reposync \
  --namespace example-namespace \
  --type merge \
  --patch '{"metadata":{"annotations":{"configsync.gke.io/deletion-propagation-policy":"Foreground"}}}'

  2. 删除 RepoSync 对象，并等待 Config Sync 将其删除：

    kubectl delete RepoSync example-reposync --namespace example-namespace --wait

    删除 RepoSync 可能需要几分钟时间才能完成。

防止删除 Kubernetes 对象

从由 Config Sync 管理的 Git 代码库中移除 Kubernetes 对象后，当新提交内容同步到集群时，该对象也会从集群中删除。

如果您希望防止 Config Sync 从 Git 代码库中移除对象配置后删除对象，则可以执行以下步骤：

  1. 将注解 client.lifecycle.config.k8s.io/deletion: detach 添加到 Git 代码库中的对象配置。

  2. 提交并推送 Git 代码库中的更改。

  3. 等待更改同步到集群。

完成这些步骤后，当 Config Sync 从 Git 代码库中移除对象配置后，不会从集群中删除此对象，但其他客户端仍然可以删除该对象。

忽略可靠来源中的对象

您可能希望 Config Sync 忽略可靠来源中的对象。 例如，绝对不应将 kpt 函数配置应用于集群。

对于您希望 Config Sync 忽略的对象，请向该对象添加 config.kubernetes.io/local-config: "true" 注解。添加此注释后，Config Sync 会忽略此对象，就好像已从可靠来源中移除了这个对象。如果资源将 local-config 注释设置为 "false" 以外的任何值，都将该资源视为设置为 "true" 并忽略。