Auf dieser Seite wird beschrieben, wie Sie Docker für die Authentifizierung bei Artifact Registry-Docker-Repositories konfigurieren.
Sie müssen die Authentifizierung für Cloud Build- oder Google Cloud-Laufzeitumgebungen wie Google Kubernetes Engine und Cloud Run nicht konfigurieren. Sie sollten jedoch prüfen, ob die erforderlichen Berechtigungen konfiguriert sind.
Hinweise
-
Installieren Sie die Google Cloud CLI und initialisieren Sie sie mit folgendem Befehl:
gcloud init
- (Optional) Konfigurieren Sie die Standardeinstellungen für gcloud-Befehle.
- Prüfen Sie, ob das für die Authentifizierung verwendete Konto Berechtigungen für den Zugriff auf Artifact Registry hat. Wir empfehlen die Verwendung eines Dienstkontos anstelle eines Nutzerkontos.
- Installieren Sie Docker, falls es noch nicht installiert ist. Docker ist in Cloud Shell enthalten.
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.
Authentifizierungsmethode auswählen
Die folgenden Authentifizierungsmethoden sind verfügbar:
- gcloud Credential Helper
- Konfigurieren Sie Ihre Artifact Registry-Anmeldedaten für die Verwendung mit Docker direkt in gcloud. Dies ist die einfachste Authentifizierungsmethode, kann aber auch langsamer sein als der eigenständige Credential Helper.
- Eigenständiger Docker Credential Helper
- Diese Option dient hauptsächlich zum Konfigurieren Ihrer Anmeldedaten für die Verwendung mit Docker, wenn die Google Cloud CLI nicht verwendet wird. Er ist erheblich schneller als gcloud Credential Helper und verwendet Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC), um Anmeldedaten in Ihrer Umgebung automatisch zu finden.
- Zugriffstoken
- Sie können ein kurzlebiges Zugriffstoken für ein Dienstkonto generieren und es dann für die Passwortauthentifizierung verwenden. Da das Token nur 60 Minuten lang gültig ist, ist es eine sicherere Option als ein Dienstkontoschlüssel.
- Dienstkontoschlüssel
- Ein nutzerverwaltetes Schlüsselpaar, das Sie als Anmeldedaten für ein Dienstkonto verwenden können. Da die Anmeldedaten langlebig sind, ist es die unsicherste Option aller verfügbaren Authentifizierungsmethoden.
Verwenden Sie nach Möglichkeit ein Zugriffstoken oder einen Credential Helper, um das Risiko nicht autorisierter Zugriffe auf Ihre Container-Images zu reduzieren. Wenn Sie einen Dienstkontoschlüssel verwenden müssen, folgen Sie den Best Practices für die Verwaltung von Anmeldedaten.
Authentifizierungseinstellungen in der Docker-Konfigurationsdatei
Docker speichert die Authentifizierungseinstellungen in der Konfigurationsdatei config.json.
- Linux:
~/.docker/config.json
- Windows:
%USERPROFILE%\.docker\config.json
Die Datei enthält separate Abschnitte für verschiedene Authentifizierungsmethoden:
credHelpers
- Wenn Sie Docker Credential Helper für die Authentifizierung verwenden, speichert Artifact Registry die Credential Helper-Einstellungen im Abschnitt
credHelpers
der Datei. auths
- Wenn Sie sich mit Docker mit einem Token oder Dienstkontoschlüssel als Passwort anmelden, speichert Docker eine base64-codierte Version Ihrer Anmeldedaten im
auths
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 nach einem Credential Helper gesucht, der dem Host zugeordnet ist. Wenn Ihr config.json
also Artifact Registry-Einstellungen sowohl im credHelpers
- als auch im auths
-Abschnitt enthält, werden die Einstellungen im auths
-Abschnitt ignoriert.
gcloud Credential Helper
Der gcloud Credential Helper bietet sicheren, kurzlebigen Zugriff auf Ihre Projektressourcen. Er konfiguriert Docker für die Authentifizierung bei Artifact Registry-Hosts in jeder Umgebung, in der die Google Cloud CLI installiert ist. Cloud Shell enthält die Google Cloud CLI und eine aktuelle Version von Docker.
Der gcloud Credential Helper ist die einfachste Authentifizierungsmethode, die eingerichtet werden kann. Es konfiguriert Docker mit den Anmeldedaten des aktiven Nutzers oder Dienstkontos in Ihrer gcloud-Sitzung. Da dieser Credential Helper von der gcloud CLI abhängt, kann er erheblich langsamer sein als der eigenständige Credential Helper. Verwenden Sie für automatisierte Builds mit Drittanbietertools oder Docker-Clients mit einer großen Anzahl von konfigurierten Registry-Hosts stattdessen den eigenständigen Credential Helper.
So authentifizieren Sie sich bei Artifact Registry:
Melden Sie sich bei der gcloud CLI als der 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
- ACCOUNT ist das Dienstkonto, das Sie mit Artifact Registry im Format
USERNAME@PROJECT-ID.iam.gserviceaccount.com
verwenden möchten. Wenn Sie ein vorhandenes Konto verwenden möchten, können Sie in der Google Cloud Console auf der Seite Dienstkonten oder mit dem Befehlgcloud iam service-accounts list
eine Liste der Dienstkonten 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).
- ACCOUNT ist das Dienstkonto, das Sie mit Artifact Registry im Format
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
undasia-northeast1
hinzuzufügen:gcloud auth configure-docker us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
Die angegebenen Hostnamen werden der Credential Helper-Konfiguration hinzugefügt. Sie können der Konfiguration später weitere Hostnamen 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
Der Befehl zeigt den Abschnitt
credHelpers
Ihrer aktuellen Docker-Konfiguration und die aktualisierte Konfiguration an, nachdem die angegebenen Hostnamen hinzugefügt wurden.Geben Sie
y
ein, um die Konfigurationsänderungen zu akzeptieren.Ihre Anmeldedaten werden im Basisverzeichnis des Nutzers gespeichert.
- Linux:
$HOME/.docker/config.json
- Windows:
%USERPROFILE%/.docker/config.json
- Linux:
Für Docker müssen sich Credential Helper im System-
PATH
befinden. Prüfen Sie, ob der Befehlgcloud
im SystemPATH
ist.
Eigenständiger Credential Helper
Der eigenständige Docker Credential Helper konfiguriert Docker für die Authentifizierung bei Artifact Registry auf einem System, auf dem die gcloud CLI nicht verfügbar ist. Er ist erheblich schneller als gcloud Credential Helper und verwendet Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC), um automatisch Anmeldedaten in Ihrer Umgebung zu finden. Für andere Vorgänge als das Hoch- und Herunterladen von Images, z. B. das Taggen oder Auflisten von Images. Wir empfehlen die Verwendung dieser Authentifizierungsmethode für automatisierte Builds mit Drittanbietertools oder Docker-Clients mit einer großen Anzahl von konfigurierten Registry-Hosts.
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:
Melden Sie sich auf dem Computer als der Nutzer an, der Docker-Befehle ausführt.
Laden Sie den eigenständigen Docker Credential Helper von GitHub herunter.
Sie können optional das
curl
-Befehlszeilentool verwenden. Beispiel:VERSION=2.1.20 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 docker-credential-gcr \ && chmod +x docker-credential-gcr && sudo mv docker-credential-gcr /usr/bin/
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
undasia-northeast1
hinzuzufügen:docker-credential-gcr configure-docker --registries=us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
Die angegebenen Hostnamen werden der Credential Helper-Konfiguration hinzugefügt. Sie können der Konfiguration später weitere Hostnamen 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.
Ihre Anmeldedaten werden im Basisverzeichnis des Nutzers gespeichert.
- Linux:
$HOME/.docker/config.json
- Windows:
%USERPROFILE%/.docker/config.json
- Linux:
Für Docker müssen sich Credential Helper im System-
PATH
befinden. Prüfen Sie, ob der Befehldocker-credential-gcr
im SystemPATH
ist.Führen Sie den folgenden Befehl aus, um zu prüfen, ob Credential Helper Ihre Anmeldedaten abrufen kann:
echo "https://HOSTNAME" | docker-credential-gcr get
Ersetzen Sie HOSTNAME durch einen Hostnamen, den Sie der Konfiguration hinzugefügt haben. Beispiel:
echo "https://us-central1-docker.pkg.dev" | docker-credential-gcr get
Wenn der Befehl erfolgreich ausgeführt wurde, enthält die zurückgegebene JSON-Ausgabe ein Token im Feld
Secret
. Beispiel:{"ServerURL":"https://us-central1-docker.pkg.dev","Username":"_dcgcr_2_0_0_token","Secret":"ya29..."}
Docker ist jetzt für die Authentifizierung bei Artifact Registry konfiguriert. Achten Sie darauf, dass die Berechtigungen richtig konfiguriert sind, wenn Sie Images hoch- und herunterladen möchten.
Zugriffstoken
Sie können ein kurzlebiges OAuth-Zugriffstoken generieren, um sich bei Artifact Registry zu authentifizieren. Da das Token 60 Minuten lang gültig ist, sollten Sie es weniger als eine Stunde anfordern, bevor Sie damit eine Verbindung zu Artifact Registry herstellen.
So verwenden Sie ein Zugriffstoken mit Anmeldedaten für ein Dienstkonto:
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.
Generieren Sie ein Zugriffstoken für das Dienstkonto und authentifizieren Sie sich mit einer der folgenden Optionen:
Wenn Sie Berechtigungen für die Rolle „Ersteller von Dienstkonto-Tokens“ (
roles/iam.serviceAccountTokenCreator
) haben, können Sie ein Dienstkonto übertragen, um ein Token dafür zu erhalten und sich dann als Dienstkonto zu authentifizieren.Führen Sie den folgenden Befehl aus und ersetzen Sie dabei ACCOUNT durch die E-Mail-Adresse Ihres Dienstkontos und den regionalen oder multiregionalen Standort des Repositorys LOCATION.
Linux
gcloud auth print-access-token \ --impersonate-service-account ACCOUNT | docker login \ -u oauth2accesstoken \ --password-stdin https://LOCATION-docker.pkg.dev
Windows
gcloud auth print-access-token --impersonate-service-account ACCOUNT | docker login -u oauth2accesstoken --password-stdin https://LOCATION-docker.pkg.dev
Aktivieren Sie in Ihrer gcloud-Sitzung ein Dienstkonto und fordern Sie dann ein Zugriffstoken an.
Aktivieren Sie das Dienstkonto, das Sie verwenden möchten. Ersetzen Sie ACCOUNT durch die E-Mail-Adresse Ihres Dienstkontos und KEY-FILE durch den Dateinamen für Ihren Dienstkontoschlüssel.
gcloud auth activate-service-account ACCOUNT \ --key-file=KEY-FILE
Generieren Sie ein Token und authentifizieren Sie es.
Führen Sie den folgenden Befehl aus und ersetzen Sie dabei LOCATION durch den regionalen oder multiregionalen Standort des Repositorys.
Linux
gcloud auth print-access-token | docker login -u oauth2accesstoken \ --password-stdin https://LOCATION-docker.pkg.dev
Windows
gcloud auth print-access-token | docker login -u oauth2accesstoken --password-stdin https://LOCATION-docker.pkg.dev
Docker ist jetzt bei Artifact Registry authentifiziert.
Dienstkontoschlüssel
Ein Dienstkontoschlüssel ist ein langlebiges Schlüsselpaar, das Sie als Anmeldedaten für ein Dienstkonto verwenden können. Im Gegensatz zum OAuth-Zugriffstoken läuft ein Dienstkontoschlüssel nicht ab. 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 spezifische Artifact Registry-Rolle 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:
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.
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.
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.
Verwenden Sie den Dienstkontoschlüssel, um die Integration in Docker zu konfigurieren:
Führen Sie dazu diesen Befehl aus:
Linux/MacOS
cat KEY-FILE | docker login -u KEY-TYPE --password-stdin \ https://LOCATION-docker.pkg.dev
Windows
Get-Content KEY-FILE | docker login -u KEY-TYPE --password-stdin https://LOCATION-docker.pkg.dev
Ersetzen Sie Folgendes:
- 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.
- KEY-TYPE ist einer der folgenden Werte:
Docker ist jetzt bei Artifact Registry authentifiziert.