Config Sync Zugriff auf Ihr Git-Repository gewähren

Auf dieser Seite wird beschrieben, wie Sie Config Sync für Ihr Git-Repository authentifizieren. Config Sync benötigt Lesezugriff auf Ihre Source of Truth, damit es Ihre Konfigurationen lesen, auf Ihre Cluster anwenden und synchronisieren kann.

Authentifizierungsmethode auswählen

Die Authentifizierungsmethode, die Sie verwenden, 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:

Methode Unterstützte Quellen Beschreibung Beschränkungen
Keine Authentifizierung Git, OCI, Helm Es ist keine zusätzliche Einrichtung erforderlich. Funktioniert nur, wenn Ihre Single Source of Truth öffentlich ist.
SSH-Schlüsselpaar Git Wird von den meisten Git-Anbietern unterstützt. Erfordert Schlüsselverwaltung. Wird für OCI oder Helm nicht unterstützt.
token Git, Helm Wird von den meisten Git-Anbietern unterstützt. Eine gute Alternative, wenn Ihre Organisation die Verwendung von SSH-Schlüsseln nicht zulässt. Unterstützt Nutzernamen und Passwörter für Helm. Erfordert die Verwaltung von Tokens. Tokens können ablaufen. Wird für OCI nicht unterstützt.
Kubernetes-Dienstkonto OCI, Helm IAM wird verwendet, um einem Kubernetes-Dienstkonto direkten Zugriff auf Artifact Registry zu gewähren. Erfordert, dass die Workload Identity-Föderation für GKE in Ihrem Cluster aktiviert ist. Wird für Git nicht unterstützt.
Google-Dienstkonto Git IAM wird verwendet, sodass keine Anmeldedaten in Kubernetes-Secrets gespeichert werden müssen. Empfohlen für Secure Source Manager und Cloud Source Repositories. Erfordert, dass die Workload Identity-Föderation für GKE in Ihrem Cluster aktiviert ist. Erfordert eine Konfiguration vor und nach der Installation von Config Sync auf Ihren Clustern. Nicht unterstützt für Repositories, die außerhalb von Secure Source Manager oder Cloud Source Repositories gehostet werden.
GitHub-App Git Direkte Integration in GitHub. Ermöglicht detaillierte Berechtigungen. Nur für in GitHub gehostete Repositories verfügbar. Wird nur in Config Sync Version 1.19.1 und höher unterstützt.

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

  • cookiefile wird möglicherweise nicht von allen Git-Anbietern 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, ist aber nicht empfehlenswert, da für die Kubernetes-Dienstkontomethode weniger Konfiguration erforderlich ist.

Authentifizierung mit Flottenpaketen

Wenn Sie Flottenpakete verwenden, müssen Sie die Anleitung auf dieser Seite nicht ausführen. Für die Authentifizierung bei Git wird Cloud Build verwendet. So müssen Sie den Zugriff nicht jedes Mal gewähren, wenn Sie Config Sync in einem Cluster installieren.

Hinweise

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

SSH-Schlüsselpaar verwenden

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

Führen Sie die folgenden Schritte aus, um Config Sync mithilfe eines SSH-Schlüsselpaars Lesezugriff auf Ihr Git-Repository zu gewähren:

  1. Erstellen Sie ein SSH-Schlüsselpaar oder bitten Sie Ihren Sicherheitsadministrator, eines bereitzustellen. Wenn Sie ein SSH-Schlüsselpaar erstellen müssen, erstellen Sie einen 4096-Bit-RSA-Schlüssel, indem Sie den folgenden Befehl ausführen:

    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: Der 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. Anleitungen für einige gängige Git-Hostanbieter finden Sie in der folgenden Liste:

  3. Erstellen Sie das git-creds-Secret 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 Verwendung der SSH-Authentifizierung konfigurieren möchten, fügen Sie den Schlüssel für bekannte 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 Prü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 die URL 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 einer cookiefile:

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

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 „cookiefile“ (cookiefile) als Authentifizierungstyp.

Token verwenden

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

Führen Sie die folgenden Schritte aus, um Config Sync mithilfe eines Tokens Lesezugriff auf Ihr Git-Repository zu gewähren:

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

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

    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 mithilfe eines Google-Dienstkontos Zugriff auf ein Repository im selben Projekt wie Ihren verwalteten Cluster gewähren. Sie müssen die folgenden Anforderungen erfüllen:

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

  1. Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Dienstkonto-Administrator (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 die IAM-Rolle zu. Das hängt vom verwendeten Repositorytyp ab:

    Secure Source Manager

    Weisen Sie dem Google-Dienstkonto die IAM-Rollen „Secure Source Manager Instance Accessor“ (roles/securesourcemanager.instanceAccessor) und „Secure Source Manager Repo Reader“ (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.iam.gserviceaccount.com"

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

      Ersetzen Sie Folgendes:

      • PROJECT_ID: Ihre Projekt-ID.
      • GSA_NAME: Der Name des Google-Dienstkontos, mit dem Sie eine Verbindung zu Secure Source Manager herstellen möchten.

    • Informationen zum Erteilen von repositoryspezifischen 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.iam.gserviceaccount.com"

      Ersetzen Sie Folgendes:

      • PROJECT_ID: Ihre Projekt-ID.
      • GSA_NAME: Name des Google-Dienstkontos, mit dem Sie eine Verbindung zu Cloud Source Repositories herstellen 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: Die JSON- oder YAML-Datei, die die Identity and Access Management-Richtlinie enthält.

    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.

Der folgende 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. Dies ist nur einmal pro Flotte erforderlich. Führen Sie den folgenden Befehl aus, um die Bindung zu erstellen, mit der das Kubernetes-Dienstkonto als Google-Dienstkonto verwendet werden kann:

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

Ersetzen Sie Folgendes:

  • FLEET_HOST_PROJECT_ID: Wenn Sie Workload Identity Federation for GKE verwenden, ist der Wert derselbe wie PROJECT_ID. Wenn Sie die Workload Identity Federation for GKE für Flotten verwenden, verwenden Sie die Projekt-ID der Flotte, für die Ihr Cluster registriert ist, als Wert.
  • GSA_NAME: Das benutzerdefinierte Google-Dienstkonto, das Sie für die Verbindung mit Secure Source Manager oder Cloud Source Repositories verwenden möchten.
  • KSA_NAME: das 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 Google Cloud 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 Abschnitt Berechtigungsprobleme mit einem Google-Dienstkonto beheben.

Compute Engine-Standarddienstkonto verwenden

Wenn Sie die Identitätsföderation von Arbeitslasten 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 schreibgeschützten Zugriff auf Ihr Repository gewähren möchten, indem Sie ein Compute Engine-Standarddienstkonto verwenden, 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.gserviceaccount.com"

Ersetzen Sie Folgendes:

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

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

GitHub-Anwendung verwenden

Wenn sich Ihr Repository auf 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 zum Lesen aus Ihrem Repository zu erteilen.

  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, die den privaten Schlüssel enthält.
    • Ersetzen Sie BASE_URL durch die Basis-URL für den GitHub-API-Endpunkt. Dieser Wert ist nur erforderlich, wenn das Repository nicht auf www.github.com gehostet wird. Andernfalls kann das Argument weggelassen werden. Der Standardwert ist https://api.github.com/.

    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, die den privaten Schlüssel enthält.
    • Ersetzen Sie BASE_URL durch die Basis-URL für den GitHub-API-Endpunkt. Dieser Wert ist nur erforderlich, wenn das Repository nicht auf www.github.com gehostet wird. Andernfalls kann das Argument weggelassen werden. Der Standardwert ist https://api.github.com/.

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

Fehlerbehebung

Wenn Sie Hilfe bei der Behebung von Problemen im Zusammenhang mit der Verbindung von Config Sync zu Ihrer „Source of Truth“ benötigen, lesen Sie die folgenden Themen zur Fehlerbehebung:

Nächste Schritte