Config Sync Zugriff auf Ihr Git-Repository gewähren

Auf dieser Seite wird beschrieben, wie Sie Config Sync bei Ihrem Git-Repository authentifizieren. Config Sync benötigt Lesezugriff auf Ihre Source of Truth um Ihre Konfigurationen lesen, auf Ihre Cluster anwenden und synchronisieren zu können.

Authentifizierungsmethode auswählen

Die verwendete Authentifizierungsmethode hängt davon ab, was für Ihren Quelltyp unterstützt wird.

In der folgenden Tabelle sind die Authentifizierungsmethoden zusammengefasst, die Sie mit Config Sync verwenden können:

Config Sync unterstützt auch die folgenden Authentifizierungsmethoden. Diese Methoden werden jedoch nur empfohlen, wenn Sie keine der in der vorherigen Tabelle aufgeführten Optionen verwenden können:

• Cookiefile:Wird möglicherweise nicht für alle Git-Anbieter unterstützt. Wird für OCI oder Helm nicht unterstützt.
• Compute Engine-Standarddienstkonto (gcenode) : Nicht empfohlen, da diese Methode nur funktioniert, wenn die Workload Identity-Föderation für GKE deaktiviert ist. Wird für Git, OCI und Helm unterstützt.
• Google-Dienstkonto für Helm und OCI:Wird unterstützt, aber nicht empfohlen, da die Kubernetes-Dienstkontomethode weniger Konfiguration erfordert.

Authentifizierung mit Flottenpaketen

Wenn Sie Flottenpakete verwenden, müssen Sie die Anleitung auf dieser Seite nicht ausführen. Flottenpakete verwenden Cloud Build zur Authentifizierung bei Git. So können Sie sich einmal pro Projekt authentifizieren und müssen nicht jedes Mal Zugriff gewähren, wenn Sie Config Sync in einem Cluster installieren.

Hinweis

Bevor Sie Config Sync Lesezugriff auf Ihr Git-Repository gewähren, führen Sie die folgenden Aufgaben aus:

• Bereiten Sie ein Git-Repository vor oder verschaffen Sie sich Zugriff darauf, in dem Sie Ihre Konfigurationsdateien speichern, die von Config Sync synchronisiert werden sollen. Weitere Informationen finden Sie in den folgenden Ressourcen:

  • Konfigurationen zu einer „Source of Truth“ hinzufügen: konzeptionelle Informationen zu Konfigurationen.
  • Best Practices für GitOps: Tipps und allgemeine Best Practices zum Organisieren und Verwalten Ihres Repositorys.
  • Unstrukturiertes Repository verwenden: Empfehlungen für die Verwendung und Organisation eines unstrukturierten Repositorys.

• Erstellen Sie einen GKE-Cluster oder verschaffen Sie sich Zugriff darauf. Bevor Sie einen Cluster erstellen, lesen Sie die Anforderungen und Empfehlungen zur Clusterkonfiguration für Config Sync.

SSH-Schlüsselpaar verwenden

Ein SSH-Schlüsselpaar besteht aus zwei Dateien, einem öffentlichen und einem privaten Schlüssel. Config Sync unterstützt keine Passphrasen. Je nach Ihren Sicherheits- und Complianceanforderungen können Sie ein einziges Schlüsselpaar für alle Cluster oder ein Schlüsselpaar pro Cluster verwenden.

So gewähren Sie Config Sync Lesezugriff auf Ihr Git-Repository mit einem SSH-Schlüsselpaar:

1. Erstellen Sie ein SSH-Schlüsselpaar oder bitten Sie Ihren Sicherheitsadministrator, Ihnen eines zur Verfügung zu stellen. Wenn Sie ein SSH-Schlüsselpaar erstellen müssen, erstellen Sie mit dem folgenden Befehl einen 4096-Bit-RSA-Schlüssel:

   ssh-keygen -t rsa -b 4096 \
     -C "GIT_REPOSITORY_USERNAME" \
     -N '' \
     -f /path/to/KEYPAIR_FILENAME
   

   Ersetzen Sie Folgendes:

   • GIT_REPOSITORY_USERNAME: Nutzername, mit dem sich Config Sync beim Repository authentifizieren soll. Wenn Sie einen Drittanbieter-Host für das Git-Repository wie GitHub oder ein Dienstkonto mit Secure Source Manager nutzen möchten, empfehlen wir die Verwendung eines separaten Kontos für die Authentifizierung.
   • /path/to/KEYPAIR_FILENAME: Pfad zur Schlüsselpaardatei.

2. Konfigurieren Sie Ihr Repository so, dass der neu erstellte öffentliche Schlüssel erkannt wird. Weitere Informationen finden Sie in der Dokumentation Ihres Git-Hostanbieters. Eine Anleitung für einige gängige Git-Hostanbieter finden Sie in der folgenden Liste:

   • Secure Source Manager
   • Bitbucket
   • GitHub
   • GitLab

3. Erstellen Sie das Secret git-creds mit dem privaten Schlüssel:

   kubectl create ns config-management-system && \
   kubectl create secret generic git-creds \
       --namespace=config-management-system \
       --from-file=ssh=/path/to/KEYPAIR_PRIVATE_KEY_FILENAME
   

   Ersetzen Sie /path/to/KEYPAIR_PRIVATE_KEY_FILENAME durch den Namen des privaten Schlüssels.

4. Optional, aber empfohlen: Wenn Sie die Überprüfung bekannter Hosts bei der SSH-Authentifizierung konfigurieren möchten, fügen Sie den Schlüssel bekannter Hosts dem Feld data.known_hosts im Secret git_creds hinzu.

   1. Führen Sie den folgenden Befehl aus, um den Schlüssel bekannter Hosts hinzuzufügen:

      kubectl edit secret git-creds --namespace=config-management-system
      

   2. Führen Sie den folgenden Befehl aus, um den Eintrag known_hosts unter data hinzuzufügen:

        known_hosts: KNOWN_HOSTS_KEY
      

      Ersetzen Sie KNOWN_HOSTS_KEY durch den Schlüssel bekannter Hosts.

   Wenn Sie die Überprüfung von known_hosts deaktivieren möchten, entfernen Sie das Feld known_hosts aus dem Secret.

Verwenden Sie bei der Installation von Config Sync das SSH-Schlüsselpaar (ssh) als Authentifizierungstyp.

Wenn Sie die URL Ihres Git-Repositorys eingeben, muss sie das SSH-Protokollformat verwenden. Das Format der URL hängt vom Git-Anbieter ab.

Cookiefile verwenden

Der Vorgang zum Abrufen eines cookiefile hängt von der Konfiguration Ihres Repositorys ab. Im Allgemeinen werden Anmeldedaten in einer .gitcookies-Datei in einem Basisverzeichnis gespeichert oder von einem Sicherheitsadministrator bereitgestellt.

So gewähren Sie Config Sync Lesezugriff auf Ihr Git-Repository mit einem cookiefile:

Nachdem Sie das cookiefile erstellt oder abgerufen haben, fügen Sie es einem neuen Secret im Cluster hinzu. Aus Sicherheitsgründen empfehlen wir die Verwendung von HTTPS:

kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace=config-management-system \
  --from-file=cookie_file=/path/to/COOKIEFILE

Ersetzen Sie /path/to/COOKIEFILE durch Ihren Pfad und Dateinamen.

Verwenden Sie bei der Installation von Config Sync das Cookiefile (cookiefile) als Authentifizierungstyp.

Token verwenden

Wenn Ihre Organisation die Verwendung von SSH-Schlüsseln nicht zulässt, sollten Sie ein Token verwenden.

So gewähren Sie Config Sync Lesezugriff auf Ihr Git-Repository mit einem Token:

1. Generieren Sie ein Token von Ihrem Git-Anbieter. Eine Anleitung finden Sie in der Dokumentation Ihres Git-Hostanbieters. Eine Anleitung für einige gängige Git-Hostanbieter finden Sie in der folgenden Liste:

   • GitHub: Erstellen Sie ein PAT. Gewähren Sie dem Token den Zugriffsbereich repo, damit es Daten aus privaten Repositories lesen kann. Da Sie ein PAT an ein GitHub-Konto binden, sollten Sie auch einen Computernutzer erstellen und das PAT an den Computernutzer binden.
   • GitLab: Erstellen Sie ein PAT oder erstellen Sie ein Deployment-Token.
   • Bitbucket: Erstellen Sie ein App-Passwort.

2. Nachdem Sie ein Token erstellt oder abgerufen haben, fügen Sie es einem neuen Secret im Cluster hinzu. Aus Sicherheitsgründen empfehlen wir die Verwendung von HTTPS:

   kubectl create ns config-management-system && \
   kubectl create secret generic git-creds \
     --namespace=config-management-system \
     --from-literal=username=USERNAME \
     --from-literal=token=TOKEN
   

   Ersetzen Sie Folgendes:

   • USERNAME: Nutzername, den Sie verwenden möchten.
   • TOKEN: Token, das Sie im vorherigen Schritt erstellt haben.

Verwenden Sie bei der Installation von Config Sync das Token (token) als Authentifizierungstyp.

Google-Dienstkonto verwenden

Sie können Config Sync Zugriff auf ein Repository im selben Projekt gewähren, in dem sich Ihr verwalteter Cluster befindet, indem Sie ein Google-Dienstkonto verwenden. Es müssen die folgenden Anforderungen erfüllt sein:

• Ihr Repository befindet sich in Secure Source Manager oder Cloud Source Repositories.
• Für Ihren Cluster ist die Workload Identity-Föderation für GKE oder die Workload Identity-Föderation für GKE für Flotten aktiviert.

So gewähren Sie Config Sync Lesezugriff auf Ihr Git-Repository mit einem Google-Dienstkonto:

1. Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle „Dienstkontoadministrator “ (roles/iam.serviceAccountAdmin) für das Dienstkonto zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen einer Richtlinienbindung benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

   Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

2. Wenn Sie kein Dienstkonto haben, erstellen Sie eins.

3. Weisen Sie dem Google-Dienstkonto je nach verwendetem Repository-Typ die IAM-Rolle zu:

   Secure Source Manager

   Weisen Sie dem Google-Dienstkonto die IAM-Rollen „Secure Source Manager-Instanzzugriff“ (roles/securesourcemanager.instanceAccessor) und „Secure Source Manager-Repository-Leser“ (roles/securesourcemanager.repoReader) zu:

   • Erteilen Sie projektweite Berechtigungen, wenn für alle Repositories im Projekt dieselben Berechtigungen gelten sollen:

     gcloud projects add-iam-policy-binding PROJECT_ID \
       --role=roles/securesourcemanager.instanceAccessor \
       --member="serviceAccount:GSA_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com"
     

     gcloud projects add-iam-policy-binding PROJECT_ID \
       --role=roles/securesourcemanager.repoReader \
       --member="serviceAccount:GSA_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com"
     

     Ersetzen Sie Folgendes:

     • PROJECT_ID: Ihre Projekt-ID.
     • GSA_NAME: Name des Google-Dienstkontos, das Sie mit Secure Source Manager verbinden möchten.

   • Informationen zum Erteilen von Repository-spezifischen Berechtigungen finden Sie in der Secure Source Manager Dokumentation unter Nutzern Rollen auf Repository-Ebene zuweisen.

   Verwenden Sie bei der Installation von Config Sync Workload Identity (gcpserviceaccount) als Authentifizierungstyp. Sie müssen auch die E-Mail-Adresse Ihres Dienstkontos hinzufügen.

   Secure Source Manager erfordert ein bestimmtes Format für die Repository-URL: https://SSM_INSTANCE_ID-PROJECT_NUMBER-git.INSTANCE_LOCATION.sourcemanager.dev/PROJECT_ID/REPO_NAME.git.

   Cloud Source Repositories

   Weisen Sie dem Google-Dienstkonto die IAM-Rolle „Cloud Source Repositories-Leser“ (roles/source.reader) zu:

   • Erteilen Sie projektweite Berechtigungen, wenn für alle Repositories im Projekt dieselben Berechtigungen gelten sollen:

     gcloud projects add-iam-policy-binding PROJECT_ID \
       --role=roles/source.reader \
       --member="serviceAccount:GSA_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com"
     

     Ersetzen Sie Folgendes:

     • PROJECT_ID: Ihre Projekt-ID.
     • GSA_NAME: Name des Google-Dienstkontos, das Sie mit Cloud Source Repositories verbinden möchten.

   • Erteilen Sie eine Repository-spezifische Berechtigung, wenn Sie Dienstkonten für jedes Repository in Ihrem Projekt unterschiedliche Zugriffsebenen zuweisen möchten:

     gcloud source repos set-iam-policy REPOSITORY POLICY_FILE --project=PROJECT_ID
     

     Ersetzen Sie Folgendes:

     • PROJECT_ID: Ihre Projekt-ID.
     • REPOSITORY: Name des Repositorys.
     • POLICY_FILE: JSON- oder YAML-Datei mit der Identity and Access Management-Richtlinie.

   Verwenden Sie bei der Installation von Config Sync Workload Identity (gcpserviceaccount) als Authentifizierungstyp. Sie müssen auch die E-Mail-Adresse Ihres Dienstkontos hinzufügen.

Dieser Schritt muss nach der Konfiguration von Config Sync ausgeführt werden, da das Kubernetes-Dienstkonto erst erstellt wird, wenn Sie Config Sync zum ersten Mal konfigurieren. Sie müssen dies nur einmal pro Flotte tun. Führen Sie den folgenden Befehl aus, um die Bindung zu erstellen, mit der das Kubernetes-Dienstkonto als Google-Dienstkonto fungieren kann:

gcloud iam service-accounts add-iam-policy-binding \
    GSA_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com \
    --role=roles/iam.workloadIdentityUser \
    --member="serviceAccount:FLEET_HOST_PROJECT_ID.s3ns.svc.id.goog[config-management-system/KSA_NAME]" \
    --project=PROJECT_ID

Ersetzen Sie Folgendes:

• FLEET_HOST_PROJECT_ID: Wenn Sie die Workload Identity-Föderation für GKE verwenden, ist der Wert derselbe wie PROJECT_ID. Wenn Sie die Workload Identity-Föderation für GKE für Flotten verwenden, verwenden Sie die Projekt-ID der Flotte, für die Ihr Cluster registriert ist, als Wert.
• GSA_NAME: Benutzerdefiniertes Google-Dienstkonto, das Sie zum Herstellen einer Verbindung zu Secure Source Manager oder Cloud Source Repositories verwenden möchten.
• KSA_NAME: Kubernetes-Dienstkonto für den Abgleich. In den meisten Fällen ist der Wert root-sync, da Config Sync automatisch ein RootSync-Objekt namens root-sync erstellt, wenn es mit der Cloud de Confiance Console oder der Google Cloud CLI installiert wird. Verwenden Sie andernfalls root-reconciler-ROOT_SYNC_NAME als Wert.

Wenn Sie Probleme beim Herstellen einer Verbindung zu Config Sync mit einem Google-Dienstkonto haben, lesen Sie den Artikel Berechtigungsprobleme mit einem Google-Dienstkonto beheben.

Compute Engine-Standarddienstkonto verwenden

Wenn Sie die Workload Identity-Föderation für GKE nicht aktiviert haben, können Sie sich alternativ zu einem Google-Dienstkonto mit einem Compute Engine-Dienstkonto authentifizieren. Diese Methode wird nur für Repositories in Secure Source Manager und Cloud Source Repositories unterstützt.

Wenn Sie Config Sync Lesezugriff auf Ihr Repository mit einem Compute Engine-Standarddienstkonto gewähren möchten, weisen Sie dem Standarddienstkonto die Rolle roles/source.reader zu:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:PROJECT_NUMBER-compute@developer.s3ns-system.iam.gserviceaccount.com"

Ersetzen Sie Folgendes:

• PROJECT_ID: Ihre Projekt-ID.
• PROJECT_NUMBER: Ihre Projektnummer.

Verwenden Sie bei der Installation von Config Sync Google Cloud Repository (gcenode) als Authentifizierungstyp.

GitHub-App verwenden

Wenn sich Ihr Repository in GitHub befindet, können Sie die GitHub-App verwenden, um Ihr Repository mit Config Sync zu verbinden:

1. Folgen Sie der Anleitung auf GitHub um eine GitHub-App bereitzustellen und ihr die Berechtigung zu erteilen, Daten aus Ihrem Repository zu lesen.

2. Fügen Sie die GitHub-App-Konfiguration einem neuen Secret im Cluster hinzu. Verwenden Sie dazu entweder die Client- oder die Anwendungs-ID:

   Client-ID

   kubectl create ns config-management-system && \
   kubectl create secret generic git-creds \
     --namespace=config-management-system \
     --from-literal=github-app-client-id=CLIENT_ID \
     --from-literal=github-app-installation-id=INSTALLATION_ID \
     --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
     --from-literal=github-app-base-url=BASE_URL
   

   • Ersetzen Sie CLIENT_ID durch die Client-ID für die GitHub-App.
   • Ersetzen Sie INSTALLATION_ID durch die Installations-ID für die GitHub-App.
   • Ersetzen Sie /path/to/GITHUB_PRIVATE_KEY durch den Namen der Datei mit dem privaten Schlüssel.
   • Ersetzen Sie BASE_URL durch die Basis-URL für den GitHub-API-Endpunkt. Dieser Wert ist nur erforderlich, wenn das Repository nicht unter www.github.com gehostet wird. Andernfalls kann das Argument weggelassen werden und der Standardwert https://api.github.com/ wird verwendet.

   Anwendungs-ID

   kubectl create ns config-management-system && \
   kubectl create secret generic git-creds \
       --namespace=config-management-system \
       --from-literal=github-app-application-id=APPLICATION_ID \
       --from-literal=github-app-installation-id=INSTALLATION_ID \
       --from-file=github-app-private-key=/path/to/GITHUB_PRIVATE_KEY \
       --from-literal=github-app-base-url=BASE_URL
   

   • Ersetzen Sie APPLICATION_ID durch die Anwendungs-ID für die GitHub-App.
   • Ersetzen Sie INSTALLATION_ID durch die Installations-ID für die GitHub-App.
   • Ersetzen Sie /path/to/GITHUB_PRIVATE_KEY durch den Namen der Datei mit dem privaten Schlüssel.
   • Ersetzen Sie BASE_URL durch die Basis-URL für den GitHub-API-Endpunkt. Dieser Wert ist nur erforderlich, wenn das Repository nicht unter www.github.com gehostet wird. Andernfalls kann das Argument weggelassen werden und der Standardwert https://api.github.com/ wird verwendet.

Verwenden Sie bei der Installation von Config Sync die GitHub-App (githubapp) als Authentifizierungstyp.

Fehlerbehebung

Hilfe bei der Behebung von Problemen im Zusammenhang mit der Verbindung von Config Sync zu Ihrer „Source of Truth“ finden Sie in den folgenden Themen zur Fehlerbehebung:

• Verbindung zur „Source of Truth“ herstellen
• Berechtigungsprobleme mit einem Google-Dienstkonto

Nächste Schritte

• Config Sync mit Standardeinstellungen installieren
• Config Sync-Installation anpassen