Authentifizierung für Docker einrichten

Auf dieser Seite wird beschrieben, wie Sie Docker für die Authentifizierung bei Docker Art-Repositories mit Artifact Registry konfigurieren.

Sie müssen die Authentifizierung für Google Cloud-Dienste nicht konfigurieren, aber Sie sollten überprüfen, ob die erforderlichen Berechtigungen konfiguriert sind.

Hinweis

1. Überprüfen Sie, ob Sie die Artifact Registry API aktiviert und das Cloud SDK-Release installiert haben. Anleitungen finden Sie unter Dienst aktivieren und deaktivieren.
2. Wenn das Ziel-Repository nicht vorhanden ist, erstellen Sie ein neues Repository.
3. (Optional) Konfigurieren Sie die Standardeinstellungen für gcloud-Befehle.
4. Achten Sie darauf, dass das für die Authentifizierung verwendete Konto Berechtigungen für den Zugriff auf Artifact Registry hat. Wir empfehlen die Verwendung eines Dienstkontos statt eines Nutzerkontos.
5. Installieren Sie Docker, falls es noch nicht installiert ist. Docker ist in Cloud Shell enthalten.

6. 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.

   Hinweis: Die Docker-Sicherheitsgruppe hat dieselben Zugriffsrechte wie der Root- oder Administratornutzer. Fügen Sie nur vertrauenswürdige Nutzer hinzu, die Zugriff auf Docker benötigen. Weitere Informationen zu den Auswirkungen auf die Sicherheit finden Sie unter Sicherheit des Docker-Daemon.

Authentifizierungsmethode auswählen

Die folgenden Authentifizierungsmethoden sind verfügbar:

gcloud Credential Helper (empfohlen)

Konfigurieren Sie Ihre Artifact 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 Docker 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 des gcloud-Tools 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.

Warnung: Docker Credential Helper wird nur für Docker 18.03 oder höher unterstützt. Ein Programmfehler in früheren Versionen des Docker-Clients verlangsamt docker build drastisch, wenn Credential Helper konfiguriert sind.

Sie sollten nur dann eine der alternativen Authentifizierungsoptionen verwenden, wenn Sie gcloud Credential Helper nicht optimal nutzen und wenn Sie wissen, wie sich die Verwendung der anderen Optionen auf die Sicherheit auswirkt.

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:

credHelepers

Wenn Sie Docker Credential Helper für die Authentifizierung von Artifact 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 sowohl die credHelpers- als auch die auths-Abschnitte Artifact Registry-Einstellungen enthält, werden die Einstellungen im Abschnitt auths ignoriert.

gcloud Credential Helper (empfohlen)

Wir empfehlen dringend, diese Methode nach Möglichkeit zu verwenden. Sie gewährleistet sicheren Zugriff auf Ihre Projektressourcen für beschränkte 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 authentifizieren Sie sich bei Artifact Registry:

1. Melden Sie sich im Cloud SDK als den Nutzer an, der die 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

     • ACCOUNT ist der Name des Dienstkontos im Format [e-mail]. Sie können vorhandene Dienstkonten auf der Seite Dienstkonten der Cloud Console oder mit dem Befehl gcloud iam service-accounts list aufrufen.
     • KEY-FILE ist die Dienstkonto-Schlüsseldatei. Informationen zum Erstellen eines Schlüssels finden Sie in der Dokumentation zur Identitäts- und Zugriffsverwaltung (Identity and Access Management, IAM).

2. Führen Sie dazu diesen Befehl aus:

   gcloud auth configure-docker HOSTNAME-LIST
   

   Dabei ist HOSTNAME-LIST eine durch Kommas getrennte Liste von Repository-Hostnamen, die der Credential Helper-Konfiguration hinzugefügt werden sollen.

   Führen Sie beispielsweise den folgenden Befehl aus, um die Regionen us-central1 und asia-northeast1 hinzuzufügen:

   gcloud auth configure-docker us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
   

   Die angegebenen Repository-Standorte werden der Credential Helper-Konfiguration hinzugefügt. Sie können der Konfiguration später weitere Standorte hinzufügen, indem Sie den Befehl noch einmal ausführen.

   Führen Sie den folgenden Befehl aus, um eine Liste der unterstützten Repository-Speicherorte anzuzeigen:

   gcloud artifacts locations list
   

   Ihre Anmeldedaten werden im Basisverzeichnis des Nutzers gespeichert.

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

3. Für Docker müssen sich Credential Helper im System-PATH befinden. Prüfen Sie, ob der Befehl gcloud im System PATH ist.

Hinweis :Wenn Sie Docker-Befehle unter Linux mit sudo normalerweise ausführen, sucht Docker nach /root/.docker/config.json Artifact Registry-Anmeldedaten. anstelle von $HOME/.docker/config.json. Wenn Sie sudo mit docker-Befehlen anstelle der Docker-Sicherheitsgruppe verwenden möchten, konfigurieren Sie die Anmeldedaten stattdessen mit sudo gcloud auth configure-docker.

Eigenständiger Credential Helper

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

Mit dem eigenständigen Docker Credential Helper werden Ihre Artifact Registry-Anmeldedaten abgerufen und in die Docker-Konfigurationsdatei geschrieben. Auf diese Weise können Sie das Docker-Befehlszeilentool docker verwenden, um direkt mit Artifact Registry zu interagieren.

So verwenden Sie Docker Credential Helper:

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

2. Laden Sie den eigenständigen Docker Credential Helper von GitHub 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
   
   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/bin/docker-credential-gcr && chmod +x /usr/bin/docker-credential-gcr
   

3. Konfigurieren Sie Docker so, dass die Anmeldedaten von Artifact Registry für die Interaktion mit Artifact Registry verwendet werden. Sie müssen dies nur einmal tun:

   docker-credential-gcr configure-docker --registries=HOSTNAME-LIST
   

   Dabei ist HOSTNAME-LIST eine durch Kommas getrennte Liste von Repository-Hostnamen, die der Credential Helper-Konfiguration hinzugefügt werden sollen.

   Führen Sie beispielsweise den folgenden Befehl aus, um die Regionen us-central1 und asia-northeast1 hinzuzufügen:

   docker-credential-gcr configure-docker --registries=us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
   

   Die angegebenen Repository-Standorte werden der Credential Helper-Konfiguration hinzugefügt. Sie können der Konfiguration später weitere Standorte hinzufügen, indem Sie den Befehl noch einmal ausführen.

   Führen Sie den folgenden Befehl aus, um eine Liste der unterstützten Repository-Speicherorte anzuzeigen:

   gcloud artifacts locations list
   

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

   Hinweis: Wenn Sie normalerweise Docker-Befehle unter Linux mit sudo ausführen, sucht Docker in /root/.docker/config.json statt in $HOME/.docker/config.json nach Artifact Registry-Anmeldedaten. Wenn Sie sudo mit docker-Befehlen anstelle der Docker-Sicherheitsgruppe verwenden möchten, konfigurieren Sie die Anmeldedaten stattdessen mit sudo docker-credential-gcr configure-docker.

   Ihre Anmeldedaten werden im Basisverzeichnis des Nutzers gespeichert.

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

4. Für Docker müssen sich Credential Helper im System-PATH befinden. Prüfen Sie, ob der Befehl docker-credential-gcr im System PATH ist.

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

Zugriffstoken

Zugriffstokens sind kurzlebige Tokens, die Zugriff auf Ihre Google Cloud-Ressourcen gewähren. 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.

So verwenden Sie ein Zugriffstoken:

1. Erstellen Sie ein Dienstkonto, das im Namen Ihrer Anwendung agieren soll, oder wählen Sie ein vorhandenes Dienstkonto für die Automatisierung aus.

   Sie benötigen den Speicherort der Dienstkonto-Schlüsseldatei, um damit die Authentifizierung bei Artifact Registry einzurichten. Auf der Seite „Dienstkonten“ können Sie die Schlüssel vorhandener Konten aufrufen und neue Schlüssel erstellen.

   Zur Seite „Dienstkonten“

2. Weisen Sie dem Dienstkonto die entsprechende Artifact Registry-Rolle zu, um Zugriff auf das Repository zu gewähren.

3. Weisen Sie der Variablen GOOGLE_APPLICATION_CREDENTIALS den Speicherort des Dienstkontoschlüssels zu, damit die Artifact Registry-Credential Helper Ihren Schlüssel beim Herstellen einer Verbindung zu Repositories abrufen können.

   export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
   

   Dabei ist KEY-FILE der Pfad zur Schlüsseldatei des Dienstkontos.

4. Rufen Sie zur Authentifizierung bei Artifact Registry mit Docker ein Zugriffstoken ab.

   Linux/macOS

   Führen Sie dazu diesen Befehl aus:

   gcloud auth application-default print-access-token | docker login -u oauth2accesstoken \
   --password-stdin https://LOCATION-docker.pkg.dev
   

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

   docker login -u oauth2accesstoken -p "$(gcloud auth application-default print-access-token)" \
   https://LOCATION-docker.pkg.dev
   

   Dabei gilt:

   • oauth2accesstoken ist der Nutzername, der zur Authentifizierung mit einem Zugriffstoken verwendet werden soll.
   • gcloud auth application-default print-access-token ist der gcloud-Befehl, um das Zugriffstoken für das Dienstkonto abzurufen. Das Zugriffstoken ist das Passwort für die Authentifizierung.
   • LOCATION ist der regionale oder multiregionale Speicherort des Repositorys, in dem das Image gespeichert ist.

   Windows

   Führen Sie dazu diesen Befehl aus:

   gcloud auth application-default print-access-token
   ya29.8QEQIfY_...
   
   docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
   https://LOCATION-docker.pkg.dev/<var>PROJECT-ID</var>/<var>REPOSITORY</var>
   

   Dabei gilt:

   • oauth2accesstoken ist der Nutzername, der zur Authentifizierung mit einem Zugriffstoken verwendet werden soll.
   • gcloud auth application-default print-access-token ist der gcloud-Befehl zum Abrufen des Zugriffstokens. Ihr Zugriffstoken ist das Passwort für die Authentifizierung.
   • LOCATION ist der regionale oder multiregionale Speicherort des Repositorys, in dem das Image gespeichert ist.

Docker ist jetzt bei Artifact Registry authentifiziert.

JSON-Schlüsseldatei

Hinweis: Verwenden Sie nach Möglichkeit ein Zugriffstoken oder eine andere verfügbare Authentifizierungsmethode, um das Risiko eines unberechtigten Zugriffs auf Ihre Artefakte zu verringern.

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. Beachten Sie, 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.

Verwenden Sie die folgenden Richtlinien, um den Zugriff auf Ihre Repositories einzuschränken:

• Erstellen Sie dedizierte Dienstkonten, die nur für die Interaktion mit Repositories verwendet werden.
• Gewähren Sie die Rolle Artifact Registry für den vom Dienstkonto erforderlichen Zugriff. Beispielsweise benötigt ein Dienstkonto, das nur Artefakte herunterlädt, nur die Rolle Artifact Registry-Leser.
• Konfigurieren Sie die Berechtigungen für Ihre dedizierten Dienstkonten für jedes Repository und nicht auf Projektebene. Anschließend können Sie den Zugriff basierend auf dem Repository-Kontext festlegen. Beispielsweise kann ein Dienstkonto für Entwicklungs-Builds die Rolle Artifact Registry-Leser für ein Produktions-Repository und die Artifact Registry-Autor-Rolle für ein Staging-Repository haben.
• Folgen Sie den Best Practices für die Verwaltung von Anmeldedaten.

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

1. Erstellen Sie ein Dienstkonto, das im Namen Ihrer Anwendung agieren soll, oder wählen Sie ein vorhandenes Dienstkonto für die Automatisierung aus.

   Sie benötigen den Speicherort der Dienstkonto-Schlüsseldatei, um damit die Authentifizierung bei Artifact Registry einzurichten. Auf der Seite „Dienstkonten“ können Sie die Schlüssel vorhandener Konten aufrufen und neue Schlüssel erstellen.

   Zur Seite „Dienstkonten“

2. Sie können den gesamten Inhalt der Schlüsseldatei optional base64-codieren.

   Linux

   base64 FILE-NAME > NEW-FILE-NAME
   

   macOS

   base64 -i FILE-NAME -o NEW-FILE-NAME
   

   Windows

   Base64.exe -e FILE-NAME > NEW-FILE-NAME
   

   Dabei ist FILE-NAME der ursprüngliche Schlüsseldatei und NEW-FILE-NAME Ihre base64-codierte Schlüsseldatei.

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, um die Integration in Docker zu konfigurieren:

   Linux/macOS

   Führen Sie dazu diesen Befehl aus:

   cat KEY-FILE | docker login -u KEY-TYPE --password-stdin \
   https://LOCATION-docker.pkg.dev
   

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

   docker login -u KEY-TYPE -p "$(cat FILE-NAME.json)" \
   https://LOCATION-docker.pkg.dev
   

   Dabei gilt:

   • KEY-TYPE ist einer der folgenden Werte:
     • _json_key, wenn Sie den Dienstkontoschlüssel im JSON-Format verwenden, wie er beim Erstellen der Datei angegeben wurde.
     • _json_key_base64, wenn Sie den gesamten Inhalt der Datei base64-codiert haben.
   • KEY-FILE ist der Name der Dienstkonto-Schlüsseldatei im JSON-Format.
   • LOCATION ist der regionale oder multiregionale Speicherort des Repositorys, an dem das Image gespeichert wird.

   Windows

   Führen Sie dazu diesen Befehl aus:

   docker login -u KEY-TYPE --password-stdin https://LOCATION-docker.pkg.dev < KEY-FILE
   

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

   set /p PASS=<KEY-FILE
   docker login -u KEY-TYPE -p "%PASS%" https://LOCATION-docker.pkg.dev
   

   Dabei gilt:

   • KEY-TYPE ist einer der folgenden Werte:
     • _json_key, wenn Sie den Dienstkontoschlüssel im JSON-Format verwenden, wie er beim Erstellen der Datei angegeben wurde.
     • _json_key_base64, wenn Sie den gesamten Inhalt der Datei base64-codiert haben.
   • KEY-FILE ist der Name der Dienstkonto-Schlüsseldatei im JSON-Format.
   • LOCATION ist der regionale oder multiregionale Speicherort des Repositorys, an dem das Image gespeichert wird.

Docker ist jetzt bei Artifact Registry authentifiziert.