手动安装 Config Connector

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

本页面上的说明重点介绍如何在 Google Kubernetes Engine (GKE) 集群上安装 Config Connector。如需详细了解不同的安装选项,请参阅选择安装类型。

命名空间模式和集群模式的比较

对于大多数用例,您应在命名空间模式下手动安装 Config Connector。另一种是集群模式。命名空间模式更具可伸缩性,并提供更好的权限隔离,因此是多租户集群或跨多个项目管理资源的推荐模式。在多租户环境中,请避免使用集群模式。集群模式使用单个共享 Identity and Access Management (IAM) 服务账号。任何可以在任何命名空间中创建 Config Connector 资源的用户都可以使用该服务账号的完整 IAM 权限。

您可以在 ConfigConnector 对象的 spec.mode 字段中设置模式。下表总结了这两种模式之间的差异:

特征 命名空间模式(推荐) 集群模式
配置对象 一个集群级 ConfigConnector 对象和每个命名空间一个 ConfigConnectorContext 对象 一个集群级 ConfigConnector 对象
IAM 服务账号 在每个命名空间的 ConfigConnectorContext 对象中设置 在 ConfigConnector 对象中为集群设置一次
权限隔离 您可以隔离每个命名空间的 IAM 权限 所有命名空间共享一个服务账号的 IAM 权限
多项目管理 每个命名空间都可以为不同的项目使用不同的服务账号 一个服务账号管理所有项目中的资源
控制器 Pod 每个具有 ConfigConnectorContext 对象的命名空间都有一个控制器 Pod 一个控制器 Pod 对应所有命名空间

如需详细了解每种模式如何使用 IAM 服务账号,请参阅使用 IAM 进行访问权限控制。

如果您更喜欢使用单个集群级服务账号,请改为按照集群模式下的安装说明进行操作。

准备工作

在手动安装 Config Connector Operator 之前,请完成以下步骤:

安装 Config Connector Operator

Config Connector 使用 Kubernetes Operator 保持其安装最新。无论您是以命名空间模式还是集群模式安装 Config Connector,都需要安装 Operator。

如需安装 Config Connector Operator,请完成以下步骤:

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

    gcloud storage cp gs://configconnector-operator/latest/release-bundle.tar.gz release-bundle.tar.gz
    
  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 Operator 配置为在命名空间模式下运行,请完成以下步骤:

    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 仅在集群所属的项目中创建资源,则宿主项目和托管项目可以是同一项目。

创建命名空间

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

kubectl create namespace NAMESPACE

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

创建身份

通过完成以下步骤,创建 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." \
        --role="roles/owner"
    

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

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

    gcloud iam service-accounts add-iam-policy-binding \
        NAMESPACE_GSA@HOST_PROJECT_ID. \
        --member="serviceAccount:HOST_PROJECT_ID.[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." \
        --role="roles/monitoring.metricWriter"
    

创建 ConfigConnectorContext

如需创建 Google Cloud 资源,请通过在该命名空间中添加 ConfigConnectorContext 对象来配置 Config Connector 以监控命名空间。

要创建 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."
      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

如需卸载 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." \
      --role="roles/editor"
    

    将 PROJECT_ID 替换为您的项目 ID。

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

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

配置 Config Connector

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

如需将 Operator 配置为集群模式,请完成以下步骤:

  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."
      # 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

卸载 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 版及更高版本中,您可以为使用命名空间模式的安装回滚 Operator 版本。在每个具有要回滚的操作器的命名空间中,将 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),所选手动 Operator 的版本必须与您用于插件的版本相同或更高。降级手动 Operator 版本可能会导致错误(例如 KNV2009),因为 GKE 插件可能已将某些 CRD 升级到更高版本的 Config Connector。

后续步骤