Authentifizierung für Docker einrichten

Auf dieser Seite wird beschrieben, wie Sie Docker zur 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. Prüfen Sie jedoch, ob die erforderlichen Berechtigungen konfiguriert sind.

Hinweis

Artifact Registry API aktivieren und gcloud-Befehlszeile installieren. Eine Anleitung finden Sie unter Dienst aktivieren und deaktivieren.
Wenn das Ziel-Repository nicht vorhanden ist, erstellen Sie ein neues Repository.
Installieren und initialisieren Sie Google Cloud CLI.
Hinweis: Wenn Sie die gcloud CLI zuvor installiert haben, prüfen Sie, ob Sie die neueste Version haben, indem Sie gcloud components update ausführen.
(Optional) Konfigurieren Sie die Standardeinstellungen für gcloud-Befehle.
Prüfen Sie, ob das Konto, das Sie für die Authentifizierung verwenden, Berechtigungen für den Zugriff auf Artifact Registry hat. Wir empfehlen, statt eines Nutzerkontos ein Dienstkonto zu verwenden.
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.

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-Anmeldedaten-Assistent: Konfigurieren Sie Ihre Artifact Registry-Anmeldedaten für die Verwendung mit Docker direkt in gcloud. Das ist die einfachste Authentifizierungsmethode, kann aber langsamer sein als die eigenständige eigenständige Anmeldedaten.
Eigenständiger Docker Credential Helper: Diese Option dient hauptsächlich zur Konfiguration Ihrer Anmeldedaten für die Verwendung mit Docker ohne Google Cloud-Befehlszeile. Das ist deutlich schneller als das gcloud-Hilfsprogramm und verwendet Standardanmeldedaten für Anwendungen (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 gültig ist, ist es eine sicherere Option als ein Dienstkontoschlüssel.
Dienstkontoschlüssel: 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 unsicherste Option aller verfügbaren Authentifizierungsmethoden.

Verwenden Sie nach Möglichkeit ein Zugriffstoken oder ein Credential Assistent, um das Risiko unbefugter 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 den Docker-Anmeldedaten-Assistenten für die Authentifizierung verwenden, speichert Artifact Registry die Einstellungen für die Anmeldedaten-Hilfe 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 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 nach einem Credential Helper gesucht, der dem Host zugeordnet ist. Wenn Ihre config.json also Artifact Registry-Einstellungen im Bereich credHelpers und auths enthält, werden die Einstellungen im Bereich auths ignoriert.

gcloud Credential Helper

Das gcloud-Anmeldedaten-Assistent bietet sicheren, kurzlebigen Zugriff auf Ihre Projektressourcen. Dort wird Docker für die Authentifizierung bei Artifact Registry-Hosts in jeder Umgebung konfiguriert, in der die Google Cloud-Befehlszeile installiert ist. Cloud Shell enthält die Google Cloud-Befehlszeile und eine aktuelle Version von Docker.

Die gcloud-Anmeldedatenhilfe ist die einfachste Authentifizierungsmethode, die eingerichtet werden kann. Es konfiguriert Docker mit den Anmeldedaten des aktiven Nutzers oder Dienstkontos in Ihrer gcloud-Sitzung. Da diese Anmeldedaten-Hilfe von der gcloud-Befehlszeile abhängig ist, kann sie deutlich langsamer sein als die eigenständige Anmeldedaten. Verwenden Sie für automatisierte Builds mit Drittanbietertools oder Docker-Clients mit einer großen Anzahl von konfigurierten Registry-Hosts den eigenständigen Assistenten für Anmeldedaten.

So authentifizieren Sie sich bei Artifact Registry:

Melden Sie sich bei gcloud-Befehlszeile 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 der Name des Dienstkontos im Format USERNAME@PROJECT-ID.iam.gserviceaccount.com. Sie können vorhandene Dienstkonten auf der Seite Dienstkonten 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).
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 Hostnamen werden in die Konfiguration für die Anmeldedaten aufgenommen. 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
```
Durch den Befehl wird der Abschnitt credHelpers der aktuellen Docker-Konfiguration und die aktualisierte Konfiguration angezeigt, 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
Für Docker müssen sich Credential Helper im System-PATH befinden. Prüfen Sie, ob der Befehl gcloud im System PATH ist.

Eigenständiger Credential Helper

Die eigenständige Docker-Anmeldedatenkonfigurierung konfiguriert Docker für die Authentifizierung bei Artifact Registry auf einem System, auf dem die gcloud-Befehlszeile nicht verfügbar ist. Das ist deutlich schneller als das gcloud Credentials Helper und verwendet Application Standard Credentials (ADC), um Anmeldedaten in Ihrer Umgebung automatisch zu finden. Andere Vorgänge als das Übertragen und Abrufen von Bildern wie das Taggen oder Auflisten von Bildern Wir empfehlen, diese Authentifizierungsmethode für automatisierte Builds mit Drittanbietertools oder Docker-Clients mit einer großen Anzahl von konfigurierten Registrierungshosts zu verwenden.

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.5
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 und asia-northeast1 hinzuzufügen:
```
docker-credential-gcr configure-docker --registries=us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
```
Die angegebenen Hostnamen werden in die Konfiguration für die Anmeldedaten aufgenommen. 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.

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
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.
Führen Sie den folgenden Befehl aus, um zu prüfen, ob das Credential Assistent Ihre Anmeldedaten erfolgreich 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 ausgeführt wird, 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. Achte darauf, dass die Berechtigungen für das Übertragen und Abrufen von Images richtig konfiguriert sind.

Zugriffstoken

Sie können ein kurzlebiges OAuth-Zugriffstoken zur Authentifizierung bei Artifact Registry generieren. Da das Token 60 Minuten gültig ist, sollten Sie es weniger als eine Stunde anfordern, bevor Sie es mit einer Artifact Registry-Verbindung verbinden.

So verwenden Sie ein Zugriffstoken mit Anmeldedaten für das 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.

Zur Seite „Dienstkonten“
Gewähren Sie dem Dienstkonto die erforderliche Artifact Registry-Rolle, um Zugriff auf das Repository zu gewähren.
Generieren Sie ein Zugriffstoken für das Dienstkonto mit einer der folgenden Optionen:
- Wenn Sie Berechtigungen in der Rolle „Ersteller von Dienstkonto-Tokens“ (roles/iam.serviceAccountTokenCreator) haben, können Sie ein Dienstkonto imitieren, um ein Token dafür zu erhalten, und sich dann als das Dienstkonto authentifizieren.
  Linux
  Führen Sie den folgenden Befehl aus und ersetzen Sie ACCOUNT durch Ihre Dienstkonto-E-Mail-Adresse und den LOCATIONregionalen oder multiregionalen Standort des Repositorys.
```
gcloud auth print-access-token \
    --impersonate-service-account ACCOUNT | docker login \
    -u oauth2accesstoken \
    --password-stdin https://LOCATION-docker.pkg.dev
```
  Windows
  Führen Sie den folgenden Befehl aus und ersetzen Sie ACCOUNT durch Ihre Dienstkonto-E-Mail-Adresse und den LOCATIONregionalen oder multiregionalen Standort des Repositorys.
```
gcloud auth print-access-token
    --impersonate-service-account ACCOUNT

ya29.8QEQIfY_...

docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
https://LOCATION-docker.pkg.dev
```
- Aktivieren Sie ein Dienstkonto in der gcloud-Sitzung und rufen Sie dann ein Zugriffstoken ab.
  1. Aktivieren Sie das Dienstkonto, das Sie verwenden möchten. Ersetze ACCOUNT durch die E-Mail-Adresse deines Dienstkontos und KEY-FILE durch den Dateinamen für deinen Dienstkontoschlüssel.
```
gcloud auth activate-service-account ACCOUNT \
    --key-file=KEY-FILE
```
  2. Rufen Sie zur Authentifizierung bei Artifact Registry mit Docker ein Zugriffstoken ab.
  3. Generieren Sie ein Token und authentifizieren Sie sich im Repository.
    Linux
    Führen Sie den folgenden Befehl aus und ersetzen Sie dabei LOCATION durch den regionalen oder multiregionalen Speicherort des Repositorys.
    
    gcloud auth print-access-token | docker login -u oauth2accesstoken \ --password-stdin https://LOCATION-docker.pkg.dev
    Windows
    Führen Sie den folgenden Befehl aus und ersetzen Sie dabei LOCATION durch den regionalen oder multiregionalen Speicherort des Repositorys.
    
    gcloud auth print-access-token ya29.8QEQIfY_... docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \ 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 dem Dienstkonto die spezielle Artifact Registry-Rolle. 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.

Zur Seite „Dienstkonten“
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:
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:
  - _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:
  - _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, in dem das Image gespeichert ist.

Docker ist jetzt bei Artifact Registry authentifiziert.

Authentifizierung für Docker einrichten

Hinweis

Linux

Windows

Authentifizierungsmethode auswählen

Authentifizierungseinstellungen in der Docker-Konfigurationsdatei

gcloud Credential Helper

Eigenständiger Credential Helper

Zugriffstoken

Linux

Windows

Linux

Windows

Dienstkontoschlüssel

Linux

macOS

Windows

Linux/macOS

Windows