Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Config Connector 控制器类型

Config Connector 采用分层架构，用于协调Google Cloud 环境中的资源与 Kubernetes 规范。顶级父控制器会将每个资源的协调路由到四个底层控制器实现之一。

了解每种控制器类型、它们在技术上的差异以及如何控制命名空间范围的路由，有助于您优化性能并排查配置问题。

底层控制器类型

Config Connector 使用以下控制器类型：

直接控制器：此控制器使用标准 Kubernetes controller-runtime 库，并使用官方 Google Cloud Go SDK 直接与 Google Cloud API 通信。我们建议您尽可能使用直接控制器。并非所有资源都支持直接控制器。新资源默认使用直接控制器。现有资源会定期迁移。如需了解详情，请参阅版本说明。
基于 Terraform 的控制器 (TF)：此控制器充当 Terraform Google 提供程序的“封装容器”。该控制器将 Kubernetes 资源模型 (KRM) 规范转换为与 Terraform 兼容的状态，并实现 plan 和 apply Terraform 操作。
基于 DCL 的控制器：此类控制器充当Google Cloud 声明性客户端库 (DCL) 的“封装容器”。
特定于 IAM 的控制器：这些是专门设计的控制器，用于管理 Identity and Access Management (IAM) 资源，包括 IAMPolicy、IAMPartialPolicy、IAMPolicyMember 和 IAMAuditConfig。部分 IAM 资源可选择性地支持直接控制器。

直接控制器的优势

某些资源类型支持多种控制器类型。如果资源支持直接控制器，我们建议您使用直接控制器，而不是其他控制器类型，原因如下：

降低资源消耗：直接控制器没有与运行和转换基于 Terraform 或基于 DCL 的状态相关的 CPU 和内存开销。
缩短了协调延迟时间：直接控制器可针对 Google Cloud 端点执行直接操作，从而缩短达到资源状态一致性所需的平均时间。
精细的状态和结构化差异：直接控制器在 cnrm-controller-manager 日志中提供结构化差异报告。这些日志包含引发调和循环等错误的精确字段更改，有助于您更轻松地排查问题。
原生观测状态：直接控制器会在资源状态中填充 status.observedState，从而提供由Google Cloud API 直接返回的资源字段的透明服务器端视图。
改进了生命周期处理：直接控制器包含其他功能，例如正常孤立删除。

父级路由控制器

无论资源类型如何，Config Connector 都会在中央父控制器中拦截所有协调请求。父控制器充当路由器，通过以下优先级规则评估哪个子逻辑处理有效同步：

命名空间替换：父控制器首先会检查目标资源命名空间中的 ConfigConnectorContext 资源配置，以查找任何显式控制器替换。
静态默认值：如果未指定任何本地替换项，父控制器将默认使用在 Config Connector 静态映射配置中定义的 build-time reconciler。

确定资源的控制器

您可以通过使用有效代码映射或检查 Google Kubernetes Engine (GKE) 中的 CustomResourceDefinition (CRD) 结构，确定为特定Google Cloud 资源配置或激活的控制器类型。

如需查找资源的静态配置，请在 GitHub 上检查 pkg/controller/resourceconfig/static_config.go 中的资源，并查找资源的配置块，例如以下示例：

{Group: "alloydb.cnrm.cloud.google.com", Kind: "AlloyDBCluster"}: {
    DefaultController:    k8s.ReconcilerTypeTerraform,
    SupportedControllers: []k8s.ReconcilerType{k8s.ReconcilerTypeDirect, k8s.ReconcilerTypeTerraform},
}

DefaultController：表示在未指定任何命名空间级上下文替换规则时使用的默认协调器。
SupportedControllers：列出已实现并可用于此资源的所有协调器。覆盖切换到此处列出的协调器。

如需检查 CRD 标签，请使用 kubectl get crd 命令：

kubectl get crd RESOURCE_NAME -o jsonpath='{.metadata.labels}'

将 RESOURCE_NAME 替换为 Config Connector CRD 的确切名称，例如 bigquerydatasets.bigquery.cnrm.cloud.google.com。

检查结果中是否包含以下信息：

cnrm.cloud.google.com/tf2crd: "true"：基于 Terraform (TF) 的控制器管理资源。
cnrm.cloud.google.com/dcl2crd: "true"：基于 DCL 的控制器管理资源。
缺少这些标签：直接控制器管理资源。

替换默认控制器

在 Config Connector 中，有两种主要方法可用于替换控制器类型。这两种方法的主要区别在于其操作范围、维护开销以及在协调期间所采用的优先级。

下表总结了这两种方法之间的差异：

功能	资源注解	ConfigConnectorContext 替换
范围	单个资源实例	命名空间中某种类型的所有资源
优先级	最高（替换 ConfigConnectorContext）	中（覆盖静态默认值）
推荐？	否	是
适用场景	一次性测试	团队或项目范围内的推出

替换特定资源的控制器

您可以通过向资源元数据添加 alpha.cnrm.cloud.google.com/reconciler 注解，强制特定资源实例使用特定协调器运行。虽然出于上一部分中指定的原因，我们不建议采用此方法，但您可能需要使用此方法来测试单个资源实例的配置或维护旧版配置。

apiVersion: bigquery.cnrm.cloud.google.com/v1beta1
kind: BigQueryDataset
metadata:
  name: my-bq-ds
  namespace: NAMESPACE_NAME
  annotations:
    alpha.cnrm.cloud.google.com/reconciler: direct
spec:
  ...

注解支持的值包括 direct、tf 或 dcl。

替换命名空间的控制器

如需使用 ConfigConnectorContext 自定义资源配置命名空间范围的替换，请完成以下步骤：

从资源定义中检索名称和群组。例如，对于 BigQueryDataset 资源，资源种类为 BigQueryDataset，组为 bigquery.cnrm.cloud.google.com。
修改包含受管理资源的命名空间内的 ConfigConnectorContext 对象：
```
kubectl edit configconnectorcontext configconnectorcontext.core.cnrm.cloud.google.com -n NAMESPACE_NAME
```
将 NAMESPACE_NAME 替换为您的目标命名空间。

添加目标替换项。例如，如需替换此命名空间中的所有 BigQueryDataset 实例以使用直接控制器运行，请按如下方式定义配置：

apiVersion: core.cnrm.cloud.google.com/v1beta1
kind: ConfigConnectorContext
metadata:
  name: configconnectorcontext.core.cnrm.cloud.google.com
  namespace: NAMESPACE_NAME
spec:
  googleServiceAccount: "kcc-sa@my-project.iam.gserviceaccount.com"
  experiments:
    controllerOverrides:
      BigQueryDataset.bigquery.cnrm.cloud.google.com: direct

保存并应用资源。父控制器会自动将新的直接协调器路由规则动态应用于此命名空间中的所有匹配资源。

命名空间替换限制和用例

明确的支持要求：如需成功进行替换，必须针对资源种类实现目标控制器类型。如需查看是否支持某种控制器类型，请参阅确定资源的控制器。如果您在替换中指定的控制器类型不受支持，父控制器会忽略替换，默认协调器会继续处理资源。
命名空间限制：ConfigConnectorContext 下的替换项会统一应用于位于相应特定命名空间内的相应资源类型的所有实例。您无法使用命名空间范围的替换项来定位单个资源实例。
访问权限控制：与标准资源编辑相比，更新 ConfigConnectorContext 对象通常需要更高级别的平台团队权限。
替换状态报告：如果在 ConfigConnectorContext 替换项中指定了无效或不受支持的控制器类型，父控制器会将上下文标记为不健康。您可以通过运行 kubectl get configconnectorcontext configconnectorcontext.core.cnrm.cloud.google.com -n NAMESPACE_NAME -o yaml 并检查 .status.healthy 和 .status.errors 字段来验证这一点。
使用场景：这是覆盖控制器的推荐方法。您可以使用它来选择让整个命名空间使用新式控制器（例如直接控制器），或者在整个项目中强制执行架构一致性。