Tipos de controladores de Config Connector

Config Connector usa una arquitectura en capas para conciliar los recursos en tu entorno deGoogle Cloud con tus especificaciones de Kubernetes. Un controlador principal de nivel superior enruta la reconciliación de cada recurso a una de las cuatro implementaciones de controladores subyacentes.

Comprender cada tipo de controlador, cómo difieren técnicamente y cómo puedes controlar el enrutamiento en todo el espacio de nombres puede ayudarte a optimizar el rendimiento y solucionar problemas de configuración.

Tipos de controladores subyacentes

Config Connector usa los siguientes tipos de controladores:

  • Controladores directos: Este controlador usa la biblioteca estándar de Kubernetescontroller-runtime y se comunica con las APIs de Google Cloud directamente a través de los SDKs oficiales de Google Cloud Go. Te recomendamos que uses controladores directos siempre que sea posible. No todos los recursos admiten el controlador directo. Los recursos nuevos usan el controlador directo de forma predeterminada. Los recursos existentes se migran con regularidad. Para obtener más información, consulta las notas de la versión.
  • Controladores basados en Terraform (TF): Este controlador actúa como un "wrapper" para el proveedor de Google de Terraform. El controlador traduce las especificaciones del modelo de recursos de Kubernetes (KRM) en estados compatibles con Terraform y, además, implementa las operaciones de Terraform plan y apply.
  • Controladores basados en DCL: Este tipo de controlador actúa como un "wrapper" para laGoogle Cloud biblioteca cliente declarativa (DCL).
  • Controladores específicos de IAM: Son controladores especializados diseñados específicamente para administrar recursos de Identity and Access Management (IAM), incluidos IAMPolicy, IAMPartialPolicy, IAMPolicyMember y IAMAuditConfig. Algunos recursos de IAM admiten de forma opcional el controlador directo.

Beneficios de los controladores directos

Algunos tipos de recursos admiten varios tipos de controladores. Si un recurso admite el controlador directo, te recomendamos que uses el controlador directo en lugar de otro tipo de controlador por los siguientes motivos:

  • Menor consumo de recursos: Los controladores directos no tienen la sobrecarga de CPU y memoria asociada con la ejecución y la traducción de estados basados en Terraform o en DCL.
  • Mejora de la latencia de conciliación: Los controladores directos pueden realizar operaciones directas en los endpoints de Google Cloud , lo que reduce el tiempo promedio necesario para alcanzar la coherencia del estado del recurso.
  • Estado detallado y diferencias estructuradas: El controlador directo proporciona informes de diferencias estructuradas en los registros de cnrm-controller-manager. Estos registros contienen los cambios precisos en los campos que iniciaron errores, como los bucles de reconciliación, lo que puede facilitar la solución de problemas.
  • Estado observado nativo: Los controladores directos propagan status.observedState en el estado del recurso, lo que proporciona una vista transparente del servidor de los campos de recursos que devuelven directamente las APIs deGoogle Cloud .
  • Mejora en el control del ciclo de vida: Los controladores directos incluyen funciones adicionales, como la eliminación correcta de elementos huérfanos.

Controlador de enrutamiento principal

Independientemente del tipo de recurso, Config Connector intercepta todas las solicitudes de reconciliación dentro de un controlador principal central. El controlador principal actúa como un router y evalúa qué lógica secundaria controla la sincronización activa con las siguientes reglas de precedencia:

  1. Invalidaciones de espacio de nombres: Primero, el controlador principal verifica la configuración del recurso ConfigConnectorContext en el espacio de nombres del recurso de destino para detectar cualquier invalidación explícita del controlador.
  2. Valores predeterminados estáticos: Si no se especifican anulaciones locales, el controlador principal se establece de forma predeterminada en el reconciliador de tiempo de compilación definido en la configuración de asignación estática de Config Connector.

Cómo identificar el controlador de un recurso

Puedes determinar qué tipo de controlador está configurado o activo para un recurso deGoogle Cloud específico con la asignación de código activo o examinando las estructuras de CustomResourceDefinition (CRD) en Google Kubernetes Engine (GKE).

Para buscar la configuración estática de un recurso, inspecciona el recurso en GitHub en pkg/controller/resourceconfig/static_config.go y busca el bloque de configuración del recurso, como en el siguiente ejemplo:

{Group: "alloydb.cnrm.cloud.google.com", Kind: "AlloyDBCluster"}: {
    DefaultController:    k8s.ReconcilerTypeTerraform,
    SupportedControllers: []k8s.ReconcilerType{k8s.ReconcilerTypeDirect, k8s.ReconcilerTypeTerraform},
}
  • DefaultController: Indica el reconciliador predeterminado que se usa si no se especifican reglas de anulación del contexto a nivel del espacio de nombres.
  • SupportedControllers: Enumera todos los reconciliadores implementados y disponibles para este recurso. Anula el cambio a los reconciliadores que se indican aquí.

Para inspeccionar las etiquetas de CRD, usa el comando kubectl get crd:

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

Reemplaza RESOURCE_NAME por el nombre exacto del CRD de Config Connector, por ejemplo, bigquerydatasets.bigquery.cnrm.cloud.google.com.

Verifica los resultados para obtener la siguiente información:

  • cnrm.cloud.google.com/tf2crd: "true": El controlador basado en Terraform (TF) administra el recurso.
  • cnrm.cloud.google.com/dcl2crd: "true": El controlador basado en DCL administra el recurso.
  • Ausencia de estas etiquetas: El responsable directo del tratamiento administra el recurso.

Anula el controlador predeterminado

Existen dos métodos principales para anular el tipo de controlador en Config Connector. La distinción entre ellos implica principalmente su alcance operativo, la sobrecarga de mantenimiento y la precedencia que tienen durante la conciliación.

En la siguiente tabla, se resumen las diferencias entre los dos enfoques:

Función Anotación de recursos Anulación de ConfigConnectorContext
Alcance Instancia de un solo recurso Todos los recursos de un tipo en un espacio de nombres
Prioridad Más alta (anula ConfigConnectorContext) Medio (anula el valor predeterminado estático)
¿Se recomienda? No Sí
Ideal para Pruebas únicas Lanzamiento para todo el equipo o proyecto

Anula el controlador de un recurso específico

Puedes forzar la ejecución de una instancia de recurso específica con un reconciliador específico agregando la anotación alpha.cnrm.cloud.google.com/reconciler a los metadatos del recurso. Aunque no se recomienda este enfoque por los motivos especificados en la sección anterior, es posible que lo necesites para probar configuraciones de una sola instancia de recurso o para mantener configuraciones heredadas.

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:
  ...

Los valores admitidos para la anotación son direct, tf o dcl.

Cómo anular el controlador de un espacio de nombres

Para configurar una anulación en todo el espacio de nombres con el recurso personalizado ConfigConnectorContext, completa los siguientes pasos:

  1. Recupera el nombre y el grupo de las definiciones de recursos. Por ejemplo, para el recurso BigQueryDataset, el tipo de recurso es BigQueryDataset y el grupo es bigquery.cnrm.cloud.google.com.

  2. Edita el objeto ConfigConnectorContext dentro del espacio de nombres que contiene tus recursos administrados:

    kubectl edit configconnectorcontext configconnectorcontext.core.cnrm.cloud.google.com -n NAMESPACE_NAME

    Reemplaza NAMESPACE_NAME por tu espacio de nombres de destino.

  3. Agrega tus anulaciones de destino. Por ejemplo, para anular todas las instancias de BigQueryDataset en este espacio de nombres para que se ejecuten con el controlador directo, define la configuración de la siguiente manera:

    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

  4. Guarda y aplica el recurso. El controlador principal aplica automáticamente las nuevas reglas de enrutamiento del conciliador directo de forma dinámica a todos los recursos coincidentes en este espacio de nombres.

Restricciones de anulación del espacio de nombres y casos de uso

  • Requisito de compatibilidad explícito: Para que una anulación se realice correctamente, el tipo de controlador objetivo debe implementarse para el tipo de recurso. Para verificar si se admite un tipo de controlador, consulta Cómo identificar el controlador de un recurso. Si el tipo de controlador que especificas en la anulación no es compatible, el controlador principal ignora la anulación y el reconciliador predeterminado sigue controlando el recurso.
  • Límite del espacio de nombres: Las anulaciones en un ConfigConnectorContext se aplican de forma colectiva a todas las instancias de ese tipo de recurso que residen dentro de ese espacio de nombres específico. No puedes segmentar anulaciones con permisos de espacio de nombres para instancias de recursos individuales.
  • Control de acceso: Por lo general, actualizar un objeto ConfigConnectorContext requiere privilegios de equipo de plataforma de nivel superior en comparación con las ediciones de recursos estándar.
  • Anulación del informe de estado: Si se especifica un tipo de controlador no válido o no admitido en las anulaciones de ConfigConnectorContext, el controlador principal marca el contexto como en mal estado. Para verificarlo, ejecuta kubectl get configconnectorcontext configconnectorcontext.core.cnrm.cloud.google.com -n NAMESPACE_NAME -o yaml y revisa los campos .status.healthy y .status.errors.
  • Cuándo usarlo: Este es el enfoque recomendado para anular los controladores. Úsalo para habilitar espacios de nombres completos para los controladores modernos (como el directo) o para aplicar la coherencia arquitectónica en todo un proyecto.