Artifact Registry bietet die Funktionen von Container Registry und wird empfohlen, um Container-Images und andere Artefakte in Google Cloud zu verwalten. Weitere Informationen zur Umstellung auf Artifact Registry

Authentifizierungsmethoden

Auf dieser Seite wird gezeigt, wie Sie den Client eines Drittanbieters für die Authentifizierung bei Container Registry konfigurieren.

Google Cloud-Dienste, die in Container Registry eingebunden werden, sind mit Berechtigungen für den Zugriff auf Repositories im selben Projekt vorkonfiguriert. Für diese Dienste müssen Sie die Authentifizierung nicht konfigurieren. Sie sollten aber prüfen, ob die Berechtigungen ordnungsgemäß konfiguriert sind.

Hinweis

  1. Prüfen Sie, ob die Container Registry API aktiviert und das Cloud SDK installiert ist. Eine Anleitung finden Sie unter Dienst aktivieren und deaktivieren.
  2. Achten Sie darauf, dass das Konto, das Sie für die Authentifizierung verwenden, Berechtigungen zum Zugriff auf Container Registry hat. Wir empfehlen die Verwendung eines Dienstkontos anstelle eines Nutzerkontos.

  3. Installieren Sie Docker, falls es noch nicht installiert ist. Docker ist in Cloud Shell enthalten.

  4. Docker benötigt für die Interaktion mit Registries Zugriff. Fügen Sie unter Linux oder Windows den Nutzer hinzu, mit dem Sie Docker-Befehle in der Docker-Sicherheitsgruppe ausführen. Dieser Schritt ist nicht für Mac OS erforderlich, da Docker Desktop auf einer virtuellen Maschine als Root-Nutzer ausgeführt wird.

    Linux

    Die Docker-Sicherheitsgruppe heißt docker. Führen Sie den folgenden Befehl aus, um Ihren Nutzernamen hinzuzufügen:

    sudo usermod -a -G docker ${USER}
    

    Windows

    Die Docker-Sicherheitsgruppe heißt docker-users. Führen Sie den folgenden Befehl aus, um einen Nutzer über die Administrator-Eingabeaufforderung hinzuzufügen:

    net localgroup docker-users DOMAIN\USERNAME /add
    

    Dabei gilt:

    • DOMAIN ist Ihre Windows-Domain.
    • USERNAME ist Ihr Nutzername.

    Melden Sie sich ab und wieder an, damit Änderungen an der Gruppenmitgliedschaft wirksam werden. Wenn Sie eine virtuelle Maschine verwenden, müssen Sie sie unter Umständen neu starten, damit die Mitgliedschaftsänderungen wirksam werden.

Authentifizierungsmethoden

Sie müssen alle Drittanbieterclients konfigurieren, die auf Container Registry zugreifen sollen.

Die folgenden Authentifizierungsmethoden sind verfügbar:

gcloud Credential Helper (empfohlen)
Konfigurieren Sie Ihre Container Registry-Anmeldedaten für die Verwendung mit Docker direkt in gcloud. Verwenden Sie diese Methode nach Möglichkeit, um einen sicheren, kurzzeitigen Zugriff auf Ihre Projektressourcen zu gewähren. Diese Option unterstützt nur Docker-Versionen ab 18.03.
Eigenständiger Credential Helper
Diese Option dient hauptsächlich zur Konfiguration Ihrer Anmeldedaten zur Verwendung mit Docker, wenn kein Cloud SDK vorhanden ist. Diese Option unterstützt nur Docker-Versionen ab 18.03.
Zugriffstoken
Standardanmeldedaten für Anwendungen stellen kurzlebige Zugriffstokens bereit, die ein Dienstkonto für den Zugriff auf Ihre Google Cloud-Ressourcen verwendet. Es ist die sicherste Alternative zur Verwendung von gcloud als Credential Helper.
JSON-Schlüsseldatei

Ein vom Nutzer verwaltetes Schlüsselpaar, das Sie als Anmeldedaten für ein Dienstkonto verwenden können. Da die Anmeldedaten langlebig sind, ist es die sicherste Option aller verfügbaren Authentifizierungsmethoden.

Verwenden Sie nach Möglichkeit ein Zugriffstoken oder eine andere verfügbare Authentifizierungsmethode, um das Risiko eines unberechtigten Zugriffs auf Ihre Artefakte zu verringern. Wenn Sie einen Dienstkontoschlüssel verwenden müssen, folgen Sie den Best Practices für die Verwaltung von Anmeldedaten.

Einige Tools oder Workflows bieten keinen guten Support für die Verwendung von gcloud als Credential Helper. Wenn Sie eine der alternativen Optionen verwenden, müssen Sie die Auswirkungen auf die Sicherheit verstehen.

Authentifizierungseinstellungen in der Docker-Konfigurationsdatei

Docker speichert die Authentifizierungseinstellungen in der Konfigurationsdatei config.json.

  • Linux: ~/.docker/config.json
  • Windows: %USERPROFILE%\.docker\config.json

In der Datei gibt es verschiedene Abschnitte für verschiedene Authentifizierungsmethoden:

credHelpers
Wenn Sie Docker Credential Helper für die Authentifizierung von Container Registry verwenden, werden die Credential Helper-Einstellungen im Abschnitt credHelpers der Datei gespeichert.
auths
Wenn Sie Docker zur Anmeldung mit einem Token oder Dienstkontoschlüssel als Passwort verwenden, speichert Docker eine base64-codierte Version Ihrer Anmeldedaten imauths der Datei.
credStore
Wenn Sie einen Anmeldedatenspeicher zum Verwalten Ihrer Anmeldedaten konfiguriert haben, befinden sich die Einstellungen für den Anmeldedatenspeicher im Abschnitt credStore der Datei.

Wenn Docker eine Verbindung zu einer Registry herstellt, wird zuerst geprüft, ob ein Credential Helper mit dem Host verknüpft ist. Wenn Ihr config.json also Container Registry-Einstellungen im Abschnitt credHelpers und auths enthält, werden die Einstellungen im Abschnitt auths ignoriert.

gcloud Credential Helper

Wir empfehlen dringend, diese Methode nach Möglichkeit zu verwenden. Sie gewährleistet den sicheren Zugriff auf Ihre Projektressourcen für begrenzte Zeit.

Verwenden Sie das gcloud-Tool, um die Authentifizierung in Cloud Shell oder in einer Umgebung zu konfigurieren, in der das Cloud SDK installiert ist. Cloud Shell enthält eine aktuelle Version von Docker.

So konfigurieren Sie die Authentifizierung:

  1. Melden Sie sich in gcloud als Nutzer an, der Docker-Befehle ausführt.

    • Führen Sie den folgenden Befehl aus, um die Authentifizierung mit Nutzeranmeldedaten zu konfigurieren:

      gcloud auth login
      
    • Führen Sie den folgenden Befehl aus, um die Authentifizierung mit Dienstkonto-Anmeldedaten zu konfigurieren:

      gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
      

      Wo

  2. Konfigurieren Sie Docker mit dem folgenden Befehl:

    gcloud auth configure-docker
    

    Ihre Anmeldedaten werden im Basisverzeichnis des Nutzers gespeichert.

    • Linux: $HOME/.docker/config.json
    • Windows: %USERPROFILE%/.docker/config.json

Eigenständiger Credential Helper

Der eigenständige Docker Credential Helper konfiguriert Docker für die Authentifizierung bei Container Registry auf einem System, auf dem das Cloud SDK nicht verfügbar ist.

Credential Helper ruft Ihre Container Registry-Anmeldedaten ab. Dies geschieht entweder automatisch oder von einem mit dem Flag --token-source angegebenen Speicherort. Dann schreibt er die Daten in die Konfigurationsdatei von Docker. Auf diese Weise können Sie das docker-Befehlszeilentool von Docker verwenden, um direkt mit Container Registry zu interagieren.

So konfigurieren Sie die Authentifizierung:

  1. Melden Sie sich auf dem Computer als der Nutzer an, der Docker-Befehle ausführt.

  2. Laden Sie docker-credential-gcr aus GitHub unter "Releases" herunter:

    Sie können optional das curl-Befehlszeilentool verwenden. Beispiel:

    VERSION=2.0.0
    OS=linux  # or "darwin" for OSX, "windows" for Windows.
    ARCH=amd64  # or "386" for 32-bit OSs, "arm64" for ARM 64.
    
    curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \
    | tar xz --to-stdout ./docker-credential-gcr \
    > /usr/local/bin/docker-credential-gcr && chmod +x /usr/local/bin/docker-credential-gcr
    
  3. Konfigurieren Sie Docker mit dem folgenden Befehl:

    docker-credential-gcr configure-docker
    

    Ihre Anmeldedaten werden im Basisverzeichnis des Nutzers gespeichert.

    • Linux: $HOME/.docker/config.json
    • Windows: %USERPROFILE%/.docker/config.json

Weitere Informationen finden Sie in der Dokumentation zum eigenständigen Docker-Credential Helper auf GitHub.

Docker ist jetzt für die Authentifizierung bei Container Registry konfiguriert. Um Images hoch- und herunterladen zu können, müssen die Berechtigungen richtig konfiguriert sein.

Zugriffstoken

Ein Zugriffstoken sind kurzlebige Anmeldedaten, die Zugriff auf Ihre Google Cloud-Ressourcen ermöglicht. Da das Token 60 Minuten lang gültig ist, sollten Sie es weniger als eine Stunde vor dem Herstellen einer Verbindung zu Container Registry anfordern.

Google Cloud ruft ein Zugriffstoken mit den Standardanmeldedaten für Anwendungen ab. Das Token läuft nach 60 Minuten ab.

  1. Erstellen Sie ein neues Dienstkonto, das mit Container Registry interagiert.

    Console

    1. Rufen Sie in der Google Cloud Console die Seite Dienstkonto erstellen auf.

      Zur Seite "Dienstkonto erstellen"

    2. Wählen Sie das Projekt aus, das Sie verwenden möchten.

    3. Geben Sie im Feld Dienstkontoname einen Namen ein.

    4. Optional: Geben Sie im Feld Dienstkontobeschreibung eine Beschreibung ein.

    5. Klicken Sie auf Erstellen.

    6. Klicken Sie auf das Feld Rolle auswählen. Wählen Sie unter Alle Rollen eine entsprechende Cloud Storage-Rolle basierend auf den Berechtigungen aus, die Sie dem Dienstkonto gewähren möchten.

    7. Klicken Sie auf Fertig.

    gcloud

    Sie können die folgenden Befehle mit dem Cloud SDK auf Ihrem lokalen Rechner oder in Cloud Shell ausführen.

    1. Erstellen Sie das Dienstkonto. Ersetzen Sie NAME durch einen Namen für das Dienstkonto.

      gcloud iam service-accounts create NAME
      
    2. Weisen Sie dem Dienstkonto eine Rolle zu. Ersetzen Sie PROJECT_ID durch die Projekt-ID und ROLE durch die entsprechende Cloud Storage-Rolle für das Dienstkonto. Diese Rolle gilt für alle Repositories im Projekt. Sie können die Rolle später ändern und dem Dienstkonto für bestimmte Repositories verschiedene Rollen zuweisen.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
      
  2. Rufen Sie einen Schlüssel für das Dienstkonto ab, das mit Container Registry interagiert.

    Console

    1. Rufen Sie in der Cloud Console die Seite Dienstkonten auf.

      Zur Seite „Dienstkonten“

    2. Klicken Sie auf die E-Mail-Adresse des Dienstkontos, das Sie verwenden möchten.

    3. Klicken Sie auf Schlüssel.

    4. Klicken Sie auf SCHLÜSSEL HINZUFÜGEN > Neuen Schlüssel erstellen.

    5. Klicken Sie auf Erstellen. Eine JSON-Datei mit Ihrem Schlüssel wird auf Ihren Computer heruntergeladen.

      In der Anleitung auf dieser Seite wird der Dateiname keyfile.json für diese Schlüsseldatei verwendet.

    6. Klicken Sie auf Schließen.

    gcloud

    Sie können den folgenden Befehl mit dem Cloud SDK auf Ihrem lokalen Rechner oder in Cloud Shell ausführen.

    In der Anleitung auf dieser Seite wird der Dateiname keyfile.json für die Schlüsseldatei verwendet.

    gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com
    
  3. Führen Sie den folgenden Befehl aus, um sich beim Cloud SDK als Dienstkonto anzumelden.

    gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
    

    Dabei gilt:

    • ACCOUNT ist der Name des Dienstkontos im Format [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com.
    • KEY-FILE ist die Dienstkonto-Schlüsseldatei. Weitere Informationen zum Erstellen eines Schlüssels erhalten Sie in der IAM-Dokumentation.
  4. Prüfen Sie, ob die Berechtigungen für das Dienstkonto ordnungsgemäß konfiguriert sind. Wenn Sie das Compute Engine-Dienstkonto verwenden, müssen Sie sowohl Berechtigungen als auch Zugriffsbereiche richtig konfigurieren.

  5. Rufen Sie ein Zugriffstoken für das Dienstkonto ab. Da das Token nur kurzlebig ist, fordern Sie es innerhalb von weniger als einer Stunde an, bevor Sie es zur Verbindung mit Container Registry verwenden.

    Linux/macOS

    • Nutzername ist oauth2accesstoken.
    • Passwort ist Ihr Zugriffstoken. Beispiel: gcloud auth print-access-token

    Beispiel:

    gcloud auth print-access-token | docker login -u oauth2accesstoken --password-stdin https://HOSTNAME
    

    Dabei ist HOSTNAME entweder gcr.io, us.gcr.io, eu.gcr.io oder asia.gcr.io.

    Alternative für ältere Docker-Clients, die --password-stdin nicht unterstützen:

    docker login -u oauth2accesstoken -p "$(gcloud auth print-access-token)" https://HOSTNAME
    

    Windows

    • Nutzername ist oauth2accesstoken.
    • Passwort ist die Ausgabe von gcloud auth print-access-token.
    1. Rufen Sie das Zugriffstoken ab.
    gcloud auth print-access-token
    

    Der zurückgegebene String ist das Zugriffstoken, das Sie als Passwort verwenden. In diesem Beispiel steht ya29.8QEQIfY_... für das zurückgegebene Zugriffstoken.

    ya29.8QEQIfY_...
    
    1. Melden Sie sich mit dem Zugriffstoken an.
    docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." https://HOSTNAME
    

    Dabei ist HOSTNAME entweder gcr.io, us.gcr.io, eu.gcr.io oder asia.gcr.io.

Docker ist jetzt bei Container Registry authentifiziert.

JSON-Schlüsseldatei

Ein Dienstkontoschlüssel ist ein langlebiges Schlüsselpaar, das Sie als Anmeldedaten für ein Dienstkonto verwenden können. Sie sind für die Sicherheit des privaten Schlüssels und andere Schlüsselverwaltungsvorgänge wie die Schlüsselrotation verantwortlich.

Jeder, der Zugriff auf einen gültigen privaten Schlüssel für ein Dienstkonto hat, kann über das Dienstkonto auf Ressourcen zugreifen. Beispielsweise erhalten einige von Google Cloud automatisch erstellte Dienstkonten wie das Container Registry-Dienstkonto die Rolle Editor mit Lese- und Schreibberechtigungen für das übergeordnete Projekt. Das Compute Engine-Standarddienstkonto ist mit schreibgeschütztem Zugriff auf den Speicher innerhalb desselben Projekts konfiguriert.

Beachten Sie darüber hinaus, dass der Lebenszyklus des Schlüsselzugriffs auf das Dienstkonto (und damit die Daten, auf die das Dienstkonto Zugriff hat) vom Lebenszyklus des Nutzers unabhängig ist, der den Schlüssel heruntergeladen hat.

Richten Sie sich nach den folgenden Richtlinien, um den Zugriff auf Ihre Container-Images zu beschränken:

So erstellen Sie ein neues Dienstkonto und einen Dienstkontoschlüssel nur für die Verwendung mit Container Registry-Repositories:

  1. Erstellen Sie ein neues Dienstkonto, das mit Container Registry interagiert.

    Console

    1. Rufen Sie in der Google Cloud Console die Seite Dienstkonto erstellen auf.

      Zur Seite "Dienstkonto erstellen"

    2. Wählen Sie das Projekt aus, das Sie verwenden möchten.

    3. Geben Sie im Feld Dienstkontoname einen Namen ein.

    4. Optional: Geben Sie im Feld Dienstkontobeschreibung eine Beschreibung ein.

    5. Klicken Sie auf Erstellen.

    6. Klicken Sie auf das Feld Rolle auswählen. Wählen Sie unter Alle Rollen eine geeignete Cloud Storage-Rolle für das Dienstkonto aus.

    7. Klicken Sie auf Fertig.

    gcloud

    Sie können die folgenden Befehle mit dem Cloud SDK auf Ihrem lokalen Rechner oder in Cloud Shell ausführen.

    1. Erstellen Sie das Dienstkonto. Ersetzen Sie NAME durch einen Namen für das Dienstkonto.

      gcloud iam service-accounts create NAME
      
    2. Weisen Sie dem Dienstkonto eine Rolle zu. Ersetzen Sie PROJECT_ID durch die Projekt-ID und ROLE durch die entsprechende Cloud Storage-Rolle für das Dienstkonto.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
      
  2. Rufen Sie einen Schlüssel für das Dienstkonto ab, das mit Container Registry interagiert.

    Console

    1. Rufen Sie in der Cloud Console die Seite Dienstkonten auf.

      Zur Seite „Dienstkonten“

    2. Klicken Sie auf die E-Mail-Adresse des Dienstkontos, das Sie verwenden möchten.

    3. Klicken Sie auf Schlüssel.

    4. Klicken Sie auf SCHLÜSSEL HINZUFÜGEN > Neuen Schlüssel erstellen.

    5. Klicken Sie auf Erstellen. Eine JSON-Datei mit Ihrem Schlüssel wird auf Ihren Computer heruntergeladen.

      In der Anleitung auf dieser Seite wird der Dateiname keyfile.json für diese Schlüsseldatei verwendet.

    6. Klicken Sie auf Schließen.

    gcloud

    Sie können den folgenden Befehl mit dem Cloud SDK auf Ihrem lokalen Rechner oder in Cloud Shell ausführen.

    In der Anleitung auf dieser Seite wird der Dateiname keyfile.json für die Schlüsseldatei verwendet.

    gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com
    
  3. Prüfen Sie, ob die Berechtigungen für das Dienstkonto ordnungsgemäß konfiguriert sind. Wenn Sie das Compute Engine-Dienstkonto verwenden, müssen Sie sowohl Berechtigungen als auch Zugriffsbereiche richtig konfigurieren.

  4. Verwenden Sie den Dienstkontoschlüssel als Passwort für die Authentifizierung bei Docker.

    Linux/macOS

    • Nutzername ist _json_key (NICHT der Name Ihres Dienstkontos).
    • keyfile.json ist der von Ihnen erstellte Dienstkontoschlüssel.

    Beispiel:

    cat keyfile.json | docker login -u _json_key --password-stdin https://HOSTNAME
    

    Dabei ist HOSTNAME entweder gcr.io, us.gcr.io, eu.gcr.io oder asia.gcr.io.

    Alternative für ältere Docker-Clients, die --password-stdin nicht unterstützen:

    docker login -u _json_key -p "$(cat keyfile.json)" https://HOSTNAME
    

    Dabei ist HOSTNAME entweder gcr.io, us.gcr.io, eu.gcr.io oder asia.gcr.io.

    Windows

    • Nutzername ist _json_key (NICHT der Name Ihres Dienstkontos).
    • keyfile.json enthält den JSON-Schlüssel des Dienstkontos.

    Beispiel:

    docker login -u _json_key --password-stdin https://HOSTNAME < keyfile.json
    

    Dabei ist HOSTNAME entweder gcr.io, us.gcr.io, eu.gcr.io oder asia.gcr.io.

    Alternative für ältere Docker-Clients, die --password-stdin nicht unterstützen:

    set /p PASS=<keyfile.json
    docker login -u _json_key -p "%PASS%" https://HOSTNAME
    

    Dabei ist HOSTNAME entweder gcr.io, us.gcr.io, eu.gcr.io oder asia.gcr.io.

Docker ist jetzt bei Container Registry authentifiziert.