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 die Konfigurationen gelesen, auf Ihre Cluster angewendet und synchronisiert werden können.

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 „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, OCI, 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 OCI und Helm. Erfordert Tokenverwaltung. Tokens können ablaufen.
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 Verwendet IAM, wodurch das Speichern von Anmeldedaten in Kubernetes-Secrets vermieden wird. 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.

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 Identitätsföderation von Arbeitslasten 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 Flottenpakete wird Cloud Build zur Authentifizierung bei Git verwendet. So müssen Sie sich nur einmal pro Projekt authentifizieren und 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, müssen Sie die folgenden Aufgaben ausführen:

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 Passphrases nicht. Abhängig von Ihren Sicherheits- und Complianceanforderungen können Sie ein einzelnes 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, 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: Der Nutzername, den Config Sync zur Authentifizierung beim Repository verwenden soll. Wenn Sie einen Git-Repository-Host eines Drittanbieters wie GitHub verwenden oder ein Dienstkonto mit Secure Source Manager nutzen möchten, empfehlen wir, ein separates Konto für die Authentifizierung zu verwenden.
    • /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. In der folgenden Liste finden Sie Anleitungen für einige gängige Git-Hosting-Anbieter:

  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 Prü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.

Cookie-Datei 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.

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

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

  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 in dem Projekt gewähren, in dem sich Ihr verwalteter Cluster befindet. Sie müssen die folgenden Anforderungen erfüllen:

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

  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, je nach dem Repository-Typ, den Sie verwenden:

    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: 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/KUBERNETES_SERVICEACCOUNT]" \
    --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 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.
  • KUBERNETES_SERVICEACCOUNT: das Kubernetes-ServiceAccount für den Abgleich. In den meisten Fällen ist der Wert root-reconciler, 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 Workload Identity Federation 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 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.gserviceaccount.com"

Ersetzen Sie Folgendes:

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

Wenn Sie Config Sync installieren, verwenden Sie Google Cloud Repository (gcenode) als Authentifizierungstyp.

GitHub-App 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 zu 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

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

Nächste Schritte