Config Connector-Controllertypen

Config Connector verwendet eine mehrschichtige Architektur, um Ressourcen in Ihrer Google Cloud Umgebung mit Ihren Kubernetes-Spezifikationen abzugleichen. Ein übergeordneter Controller der obersten Ebene leitet den Abgleich jeder Ressource an eine von vier zugrunde liegenden Controller-Implementierungen weiter.

Wenn Sie die einzelnen Controllertypen, ihre technischen Unterschiede und die Möglichkeit zur Steuerung des Namespace-weiten Routings kennen, können Sie die Leistung optimieren und Konfigurationsprobleme beheben.

Zugrunde liegende Controllertypen

Config Connector verwendet die folgenden Controllertypen:

  • Direkte Controller: Dieser Controller verwendet die Standardbibliothek controller-runtime von Kubernetes und kommuniziert direkt mit Google Cloud APIs über die offiziellen Google Cloud Go-SDKs. Wir empfehlen, nach Möglichkeit direkte Controller zu verwenden. Nicht alle Ressourcen unterstützen den direkten Controller. Neue Ressourcen verwenden standardmäßig den direkten Controller. Vorhandene Ressourcen werden regelmäßig migriert. Weitere Informationen finden Sie in den Versionshinweisen.
  • Terraform-basierte Controller (TF) : Dieser Controller fungiert als Wrapper für den Terraform Google Provider. Der Controller übersetzt Spezifikationen des Kubernetes Resource Model (KRM) in Terraform-kompatible Zustände und implementiert die Terraform-Vorgänge plan und apply.
  • DCL-basierte Controller: Dieser Controllertyp fungiert als Wrapper für die Google Cloud Declarative Client Library (DCL).
  • IAM-spezifische Controller:Das sind spezielle Controller, die speziell für die Verwaltung von Ressourcen der Identitäts- und Zugriffsverwaltung (Identity and Access Management, IAM) entwickelt wurden, einschließlich IAMPolicy, IAMPartialPolicy, IAMPolicyMember und IAMAuditConfig. Einige IAM-Ressourcen unterstützen optional den direkten Controller.

Vorteile direkter Controller

Einige Ressourcentypen unterstützen mehrere Controllertypen. Wenn eine Ressource den direkten Controller unterstützt, empfehlen wir, aus folgenden Gründen den direkten Controller anstelle eines anderen Controllertyps zu verwenden:

  • Geringerer Ressourcenverbrauch:Bei direkten Controllern fallen nicht der CPU- und Arbeitsspeicheraufwand an, der mit der Ausführung und Übersetzung von Terraform-basierten oder DCL-basierten Zuständen verbunden ist.
  • Verbesserte Latenz beim Abgleich:Direkte Controller können direkte Vorgänge für Google Cloud Endpunkte ausführen, wodurch die durchschnittliche Zeit verkürzt wird, die erforderlich ist, um die Konsistenz des Ressourcenstatus zu erreichen.
  • Detaillierter Status und strukturierte Unterschiede:Der direkte Controller bietet strukturierte Berichte zu Unterschieden in den cnrm-controller-manager-Protokollen. Diese Logs enthalten die genauen Feldänderungen, die Fehler wie Abgleichsschleifen ausgelöst haben, was die Fehlerbehebung erleichtern kann.
  • Nativer beobachteter Status: Direkte Controller füllen status.observedState im Ressourcenstatus aus und bieten so eine transparente serverseitige Ansicht der Ressourcenfelder, die direkt von den Google Cloud APIs zurückgegeben werden.
  • Verbesserte Lebenszyklusverwaltung:Direkte Controller enthalten zusätzliche Funktionen wie das ordnungsgemäße Löschen verwaister Ressourcen.

Übergeordneter Routing-Controller

Unabhängig vom Ressourcentyp fängt Config Connector alle Abgleichsanfragen in einem zentralen übergeordneten Controller ab. Der übergeordnete Controller fungiert als Router und wertet anhand der folgenden Vorrangregeln aus, welche untergeordnete Logik die aktive Synchronisierung verarbeitet:

  1. Namespace-Überschreibungen:Der übergeordnete Controller prüft zuerst die ConfigConnectorContext-Ressourcenkonfiguration im Namespace der Zielressource auf explizite Controller-Überschreibungen.
  2. Statische Standardeinstellungen:Wenn keine lokalen Überschreibungen angegeben sind, verwendet der übergeordnete Controller standardmäßig den zur Build-Zeit definierten Reconciler aus der statischen Zuordnungskonfiguration von Config Connector.

Controller für eine Ressource ermitteln

Sie können ermitteln, welcher Controllertyp für eine bestimmte Google Cloud Ressource konfiguriert oder aktiv ist, indem Sie die aktive Codezuordnung verwenden oder die CustomResourceDefinition-Strukturen (CRD) in Google Kubernetes Engine (GKE) untersuchen.

Wenn Sie die statische Konfiguration für eine Ressource suchen möchten, prüfen Sie die Ressource in GitHub unter pkg/controller/resourceconfig/static_config.go und suchen Sie nach dem Konfigurationsblock für die Ressource, wie im folgenden Beispiel:

{Group: "alloydb.cnrm.cloud.google.com", Kind: "AlloyDBCluster"}: {
    DefaultController:    k8s.ReconcilerTypeTerraform,
    SupportedControllers: []k8s.ReconcilerType{k8s.ReconcilerTypeDirect, k8s.ReconcilerTypeTerraform},
}
  • DefaultController:Gibt den Standard-Reconciler an, der verwendet wird, wenn keine Überschreibungsregeln für den Kontext auf Namespace-Ebene angegeben sind.
  • SupportedControllers:Listet alle Reconciler auf, die für diese Ressource implementiert und verfügbar sind. Überschreibungen wechseln zu den hier aufgeführten Reconcilern.

Verwenden Sie den Befehl kubectl get crd, um CRD-Labels zu prüfen:

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

Ersetzen Sie RESOURCE_NAME durch den genauen Namen der Config Connector-CRD, z. B. bigquerydatasets.bigquery.cnrm.cloud.google.com.

Prüfen Sie die Ergebnisse auf die folgenden Informationen:

  • cnrm.cloud.google.com/tf2crd: "true": Der Terraform-basierte Controller (TF) verwaltet die Ressource.
  • cnrm.cloud.google.com/dcl2crd: "true": Der DCL-basierte Controller verwaltet die Ressource.
  • Fehlen dieser Labels:Der direkte Controller verwaltet die Ressource.

Standard-Controller überschreiben

Es gibt zwei Hauptmethoden, um den Controllertyp in Config Connector zu überschreiben. Der Unterschied zwischen ihnen liegt hauptsächlich im Betriebsumfang, im Wartungsaufwand und im Vorrang beim Abgleich.

In der folgenden Tabelle sind die Unterschiede zwischen den beiden Ansätzen zusammengefasst:

Funktion Ressourcenannotation ConfigConnectorContext-Überschreibung
Umfang Einzelne Ressourceninstanz Alle Ressourcen einer Art in einem Namespace
Vorrang Höchster Vorrang (überschreibt ConfigConnectorContext) Medium (überschreibt statische Standardeinstellung)
Empfohlen? Nein Ja
Optimal für Einmalige Tests Team- oder projektweite Einführung

Controller für eine bestimmte Ressource überschreiben

Sie können erzwingen, dass eine bestimmte Ressourceninstanz mit einem bestimmten Reconciler ausgeführt wird, indem Sie der Ressourcenmetadaten die Annotation alpha.cnrm.cloud.google.com/reconciler hinzufügen. Dieser Ansatz wird aus den im vorherigen Abschnitt genannten Gründen nicht empfohlen. Er kann jedoch erforderlich sein, um Konfigurationen für eine einzelne Ressourceninstanz zu testen oder Legacy-Konfigurationen zu verwalten.

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

Unterstützte Werte für die Annotation sind direct, tf oder dcl.

Controller für einen Namespace überschreiben

Führen Sie die folgenden Schritte aus, um eine Namespace-weite Überschreibung mit der benutzerdefinierten Ressource ConfigConnectorContext zu konfigurieren:

  1. Rufen Sie den Namen und die Gruppe aus den Ressourcendefinitionen ab. Für die Ressource BigQueryDataset ist die Ressourcenart beispielsweise BigQueryDataset und die Gruppe bigquery.cnrm.cloud.google.com.

  2. Bearbeiten Sie das ConfigConnectorContext-Objekt im Namespace, der Ihre verwalteten Ressourcen enthält:

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

    Ersetzen Sie NAMESPACE_NAME durch den Ziel-Namespace.

  3. Fügen Sie die gewünschten Überschreibungen hinzu. Wenn Sie beispielsweise alle BigQueryDataset-Instanzen in diesem Namespace so überschreiben möchten, dass sie mit dem direkten Controller ausgeführt werden, definieren Sie die Konfiguration so:

    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. Speichern Sie die Ressource und wenden Sie sie an. Der übergeordnete Controller wendet die neuen Routingregeln für den direkten Reconciler automatisch dynamisch auf alle übereinstimmenden Ressourcen in diesem Namespace an.

Einschränkungen und Anwendungsfälle für Namespace-Überschreibungen

  • Explizite Unterstützung erforderlich:Damit eine Überschreibung erfolgreich ist, muss der Ziel-Controllertyp für die Ressourcenart implementiert sein. Informationen dazu, ob ein Controllertyp unterstützt wird, finden Sie unter Controller für eine Ressource ermitteln. Wenn der in der Überschreibung angegebene Controllertyp nicht unterstützt wird, ignoriert der übergeordnete Controller die Überschreibung und der Standard-Reconciler verarbeitet die Ressource weiterhin.
  • Namespace-Limit:Überschreibungen unter einem ConfigConnectorContext gelten gemeinsam für alle Instanzen dieses Ressourcentyps, die sich in diesem bestimmten Namespace befinden. Sie können mit Namespace-bezogenen Überschreibungen nicht auf einzelne Ressourceninstanzen abzielen.
  • Zugriffssteuerung:Für die Aktualisierung eines ConfigConnectorContext-Objekts sind in der Regel höhere Berechtigungen des Plattformteams erforderlich als für Standardressourcenbearbeitungen.
  • Statusberichte zu Überschreibungen:Wenn in den ConfigConnectorContext-Überschreibungen ein ungültiger oder nicht unterstützter Controllertyp angegeben ist, markiert der übergeordnete Controller den Kontext als fehlerhaft. Sie können dies überprüfen, indem Sie kubectl get configconnectorcontext configconnectorcontext.core.cnrm.cloud.google.com -n NAMESPACE_NAME -o yaml ausführen und die Felder .status.healthy und .status.errors prüfen.
  • Wann verwenden?:Dies ist der empfohlene Ansatz zum Überschreiben von Controllern. Verwenden Sie ihn, um ganze Namespaces für moderne Controller (z. B. direkte Controller) zu aktivieren oder um die architektonische Konsistenz in einem Projekt zu erzwingen.