手动安装 Config Connector

本页面介绍了如何手动安装 Config Connector。 手动安装是一种灵活的选项，可让您控制已安装的版本和升级时间表。

如需详细了解不同的安装选项，请参阅选择安装类型。

对于大多数使用场景，我们建议以命名空间模式手动安装 Config Connector。另一种是集群模式。命名空间模式具有更高的可伸缩性，并提供更好的权限隔离，非常适合多租户使用情形或管理多个项目中的资源。

如果您希望使用单个集群范围的服务账号，请改为按照以集群模式安装的说明操作。

准备工作

在手动安装 Config Connector 运算符之前，请完成以下步骤：

• 创建或指定尚未安装 Config Connector 且启用了 Workload Identity 和 Kubernetes Engine Monitoring 的 GKE 集群。
• 配置 kubectl 以关联到您的集群。

安装 Config Connector Operator

Config Connector 使用 Kubernetes 运算符使其安装保持最新。无论您是以命名空间模式还是集群模式安装 Config Connector，都需要安装该 operator。

如需安装 Config Connector 运算符，请完成以下步骤：

1. 下载最新的 Config Connector Operator .tar 文件：

   gcloud storage cp gs://configconnector-operator/latest/release-bundle.tar.gz release-bundle.tar.gz
   

   注意： 请保留安装软件包的副本，因为您需要使用该软件包来卸载 Config Connector。

2. 解压缩 tar 文件：

   tar zxvf release-bundle.tar.gz
   

3. 在集群上安装 Config Connector Operator：

   Autopilot

   kubectl apply -f operator-system/autopilot-configconnector-operator.yaml
   

   标准

   kubectl apply -f operator-system/configconnector-operator.yaml
   

4. 如需将 Config Connector 运算符配置为在命名空间模式下运行，请完成以下步骤：

   1. 创建一个名为 configconnector.yaml 且包含以下内容的清单：

      apiVersion: core.cnrm.cloud.google.com/v1beta1
      kind: ConfigConnector
      metadata:
        # the name is restricted to ensure that there is only ConfigConnector resource installed in your cluster
        name: configconnector.core.cnrm.cloud.google.com
      spec:
        mode: namespaced
        stateIntoSpec: Absent
      

   2. 将清单应用到您的集群：

      kubectl apply -f configconnector.yaml
      

以命名空间模式安装 Config Connector

注意：您必须为想要 Config Connector 从其创建资源的每个命名空间执行这些步骤。

在以下部分中，您安装 Config Connector 的项目称为“宿主项目”。您可以让 Config Connector 管理资源的其他项目称为“代管式项目”。如果您希望 Config Connector 仅在与集群相同的项目中创建资源，则宿主项目和托管项目可以是同一项目。

创建命名空间

运行以下命令以创建新的命名空间：

kubectl create namespace NAMESPACE

将 NAMESPACE 替换为命名空间的名称。

创建身份

完成以下步骤，创建 Identity and Access Management (IAM) 服务账号并在 IAM 服务账号和 Config Connector Kubernetes 服务账号之间创建绑定：

1. 创建 IAM 服务账号。 如果您原本有一个服务账号，则可以使用原有的账号，而不必新建服务账号。通过运行以下命令，使用 gcloud 创建服务账号：

   gcloud iam service-accounts create NAMESPACE_GSA --project HOST_PROJECT_ID
   

   请替换以下内容：

   • 将 NAMESPACE_GSA 替换为绑定到命名空间的 Google 服务账号 (GSA) 的名称。
   • 将 HOST_PROJECT_ID 替换为您的宿主项目 ID。

   如需详细了解如何创建服务账号，请参阅创建和管理服务账号。

2. 向 IAM 服务账号授予对代管项目的提升权限：

   gcloud projects add-iam-policy-binding MANAGED_PROJECT_ID \
       --member="serviceAccount:NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com" \
       --role="roles/owner"
   

   将 MANAGED_PROJECT_ID 替换为您的托管项目 ID。

   注意： 如果您想授予对项目的编辑者访问权限，请将 roles/owner 替换为 roles/editor。 授予 Editor 角色将允许使用大部分 Config Connector 功能，但项目或组织范围内的配置除外（如 IAM 修改）。

3. 在 IAM 服务账号与 Config Connector Kubernetes 服务账号之间创建 IAM 政策绑定：

   gcloud iam service-accounts add-iam-policy-binding \
       NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com \
       --member="serviceAccount:HOST_PROJECT_ID.svc.id.goog[cnrm-system/cnrm-controller-manager-NAMESPACE]" \
       --role="roles/iam.workloadIdentityUser"
   

4. 向 IAM 服务账号授予在宿主项目上将 Prometheus 指标发布到 Google Cloud Observability 的权限：

   gcloud projects add-iam-policy-binding HOST_PROJECT_ID \
       --member="serviceAccount:NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com" \
       --role="roles/monitoring.metricWriter"
   

创建 ConfigConnectorContext

如需创建 Google Cloud 资源，请配置 Config Connector 以监视命名空间，具体方法是在该命名空间中添加 ConfigConnectorContext 对象。

要创建 ConfigConnectorContext，请完成以下步骤：

1. 创建一个名为 configconnectorcontext.yaml 且包含以下内容的清单：

   apiVersion: core.cnrm.cloud.google.com/v1beta1
   kind: ConfigConnectorContext
   metadata:
     # you need one ConfigConnectorContext per namespace
     name: configconnectorcontext.core.cnrm.cloud.google.com
     namespace: NAMESPACE
   spec:
     googleServiceAccount: "NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com"
     stateIntoSpec: Absent
   

2. 将清单应用到您的集群：

   kubectl apply -f configconnectorcontext.yaml
   

3. 运行以下命令，验证 Config Connector 运算符是否为您的命名空间创建了 Kubernetes 服务账号：

   kubectl get serviceaccount/cnrm-controller-manager-NAMESPACE  -n cnrm-system
   

4. 验证 Config Connector 控制器 Pod 是否正在为您的命名空间运行：

   kubectl wait -n cnrm-system \
       --for=condition=Ready pod \
       -l cnrm.cloud.google.com/component=cnrm-controller-manager \
       -l cnrm.cloud.google.com/scoped-namespace=NAMESPACE
   

   如果 Config Connector 控制器正在运行，则输出类似于：

   cnrm-controller-manager-abcdefghijk-0 condition met.
   

停止管理命名空间中的资源

如果您希望 Config Connector 停止管理命名空间中的资源，请移除该命名空间中的所有 Config Connector 资源和 ConfigConnectorContext 对象。

1. 如需查找命名空间中的所有 Config Connector 资源，请列出每个 Config Connector 自定义资源定义中的所有资源。

   kubectl get gcp -n NAMESPACE
   

   此命令的输出会列出该命名空间中代表由 Config Connector 管理的资源的所有自定义资源定义 (CRD)，包括相应资源的名称和 Kubernetes 种类。

2. 如需移除所有 Config Connector 资源，请针对上一步输出中的每个资源运行以下命令：

   kubectl delete -n NAMESPACE KIND NAME
   

   替换以下内容：

   • KIND：资源的 Kubernetes 种类。
   • NAME：资源的名称。

3. 删除命名空间中的 ConfigConnectorContext 对象。

   kubectl delete -n NAMESPACE ConfigConnectorContext configconnectorcontext.core.cnrm.cloud.google.com
   

   重要提示： 在删除所有由 Config Connector 管理的资源之前，请勿删除 ConfigConnectorContext 对象。

卸载 Config Connector

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

1. 如需移除 Config Connector CRD 和控制器组件，请运行以下命令：

   kubectl delete ConfigConnectorContext --all -A –wait=false
   
   kubectl delete ConfigConnector configconnector.core.cnrm.cloud.google.com \
       --wait=true
   

2. 如需卸载 Config Connector Operator，请运行以下命令：

   kubectl delete -f operator-system/configconnector-operator.yaml  --wait=true
   

以集群模式安装

如果您想管理单个项目中的资源，并且不需要命名空间模式提供的权限分离，则可能更倾向于以集群模式安装和管理 Config Connector。

创建身份

Config Connector 通过使用 Identity and Access Management (IAM) 服务账号进行身份验证以及使用 Workload Identity Federation for GKE 将 IAM 服务账号与 Kubernetes 服务账号绑定来创建和管理 Google Cloud 资源。

注意： 您只需为每个集群执行一次这些步骤。

如需创建身份，请完成以下步骤：

1. 创建 IAM 服务账号。 如果您希望使用现有服务账号，则可以使用该账号并跳过此步骤：

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
   

   将 SERVICE_ACCOUNT_NAME 替换为您的服务账号的名称。

   如需详细了解如何创建服务账号，请参阅创建和管理服务账号。

2. 向 IAM 服务账号授予对项目的提升权限：

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

   将 PROJECT_ID 替换为您的项目 ID。

   注意： 授予 Editor 角色将允许使用大部分 Config Connector 功能，但项目和组织范围内的配置除外（如 IAM 修改）。在生产环境中，我们建议您设置更精细的权限。 如需详细了解 IAM 角色，请参阅了解角色。

3. 在 IAM 服务账号与 Config Connector 运行的预定义 Kubernetes 服务账号之间创建 IAM 政策绑定：

   gcloud iam service-accounts add-iam-policy-binding \
   SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
     --member="serviceAccount:PROJECT_ID.svc.id.goog[cnrm-system/cnrm-controller-manager]" \
     --role="roles/iam.workloadIdentityUser"
   

配置 Config Connector

要完成安装，请为 ConfigConnector CustomResource 创建配置文件，然后使用 kubectl apply 命令应用该配置文件。Config Connector Operator 在集群中安装Google Cloud 资源 CRD 和 Config Connector 组件。

如需将操作员配置为集群模式，请完成以下步骤：

1. 将以下 YAML 文件复制到名为 configconnector.yaml 的文件中：

   # configconnector.yaml
   apiVersion: core.cnrm.cloud.google.com/v1beta1
   kind: ConfigConnector
   metadata:
     # the name is restricted to ensure that there is only one
     # ConfigConnector resource installed in your cluster
     name: configconnector.core.cnrm.cloud.google.com
   spec:
     mode: cluster
     googleServiceAccount: "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"
     # Setting `stateIntoSpec` to `Absent` is recommended. It means setting `cnrm.cloud.google.com/state-into-spec`
     # annotation to `absent` for all Config Connector resources created in the cluster in the future.
     # It prevents Config Connector from populating unspecified fields into the spec.
     stateIntoSpec: Absent

   替换以下内容：
   • 将 SERVICE_ACCOUNT_NAME 替换为您的服务账号的名称。
   • PROJECT_ID 替换为您的项目 ID。
2. 使用 kubectl apply 将配置应用到集群：

     kubectl apply -f configconnector.yaml

指定创建资源的位置

Config Connector 可以按项目、文件夹或组织整理资源，这与使用 Google Cloud整理资源的方式相同。

在使用 Config Connector 创建资源之前，必须先配置创建资源的位置。为了确定创建资源的位置，Config Connector 会在资源配置或现有命名空间中使用注释。如需了解详情，请参阅整理资源。

如果您没有可用于此目的的命名空间，请使用 kubectl 创建一个命名空间。

kubectl create namespace NAMESPACE

将 NAMESPACE 替换为您的命名空间名称。 例如 config-connector。

选择一个标签页以便选择 Config Connector 创建资源的位置。

项目

如需在特定项目中创建资源，请运行以下命令：

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/project-id=PROJECT_ID

请替换以下内容：

• 将 NAMESPACE 替换为您的命名空间名称。
• 将 PROJECT_ID 替换为您的 Google Cloud 项目 ID。

文件夹

如需在特定文件夹中创建资源，请运行以下命令：

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/folder-id=FOLDER_ID

请替换以下内容：

• 将 NAMESPACE 替换为您的命名空间名称。
• 将 FOLDER_ID 替换为您的 Google Cloud 文件夹 ID。

组织

如需在特定组织中创建资源，请运行以下命令：

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/organization-id=ORGANIZATION_ID

请替换以下内容：

• 将 NAMESPACE 替换为您的命名空间名称。
• 将 ORGANIZATION_ID 替换为您的 Google Cloud 组织 ID。

为命名空间添加注释时，Config Connector 将在相应的项目、文件夹或组织中创建资源。如需详细了解 Config Connector 如何使用 Kubernetes 命名空间，请参阅 Kubernetes 命名空间和 Google Cloud 项目。

验证安装

Config Connector 在命名空间 cnrm-system 中运行其所有组件。您可以通过运行以下命令来验证 Pod 是否准备就绪：

kubectl wait -n cnrm-system \
      --for=condition=Ready pod --all

如果正确安装了 Config Connector，则输出类似于以下内容：

pod/cnrm-controller-manager-0 condition met

注意：启动控制器 Pod 可能需要几分钟时间。

卸载 Config Connector

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

1. 如需移除 Config Connector CRD 和控制器组件，请运行以下命令：

   kubectl delete ConfigConnector configconnector.core.cnrm.cloud.google.com \
       --wait=true
   

2. 如需卸载 Config Connector Operator，请运行以下命令：

   kubectl delete -f operator-system/configconnector-operator.yaml  --wait=true
   

升级 Config Connector

如需下载并安装最新版本的 Config Connector Operator，请运行以下命令：

gcloud storage cp gs://configconnector-operator/latest/release-bundle.tar.gz release-bundle.tar.gz
tar zxvf release-bundle.tar.gz
kubectl apply -f operator-system/configconnector-operator.yaml

降级 Config Connector

不支持完全降级 Config Connector。如需同时降级 Config Connector Operator 和 CRD，您必须卸载并重新安装 Config Connector，然后重新应用资源。

在 Config Connector 1.123.1 版及更高版本中，您可以回滚使用命名空间模式的安装的运算符版本。在包含要回滚的操作的每个命名空间中，将 ConfigConnectorContext 对象中的 spec.version 字段设置为之前的 Config Connector 版本。

您可以将 Config Connector 控制器回滚最多 3 个次要版本。您必须始终回滚到给定次要版本的最新补丁版本。

从非 Operator 安装升级

Config Connector 1.33.0 版及更高版本仅支持使用 GKE 插件或 Operator 进行安装。

如需升级到 Operator（并保留所有 Config Connector 资源），您必须移除除 CRD 之外的所有 Config Connector 系统组件，然后安装 Operator。

1. 运行以下命令以移除 Config Connector 系统非 CRD 组件：

   kubectl delete sts,deploy,po,svc,roles,clusterroles,clusterrolebindings --all-namespaces -l cnrm.cloud.google.com/system=true --wait=true
   kubectl delete validatingwebhookconfiguration abandon-on-uninstall.cnrm.cloud.google.com --ignore-not-found --wait=true
   kubectl delete validatingwebhookconfiguration validating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true
   kubectl delete mutatingwebhookconfiguration mutating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true
   

2. 使用 GKE 插件或 Operator 安装 Config Connector。

从插件切换为手动安装

作为插件安装时，Config Connector 的版本与已安装的 GKE 版本直接相关。

手动安装可以加快更新速度，但需要进行手动升级。

如需切换安装方法并安全地保留资源，请完成以下步骤：

1. 停用插件，而不删除任何 ConfigConnector 或 ConfigConnectorContext 对象：

   gcloud container clusters update CLUSTER_NAME --update-addons ConfigConnector=DISABLED
   

   将 CLUSTER_NAME 替换为您在其中安装 Config Connector 的集群的名称。

2. 安装所选版本的手动 Operator。

   为防止出现潜在的 CRD 验证错误（例如 KNV2009: Invalid value: "v1beta1": must appear in spec.versions），所选的手动运算符版本必须与您之前用于插件的版本相同或更高。降级手动运算符版本可能会导致错误（例如 KNV2009），因为 GKE 插件可能已将某些 CRD 升级到较新的 Config Connector 版本。

注意： 由于 configconnector-operator-system 命名空间中的 namespace-id ConfigMap 在停用插件时会被删除，因此旧式 cnrm-controller-manager StatefulSets 已重新创建。

后续步骤

• Config Connector 使用入门。
• 了解 Config Connector 的最佳实践。