Config Connector manuell installieren

Auf dieser Seite wird erläutert, wie Sie Config Connector manuell installieren. Die manuelle Installation ist eine flexible Option, mit der Sie die installierte Version und den Upgradezeitplan steuern können.

Die Anleitung auf dieser Seite konzentriert sich auf die Installation von Config Connector in Google Kubernetes Engine-Clustern (GKE). Weitere Informationen zu den verschiedenen Installationsoptionen finden Sie unter Installationstyp auswählen.

In den meisten Fällen sollten Sie Config Connector manuell im Namespace-Modus installieren. Die Alternative ist der Clustermodus. Der Namespace-Modus ist skalierbarer und bietet eine bessere Berechtigungsisolation. Daher wird er für mehrmandantenfähige Cluster oder für die Verwaltung von Ressourcen über mehrere Projekte hinweg empfohlen. Vermeiden Sie in Mehrmandanten-Umgebungen den Clustermodus. Im Clustermodus wird ein einzelnes, freigegebenes IAM-Dienstkonto (Identity and Access Management) verwendet. Jeder Nutzer, der Config Connector-Ressourcen in einem beliebigen Namespace erstellen kann, kann mit den vollständigen IAM-Berechtigungen dieses Dienstkontos agieren.

Wenn Sie ein einzelnes, clusterweites Dienstkonto bevorzugen, folgen Sie stattdessen der Anleitung für die Installation im Clustermodus.

Hinweis

Führen Sie vor der manuellen Installation des Config Connector-Operators die folgenden Schritte aus:

• Erstellen oder identifizieren Sie einen GKE-Cluster, in dem Config Connector noch nicht installiert ist und für den Workload Identity und Kubernetes Engine-Monitoring aktiviert sind.
• Konfigurieren Sie kubectl, um eine Verbindung zum Cluster herzustellen.

Config Connector-Operator installieren

Config Connector verwendet einen Kubernetes-Operator, um die Installation auf dem neuesten Stand zu halten. Die Installation des Operators ist erforderlich, unabhängig davon, ob Sie Config Connector im Namespace- oder Clustermodus installieren.

Führen Sie die folgenden Schritte aus, um den Config Connector-Operator zu installieren:

1. Laden Sie die neueste TAR-Datei für den Config Connector-Operator herunter:

   gcloud storage cp gs://configconnector-operator/latest/release-bundle.tar.gz release-bundle.tar.gz
   

   Hinweis: Erstellen Sie eine Kopie des Installationspakets, da Sie dieses benötigen, um Config Connector zu deinstallieren.

2. Extrahieren Sie die TAR-Datei:

   tar zxvf release-bundle.tar.gz
   

3. Installieren Sie den Config Connector-Operator in Ihrem Cluster:

   Autopilot

   kubectl apply -f operator-system/autopilot-configconnector-operator.yaml
   

   Standard

   kubectl apply -f operator-system/configconnector-operator.yaml
   

4. Führen Sie die folgenden Schritte aus, um den Config Connector-Operator für die Ausführung im Namespace-Modus zu konfigurieren:

   1. Erstellen Sie ein Manifest mit dem Namen configconnector.yaml und dem folgenden Inhalt:

      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. Wenden Sie das Manifest auf Ihren Cluster an:

      kubectl apply -f configconnector.yaml
      

Config Connector im Namespace-Modus installieren

Hinweis: Sie müssen diese Schritte für jeden Namespace ausführen, aus dem Config Connector Ressourcen erstellen soll.

In den folgenden Abschnitten ist das Projekt, in dem Sie Config Connector installieren, das Hostprojekt. Die anderen Projekte, in denen Sie Ressourcen mit Config Connector verwalten können, sind verwaltete Projekte. Das Host- und das verwaltete Projekt können dasselbe Projekt sein, wenn Config Connector nur Ressourcen im selben Projekt wie Ihr Cluster erstellen soll.

Namespace erstellen

Erstellen Sie mit dem folgenden Befehl einen neuen Namespace:

kubectl create namespace NAMESPACE

Ersetzen Sie NAMESPACE durch einen Namen für den Namespace.

Identität erstellen

Erstellen Sie ein IAM-Dienstkonto und eine Bindung zwischen dem IAM-Dienstkonto und dem Kubernetes-Dienstkonto von Config Connector. Führen Sie dazu die folgenden Schritte aus:

1. IAM-Dienstkonto erstellen. Wenn Sie bereits ein Dienstkonto haben, können Sie dieses verwenden, statt ein neues zu erstellen. Verwenden Sie gcloud, um das Dienstkonto mit folgendem Befehl zu erstellen:

   gcloud iam service-accounts create NAMESPACE_GSA --project HOST_PROJECT_ID
   

   Dabei gilt:

   • NAMESPACE_GSA durch den Namen des Google-Dienstkontos (GSA, Google Service Account), das an Ihren Namespace gebunden ist.
   • HOST_PROJECT_ID ist die ID Ihres Hostprojekts.

   Weitere Informationen zum Erstellen von Dienstkonten finden Sie unter Dienstkonten erstellen und verwalten.

2. Weisen Sie dem IAM-Dienstkonto erhöhte Berechtigungen für Ihr verwaltetes Projekt zu:

   gcloud projects add-iam-policy-binding MANAGED_PROJECT_ID \
       --member="serviceAccount:NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com" \
       --role="roles/owner"
   

   Ersetzen Sie MANAGED_PROJECT_ID durch die ID Ihres verwalteten Projekts.

   Hinweis: Wenn Sie dem Projekt Bearbeitungszugriff gewähren möchten, ersetzen Sie roles/owner durch roles/editor. Durch Zuweisen der Bearbeiterrolle können die meisten Config Connector-Funktionen ausgeführt werden, mit Ausnahme von projekt- oder organisationsweiten Konfigurationen wie IAM-Änderungen.

3. Erstellen Sie eine IAM-Richtlinienbindung zwischen dem IAM-Dienstkonto und dem Config Connector-Kubernetes-Dienstkonto:

   gcloud iam service-accounts add-iam-policy-binding \
       NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com \
       --member="serviceAccount:HOST_PROJECT_ID.svc.id.goog[cnrm-system/cnrm-controller-manager-NAMESPACE]" \
       --role="roles/iam.workloadIdentityUser"
   

4. Erteilen Sie dem IAM-Dienstkonto die Berechtigung, Prometheus-Messwerte in Ihrem Hostprojekt in Google Cloud Observability zu veröffentlichen:

   gcloud projects add-iam-policy-binding HOST_PROJECT_ID \
       --member="serviceAccount:NAMESPACE_GSA@HOST_PROJECT_ID.iam.gserviceaccount.com" \
       --role="roles/monitoring.metricWriter"
   

ConfigConnectorContext erstellen

Wenn Sie Google Cloud -Ressourcen erstellen möchten, konfigurieren Sie Config Connector so, dass Ihr Namespace überwacht wird. Fügen Sie dazu ein ConfigConnectorContext-Objekt in diesem Namespace hinzu.

Führen Sie folgende Schritte aus, um eine ConfigConnectorContext zu erstellen.

1. Erstellen Sie ein Manifest mit dem Namen configconnectorcontext.yaml und dem folgenden Inhalt:

   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.iam.gserviceaccount.com"
     stateIntoSpec: Absent
   

2. Wenden Sie das Manifest auf Ihren Cluster an:

   kubectl apply -f configconnectorcontext.yaml
   

3. Prüfen Sie mit dem folgenden Befehl, ob der Config Connector-Operator ein Kubernetes-Dienstkonto für Ihren Namespace erstellt hat:

   kubectl get serviceaccount/cnrm-controller-manager-NAMESPACE  -n cnrm-system
   

4. Prüfen Sie, ob der Config Connector-Controller-Pod für Ihren Namespace ausgeführt wird:

   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
   

   Wenn der Config Connector-Controller ausgeführt wird, sieht die Ausgabe in etwa so aus:

   cnrm-controller-manager-abcdefghijk-0 condition met.
   

Verwaltung von Ressourcen in einem Namespace beenden

Wenn Config Connector keine Ressourcen mehr in einem Namespace verwalten soll, entfernen Sie alle Config Connector-Ressourcen und das ConfigConnectorContext-Objekt in diesem Namespace.

1. Wenn Sie alle Config Connector-Ressourcen in Ihrem Namespace finden möchten, listen Sie für jede benutzerdefinierte Config Connector-Ressourcendefinition alle Ressourcen auf.

   kubectl get gcp -n NAMESPACE
   

   Die Ausgabe dieses Befehls listet alle benutzerdefinierten Ressourcendefinitionen (Custom Resource Definitions, CRDs) auf, die eine von Config Connector verwaltete Ressource in diesem Namespace darstellen, einschließlich des Namens und der Kubernetes-Art dieser Ressource.

2. Führen Sie den folgenden Befehl aus, um alle Config Connector-Ressourcen für jede Ressource in der Ausgabe des vorherigen Schritts zu entfernen:

   kubectl delete -n NAMESPACE KIND NAME
   

   Ersetzen Sie Folgendes:

   • KIND: die Kubernetes-Art der Ressource.
   • NAME ist der Name der -Ressource.

3. Löschen Sie das ConfigConnectorContext-Objekt in Ihrem Namespace.

   kubectl delete -n NAMESPACE ConfigConnectorContext configconnectorcontext.core.cnrm.cloud.google.com
   

   Wichtig: Löschen Sie das Objekt ConfigConnectorContext erst, wenn alle von Config Connector verwalteten Ressourcen gelöscht wurden.

Config Connector deinstallieren

Führen Sie folgende Schritte aus, um Config Connector zu deinstallieren:

1. Führen Sie den folgenden Befehl aus, um die Config Connector-CRDs und -Controller-Komponenten zu entfernen:

   kubectl delete ConfigConnectorContext --all -A –wait=false
   
   kubectl delete ConfigConnector configconnector.core.cnrm.cloud.google.com \
       --wait=true
   

2. Führen Sie folgenden Befehl aus, um den Config Connector-Operator zu deinstallieren:

   kubectl delete -f operator-system/configconnector-operator.yaml  --wait=true
   

Im Clustermodus installieren

Sie können Config Connector im Clustermodus installieren und verwalten, wenn Sie Ressourcen innerhalb eines einzelnen Projekts verwalten möchten und die Berechtigungstrennung, die der Namespace-Modus bietet, nicht benötigen.

Identität erstellen

Config Connector erstellt und verwaltet Google Cloud -Ressourcen, indem er sich mit einem IAM-Dienstkonto (Identity and Access Management) authentifiziert und die Workload Identity-Föderation für GKE verwendet, um IAM-Dienstkonten an Kubernetes-Dienstkonten zu binden.

Hinweis: Sie müssen diese Schritte nur einmal pro Cluster ausführen.

Führen Sie zum Erstellen der Identität folgende Schritte aus:

1. IAM-Dienstkonto erstellen. Wenn Sie ein vorhandenes Dienstkonto verwenden möchten, können Sie dieses Konto verwenden und diesen Schritt überspringen:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
   

   Ersetzen Sie SERVICE_ACCOUNT_NAME durch einen Namen für Ihr Dienstkonto.

   Weitere Informationen zum Erstellen von Dienstkonten finden Sie unter Dienstkonten erstellen und verwalten.

2. Weisen Sie dem IAM-Dienstkonto erweiterte Berechtigungen für Ihr Projekt zu:

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
     --role="roles/editor"
   

   Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID.

   Hinweis: Durch das Zuweisen der Bearbeiterrolle werden die meisten Config Connector-Funktionen ermöglicht, mit Ausnahme von projekt- und organisationsweiten Konfigurationen wie IAM-Änderungen. In einer Produktionsumgebung empfehlen wir, detailliertere Berechtigungen festzulegen. Weitere Informationen zu IAM-Rollen finden Sie unter Informationen zu Rollen.

3. Erstellen Sie eine IAM-Richtlinienbindung zwischen dem IAM-Dienstkonto und dem vordefinierten Kubernetes-Dienstkonto, das Config Connector ausführt:

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

Config Connector konfigurieren

Um die Installation abzuschließen, erstellen Sie eine Konfigurationsdatei für die CustomResource-ConfigConnector und wenden diese dann mit dem Befehl kubectl apply an. Der Config Connector-Operator installiertGoogle Cloud -Ressourcen-CRDs und Config Connector-Komponenten in Ihrem Cluster.

Führen Sie die folgenden Schritte aus, um den Operator im Clustermodus zu konfigurieren:

1. Kopieren Sie die folgende YAML-Datei in eine Datei mit dem Namen 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.iam.gserviceaccount.com"
     # 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

   Ersetzen Sie Folgendes:
   • SERVICE_ACCOUNT_NAME durch den Namen Ihres Dienstkontos.
   • PROJECT_ID durch Ihre Projekt-ID,
2. Wenden Sie die Konfiguration mit kubectl apply auf Ihren Cluster an:

     kubectl apply -f configconnector.yaml

Speicherort für Ressourcen angeben

Config Connector kann Ressourcen nach Projekt, Ordner oder Organisation organisieren, genau wie Sie Ressourcen mit Google Cloudorganisieren würden.

Bevor Sie mit Config Connector Ressourcen erstellen, müssen Sie festlegen, wo die Ressourcen angelegt werden sollen. Um zu ermitteln, wo eine Ressource erstellt werden soll, nutzt Config Connector eine Annotation in der Ressourcenkonfiguration oder in einem vorhandenen Namespace. Weitere Informationen finden Sie unter Ressourcen organisieren.

Wenn Sie keinen für diesen Zweck geeigneten Namespace haben, erstellen Sie einen mit kubectl.

kubectl create namespace NAMESPACE

Ersetzen Sie dabei NAMESPACE durch Ihren Namespace-Namen. Beispiel: config-connector.

Wählen Sie den Tab aus, in dem Config Connector Ressourcen anlegen soll.

Projekt

Führen Sie folgenden Befehl aus, um Ressourcen in einem bestimmten Projekt zu erstellen:

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/project-id=PROJECT_ID

Ersetzen Sie Folgendes:

• NAMESPACE durch Ihren Namespace-Namen.
• PROJECT_ID durch Ihre Google Cloud -Projekt-ID.

Ordner

Führen Sie folgenden Befehl aus, um Ressourcen in einem bestimmten Ordner zu erstellen:

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/folder-id=FOLDER_ID

Ersetzen Sie Folgendes:

• NAMESPACE durch Ihren Namespace-Namen.
• FOLDER_ID durch Ihre Google Cloud -Ordner-ID.

Organisation

Führen Sie folgenden Befehl aus, um Ressourcen in einer bestimmten Organisation zu erstellen:

    kubectl annotate namespace \
    NAMESPACE cnrm.cloud.google.com/organization-id=ORGANIZATION_ID

Ersetzen Sie Folgendes:

• NAMESPACE durch Ihren Namespace-Namen.
• ORGANIZATION_ID durch Ihre Organisations-ID von Google Cloud .

Wenn Sie Ihren Namespace mit Annotationen versehen, erstellt Config Connector Ressourcen im entsprechenden Projekt, im entsprechenden Ordner oder in der entsprechenden Organisation. Weitere Informationen zur Verwendung von Kubernetes-Namespaces durch Config Connector finden Sie unter Kubernetes-Namespaces und Google Cloud -Projekte.

Installation prüfen

Config Connector führt alle seine Komponenten in einem Namespace mit dem Namen cnrm-system aus. Mit dem folgenden Befehl können Sie prüfen, ob die Pods bereit sind:

kubectl wait -n cnrm-system \
      --for=condition=Ready pod --all

Wenn Config Connector korrekt installiert ist, sieht die Ausgabe etwa so aus:

pod/cnrm-controller-manager-0 condition met

Hinweis: Es kann mehrere Minuten dauern, bis der Controller-Pod startet.

Config Connector deinstallieren

Führen Sie folgende Schritte aus, um Config Connector zu deinstallieren:

1. Führen Sie den folgenden Befehl aus, um die Config Connector-CRDs und -Controller-Komponenten zu entfernen:

   kubectl delete ConfigConnector configconnector.core.cnrm.cloud.google.com \
       --wait=true
   

2. Führen Sie folgenden Befehl aus, um den Config Connector-Operator zu deinstallieren:

   kubectl delete -f operator-system/configconnector-operator.yaml  --wait=true
   

Config Connector aktualisieren

Führen Sie den folgenden Befehl aus, um die aktuelle Version des Config Connector-Operators herunterzuladen und zu installieren:

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

Downgrade von Config Connector durchführen

Ein vollständiges Downgrade von Config Connector wird nicht unterstützt. Wenn Sie sowohl den Config Connector-Operator als auch die CRDs downgraden möchten, müssen Sie Config Connector deinstallieren, neu installieren und dann Ihre Ressourcen noch einmal anwenden.

In Config Connector-Version 1.123.1 und höher können Sie ein Rollback der Operator-Version für Installationen durchführen, die den Namespace-Modus verwenden. Legen Sie in jedem Namespace, der einen Operator hat, für den Sie ein Rollback durchführen möchten, das Feld spec.version im Objekt ConfigConnectorContext auf die vorherige Config Connector-Version fest.

Sie können den Config Connector-Controller um maximal drei Nebenversionen zurücksetzen. Sie müssen immer ein Rollback auf die neueste Patchversion für eine bestimmte Nebenversion ausführen.

Upgrade von Installationen ohne Operator

Config Connector Version 1.33.0 und höher unterstützt nur die Installation mit dem GKE-Add-on oder dem Operator.

Wenn Sie ein Upgrade auf den Operator durchführen und alle Config Connector-Ressourcen beibehalten möchten, müssen Sie alle Config Connector-Systemkomponenten mit Ausnahme der CRDs entfernen und dann den Operator installieren.

1. Führen Sie folgenden Befehle aus, um Nicht-CRD-Komponenten des Config Connector-Systems zu entfernen:

   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. Installieren Sie Config Connector mit dem GKE-Add-on oder dem Operator.

Vom Add-on zu einer manuellen Installation wechseln

Wenn Config Connector als Add-on installiert ist, ist die Version direkt an die installierte GKE-Version gebunden.

Die manuelle Installation ermöglicht schnellere Updates, erfordert aber manuelle Upgrades.

So wechseln Sie die Installationsmethode und behalten Ihre Ressourcen sicher bei:

1. Deaktivieren Sie das Add-on, ohne irgendwelche ConfigConnector- oder ConfigConnectorContext-Objekte zu löschen:

   gcloud container clusters update CLUSTER_NAME --update-addons ConfigConnector=DISABLED
   

   Ersetzen Sie CLUSTER_NAME durch den Namen des Clusters, auf dem Sie Config Connector installiert haben.

2. Installieren Sie den manuellen Operator der ausgewählten Version.

   Um potenzielle CRD-Validierungsfehler (z. B. KNV2009: Invalid value: "v1beta1": must appear in spec.versions) zu vermeiden, muss die ausgewählte Version des manuellen Operators mit der Version, die Sie für das Add-on verwendet haben, identisch oder höher sein. Ein Downgrade der manuellen Operatorversion kann zu Fehlern führen (z. B. KNV2009), da das GKE-Add-on möglicherweise bereits bestimmte CRDs auf eine neuere Config Connector-Version aktualisiert hat.

Hinweis: Da die namespace-id ConfigMap im Namespace configconnector-operator-system im Rahmen der Deaktivierung des Add-ons gelöscht wird, werden alte cnrm-controller-manager StatefulSets neu erstellt.

Nächste Schritte

• Erste Schritte mit Config Connector.
• Best Practices für Config Connector