Types de contrôleurs Config Connector

Config Connector utilise une architecture en couches pour rapprocher les ressources de votre Google Cloud environnement de vos spécifications Kubernetes. Un contrôleur parent de premier niveau achemine le rapprochement de chaque ressource vers l'une des quatre implémentations de contrôleur sous-jacentes.

Comprendre chaque type de contrôleur, ses différences techniques et comment contrôler le routage à l'échelle de l'espace de noms peut vous aider à optimiser les performances et à résoudre les problèmes de configuration.

Types de contrôleurs sous-jacents

Config Connector utilise les types de contrôleurs suivants :

  • Contrôleurs directs : ce contrôleur utilise la bibliothèque Kubernetes standard controller-runtime et communique directement avec les API Google Cloud à l'aide des SDK Go officiels Google Cloud . Nous vous recommandons d'utiliser des contrôleurs directs lorsque cela est possible. Toutes les ressources ne sont pas compatibles avec le contrôleur direct. Les nouvelles ressources utilisent le contrôleur direct par défaut. Les ressources existantes sont migrées régulièrement. Pour en savoir plus, consultez les notes de version.
  • Contrôleurs basés sur Terraform (TF) : ce contrôleur sert de "wrapper" pour le fournisseur Terraform Google. Le contrôleur traduit les spécifications du modèle de ressource Kubernetes (KRM) en états compatibles avec Terraform et implémente les opérations Terraform plan et apply.
  • Contrôleurs basés sur DCL : ce type de contrôleur sert de "wrapper" pour la Google Cloud bibliothèque client déclarative (DCL).
  • Contrôleurs spécifiques à IAM : il s'agit de contrôleurs spécialisés conçus spécifiquement pour gérer les ressources de Identity and Access Management (IAM), y compris IAMPolicy, IAMPartialPolicy, IAMPolicyMember et IAMAuditConfig. Certaines ressources IAM sont éventuellement compatibles avec le contrôleur direct.

Avantages des contrôleurs directs

Certains types de ressources sont compatibles avec plusieurs types de contrôleurs. Si une ressource est compatible avec le contrôleur direct, nous vous recommandons d'utiliser le contrôleur direct plutôt qu'un autre type de contrôleur pour les raisons suivantes :

  • Consommation de ressources réduite : les contrôleurs directs n'ont pas la surcharge de processeur et de mémoire associée à l'exécution et à la traduction des états basés sur Terraform ou DCL.
  • Latence de rapprochement améliorée : les contrôleurs directs peuvent effectuer des opérations directes sur les points de terminaison, ce qui réduit le temps moyen nécessaire pour atteindre la cohérence de l'état de la ressource. Google Cloud
  • État précis et différences structurées : le contrôleur direct fournit des rapports de différences structurées dans les journaux cnrm-controller-manager. Ces journaux contiennent les modifications précises des champs qui ont déclenché des erreurs telles que des boucles de rapprochement, ce qui peut faciliter le dépannage.
  • État observé natif : les contrôleurs directs remplissent status.observedState dans l'état de la ressource, ce qui fournit une vue transparente côté serveur des champs de ressources renvoyés directement par les Google Cloud API.
  • Gestion améliorée du cycle de vie : les contrôleurs directs incluent des fonctionnalités supplémentaires telles que la suppression progressive des orphelins.

Contrôleur de routage parent

Quel que soit le type de ressource, Config Connector intercepte toutes les requêtes de rapprochement dans un contrôleur parent central. Le contrôleur parent fait office de routeur, en évaluant la logique enfant qui gère la synchronisation active à l'aide des règles de priorité suivantes :

  1. Remplacements d'espace de noms : le contrôleur parent vérifie d'abord la configuration de la ressource ConfigConnectorContext dans l'espace de noms de la ressource cible pour détecter les remplacements de contrôleur explicites.
  2. Valeurs par défaut statiques : si aucun remplacement local n'est spécifié, le contrôleur parent utilise par défaut le rapprochement au moment de la compilation défini dans la configuration de mappage statique de Config Connector.

Identifier le contrôleur d'une ressource

Vous pouvez déterminer le type de contrôleur configuré ou actif pour une ressource spécifique Google Cloud à l'aide du mappage de code actif ou en examinant les structures CustomResourceDefinition (CRD) dans Google Kubernetes Engine (GKE).

Pour rechercher la configuration statique d'une ressource, inspectez la ressource dans GitHub à l'adresse pkg/controller/resourceconfig/static_config.go, puis recherchez le bloc de configuration de la ressource, comme dans l'exemple suivant :

{Group: "alloydb.cnrm.cloud.google.com", Kind: "AlloyDBCluster"}: {
    DefaultController:    k8s.ReconcilerTypeTerraform,
    SupportedControllers: []k8s.ReconcilerType{k8s.ReconcilerTypeDirect, k8s.ReconcilerTypeTerraform},
}
  • DefaultController : indique le rapprochement par défaut utilisé si aucune règle de remplacement de contexte au niveau de l'espace de noms n'est spécifiée.
  • SupportedControllers : liste tous les rapprochements implémentés et disponibles pour cette ressource. Les remplacements passent aux rapprochements listés ici.

Pour inspecter les libellés CRD, utilisez la commande kubectl get crd :

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

Remplacez RESOURCE_NAME par le nom exact de la CRD Config Connector, par exemple, bigquerydatasets.bigquery.cnrm.cloud.google.com.

Vérifiez les résultats pour obtenir les informations suivantes :

  • cnrm.cloud.google.com/tf2crd: "true": le contrôleur basé sur Terraform (TF) gère la ressource.
  • cnrm.cloud.google.com/dcl2crd: "true": le contrôleur basé sur DCL gère la ressource.
  • Absence de ces libellés : le contrôleur direct gère la ressource.

Remplacer le contrôleur par défaut

Il existe deux méthodes principales pour remplacer le type de contrôleur dans Config Connector. La distinction entre les deux concerne principalement leur champ d'application opérationnel, leur surcharge de maintenance et la priorité qu'elles prennent lors du rapprochement.

Le tableau suivant récapitule les différences entre les deux approches :

Fonctionnalité Annotation de ressource Remplacement ConfigConnectorContext
Champ d'application Instance de ressource unique Toutes les ressources d'un type dans un espace de noms
Priorité La plus élevée (remplace ConfigConnectorContext) Moyenne (remplace la valeur par défaut statique)
Recommandé ? Non Oui
Application idéale Test ponctuel Déploiement à l'échelle de l'équipe ou du projet

Remplacer le contrôleur d'une ressource spécifique

Vous pouvez forcer une instance de ressource spécifique à s'exécuter avec un rapprochement spécifique en ajoutant l'annotation alpha.cnrm.cloud.google.com/reconciler aux métadonnées de la ressource. Bien que cette approche ne soit pas recommandée pour les raisons spécifiées dans la section précédente, vous devrez peut-être l'utiliser pour tester les configurations d'une seule instance de ressource ou pour maintenir des configurations héritées.

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

Les valeurs compatibles pour l'annotation sont direct, tf ou dcl.

Remplacer le contrôleur d'un espace de noms

Pour configurer un remplacement à l'échelle de l'espace de noms à l'aide de la ressource personnalisée ConfigConnectorContext, procédez comme suit :

  1. Récupérez le nom et le groupe à partir des définitions de ressources. Par exemple, pour la ressource BigQueryDataset, le type de ressource est BigQueryDataset et le groupe est bigquery.cnrm.cloud.google.com.

  2. Modifiez l'objet ConfigConnectorContext dans l'espace de noms contenant vos ressources gérées :

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

    Remplacez NAMESPACE_NAME par l'espace de noms cible.

  3. Ajoutez vos remplacements cibles. Par exemple, pour remplacer toutes les instances BigQueryDataset de cet espace de noms afin qu'elles s'exécutent avec le contrôleur direct, définissez la configuration comme suit :

    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. Enregistrez et appliquez la ressource. Le contrôleur parent applique automatiquement les nouvelles règles de routage direct du rapprochement de manière dynamique à toutes les ressources correspondantes de cet espace de noms.

Contraintes et cas d'utilisation du remplacement d'espace de noms

  • Exigence de compatibilité explicite : pour qu'un remplacement réussisse, le type de contrôleur ciblé doit être implémenté pour le type de ressource. Pour vérifier si un type de contrôleur est compatible, consultez Identifier le contrôleur d'une ressource. Si le type de contrôleur que vous spécifiez dans le remplacement n'est pas compatible, le contrôleur parent ignore le remplacement et le rapprochement par défaut continue de gérer la ressource.
  • Limite d'espace de noms : les remplacements sous un ConfigConnectorContext s'appliquent collectivement à toutes les instances de ce type de ressource qui résident dans cet espace de noms spécifique. Vous ne pouvez pas cibler des instances de ressources individuelles avec des remplacements à portée d'espace de noms.
  • Contrôle des accès : la mise à jour d'un objet ConfigConnectorContext nécessite généralement des droits d'équipe de plate-forme de niveau supérieur par rapport aux modifications de ressources standards.
  • Rapports sur l'état de remplacement : si un type de contrôleur non valide ou non compatible est spécifié dans les remplacements ConfigConnectorContext, le contrôleur parent marque le contexte comme étant en mauvais état. Pour le vérifier, exécutez kubectl get configconnectorcontext configconnectorcontext.core.cnrm.cloud.google.com -n NAMESPACE_NAME -o yaml, puis vérifiez les champs .status.healthy et .status.errors.
  • Quand l'utiliser : il s'agit de l'approche recommandée pour remplacer les contrôleurs. Utilisez-la pour activer des espaces de noms entiers pour les contrôleurs modernes (tels que les contrôleurs directs) ou pour appliquer une cohérence architecturale dans un projet.