Diese Seite wurde von der Cloud Translation API übersetzt.

Authentifizierung bei Artifact Registry für Docker konfigurieren

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

Sie müssen die Authentifizierung für Cloud Build oder Google Cloud-Laufzeitumgebungen wie Google Kubernetes Engine und Cloud Runnicht konfigurieren. Sie sollten jedoch prüfen, ob die erforderlichen Berechtigungen konfiguriert sind.

Hinweise

Install the Google Cloud CLI, then initialize it by running the following command:
```
gcloud init
```
(Optional) Konfigurieren Sie Standardeinstellungen für gcloud CLI-Befehle.
Achten Sie darauf, dass das Konto, das Sie für die Authentifizierung verwenden, Berechtigungen zum 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 unter macOS nicht 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 Ihr Nutzername ist.
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-Daemons.

Authentifizierungsmethode auswählen

Die folgenden Authentifizierungsmethoden sind verfügbar:

gcloud Credential Helper: Konfigurieren Sie Ihre Artifact Registry-Anmeldedaten für die Verwendung mit direkt in der gcloud CLI. Dies ist die einfachste Authentifizierungsmethode, kann aber langsamer sein als der eigenständige Anmeldedaten-Helper.
Eigenständiger Docker Credential Helper: Diese Option dient hauptsächlich zur Konfiguration Ihrer Anmeldedaten zur Verwendung mit Docker, wenn keine Google Cloud CLI vorhanden ist. Er ist deutlich schneller als die gcloud CLI. Credential Helper und nutzt Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) Anmeldedaten in Ihrer Umgebung.
Zugriffstoken: Sie können ein kurzlebiges Zugriffstoken für ein Dienstkonto generieren und Verwenden Sie das Token zur Passwortauthentifizierung. Da das Token nur für 60 Tage gültig ist, ist er sicherer 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 einen Anmeldedaten-Helper, um das Risiko eines unberechtigten Zugriffs auf Ihre Container-Images zu verringern. 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 Artifact Registry speichert die Credential Helper-Einstellungen im credHelpers.
auths: Wenn Sie sich mit Docker mit einem Token oder Dienstkontoschlüssel als Passwort anmelden, speichert Docker eine base64-codierte Version Ihrer Anmeldedaten im Abschnitt auths der Datei.
credStore: Wenn Sie Anmeldedatenspeicher zum Verwalten Ihrer Anmeldedaten befinden sich die Einstellungen für den Anmeldedatenspeicher in 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 Folgendes enthält: Artifact Registry-Einstellungen in den Abschnitten credHelpers und auths Die Einstellungen im Bereich auths werden ignoriert.

Credential Helper für die gcloud CLI

Der gcloud CLI Credential Helper bietet sicheren, kurzlebigen Zugriff auf Ihre Projektressourcen. Es konfiguriert Docker für die Authentifizierung bei Artifact Registry wird in jeder Umgebung gehostet, in der die Google Cloud CLI installiert ist. Cloud Shell enthält die Google Cloud CLI und eine aktuelle Version von Docker.

Der gcloud CLI Credential Helper ist die einfachste Authentifizierungsmethode, die Sie einrichten können. Docker wird mit den Anmeldedaten des aktiven Nutzers oder Dienstkontos in Ihrer gcloud CLI-Sitzung konfiguriert. Da dieser Credential Helper von der gcloud CLI abhängt, kann er deutlich langsamer sein als der eigenständige Credential Helper. Verwenden Sie für automatisierte Builds mit Drittanbietertools oder Docker-Clients mit einer großen Anzahl konfigurierter Registry-Hosts stattdessen den eigenständigen Anmeldedaten-Helper.

So authentifizieren Sie sich bei Artifact Registry:

Melden Sie sich in 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
```
  Dabei gilt:
  - ACCOUNT ist das Dienstkonto, mit dem Sie verwenden möchten. Artifact Registry im Format USERNAME@PROJECT-ID.iam.gserviceaccount.com. Wenn Sie ein vorhandenes Konto verwenden möchten, können Sie sich eine Liste der Dienstkonten auf der Seite Dienstkonten in der Google Cloud Console oder mit dem Befehl gcloud iam service-accounts list ansehen.
  - 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).
  Hinweis: Dienstkontoschlüssel stellen ein Sicherheitsrisiko dar, wenn sie nicht ordnungsgemäß verwaltet werden. Sie sollten nach Möglichkeit eine sicherere Alternative zu Dienstkontoschlüsseln auswählen. Wenn Sie sich mit einem Dienstkontoschlüssel authentifizieren müssen, sind Sie für die Sicherheit des privaten Schlüssels und für andere Vorgänge verantwortlich, die unter Best Practices für die Verwaltung von Dienstkontoschlüsseln beschrieben werden. Wenn Sie keinen Dienstkontoschlüssel erstellen können, ist das Erstellen von Dienstkontoschlüsseln für Ihre Organisation möglicherweise deaktiviert. Weitere Informationen finden Sie unter Standardmäßig sichere Organisationsressourcen verwalten.
Führen Sie dazu diesen Befehl aus:
```
gcloud auth configure-docker HOSTNAME-LIST
```
Dabei ist HOSTNAME-LIST eine durch Kommas getrennte Liste von Repositorys Hostnamen, die der Credential Helper-Konfiguration hinzugefügt werden sollen.

Führen Sie beispielsweise den folgenden Befehl aus, um die Regionen us-west1 und asia-northeast1 hinzuzufügen:
```
gcloud auth configure-docker us-west1-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 erneut.

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 nach dem Hinzufügen der angegebenen Hostnamen an.

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

Der eigenständige Docker Credential Helper konfiguriert Docker für die Authentifizierung. in Artifact Registry auf einem System übertragen werden, auf dem die gcloud CLI nicht verfügbar ist. Er ist deutlich schneller als der Anmeldedaten-Helfer der gcloud CLI und verwendet Standardanmeldedaten für Anwendungen (ADC), um Anmeldedaten in Ihrer Umgebung automatisch zu finden. Für andere Vorgänge als Push- und Images abrufen, z. B. das Taggen oder Auflisten von Images. Wir empfehlen dies Authentifizierungsmethode für automatisierte Builds mit Drittanbietertools oder Docker Clients mit einer großen Anzahl konfigurierter 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.25
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 Repositorys Hostnamen, die der Credential Helper-Konfiguration hinzugefügt werden sollen.

Führen Sie beispielsweise den folgenden Befehl aus, um die Regionen us-west1 und asia-northeast1 hinzuzufügen:
```
docker-credential-gcr configure-docker --registries=us-west1-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 eigenständige Docker Credential Helper-Dokumentation 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.
So überprüfen Sie, ob Credential Helper Ihre Anmeldedaten verwenden, führen Sie den folgenden Befehl aus:
```
echo "https://HOSTNAME" | docker-credential-gcr get
```
Ersetzen Sie HOSTNAME durch einen Hostnamen, den Sie dem Konfiguration. Beispiel:
```
echo "https://us-west1-docker.pkg.dev" | docker-credential-gcr get
```
Wenn der Befehl erfolgreich ist, enthält die zurückgegebene JSON-Ausgabe ein Token in Das Feld Secret. Beispiel:
```
{"ServerURL":"https://us-west1-docker.pkg.dev","Username":"_dcgcr_2_0_0_token","Secret":"ya29..."}
```

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

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 sie weniger als eine Stunde vor der Herstellung einer Verbindung Artifact Registry.

So verwenden Sie ein Zugriffstoken mit Dienstkonto-Anmeldedaten:

Erstellen Sie ein Dienstkonto, das im Namen Ihrer Anwendung agieren soll, oder wählen Sie ein vorhandenes Dienstkonto für die Automatisierung aus.
Weisen Sie dem Dienstkonto die Rolle Artifact Registry zu, um den Zugriff auf das Repository zu ermöglichen.
Generieren Sie ein Zugriffstoken für das Dienstkonto und authentifizieren Sie es:
- Sie benötigen die Berechtigungen der Rolle „Ersteller von Dienstkonto-Tokens“ (roles/iam.serviceAccountTokenCreator), um die Identität eines Dienstkontos zu übernehmen, ein Token dafür zu erhalten und sich dann als das Dienstkonto zu authentifizieren.
  
  Führen Sie den folgenden Befehl aus und ersetzen Sie dabei ACCOUNT durch Ihren E-Mail-Adresse des Dienstkontos und LOCATION regional oder multiregional Standort von des Repositorys.
  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

Docker ist jetzt bei Artifact Registry authentifiziert.

Dienstkontoschlüssel

Hinweis :Verwenden Sie nach Möglichkeit ein Zugriffstoken oder Credential Helper, um um das Risiko unbefugter Zugriffe auf Ihre Artefakte zu verringern. Dienstkontoschlüssel stellen ein Sicherheitsrisiko dar, wenn sie nicht ordnungsgemäß verwaltet werden. Sie sollten Eine sicherere Alternative zu Dienstkontoschlüsseln auswählen wenn möglich. Wenn Sie sich mit einem Dienstkontoschlüssel authentifizieren müssen, sind Sie für die Sicherheit des privaten Schlüssels und für andere Vorgänge verantwortlich, die unter Best Practices für die Verwaltung von Dienstkontoschlüsseln beschrieben werden. Wenn Sie keinen Dienstkontoschlüssel erstellen können, ist das Erstellen von Dienstkontoschlüsseln für Ihre Organisation möglicherweise deaktiviert. Weitere Informationen finden Sie unter Standardmäßig sichere Organisationsressourcen verwalten

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.
Die spezifische URL erteilen Artifact Registry-Rolle für den Zugriff, der für das Dienstkonto erforderlich ist. 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“

Hinweis: Dienstkontoschlüssel stellen ein Sicherheitsrisiko dar, wenn sie nicht ordnungsgemäß verwaltet werden. Sie sollten nach Möglichkeit eine sicherere Alternative zu Dienstkontoschlüsseln auswählen. Wenn Sie sich mit einem Dienstkontoschlüssel authentifizieren müssen, sind Sie für die Sicherheit des privaten Schlüssels und für andere Vorgänge verantwortlich, die unter Best Practices für die Verwaltung von Dienstkontoschlüsseln beschrieben werden. Wenn Sie keinen Dienstkontoschlüssel erstellen können, ist das Erstellen von Dienstkontoschlüsseln für Ihre Organisation möglicherweise deaktiviert. Weitere Informationen finden Sie unter Standardmäßig sichere Organisationsressourcen verwalten.
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üsseldateiname 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/die/das regional oder multiregional Speicherort des Repositorys, in dem das Image gespeichert wird.

Docker ist jetzt bei Artifact Registry authentifiziert.

Authentifizierung bei Artifact Registry für Docker konfigurieren

Hinweise

Linux

Windows

Authentifizierungsmethode auswählen

Authentifizierungseinstellungen in der Docker-Konfigurationsdatei

Credential Helper für die gcloud CLI

Eigenständiger Credential Helper

Zugriffstoken

Linux

Windows

Dienstkontoschlüssel

Linux

macOS

Windows

Linux/macOS

Windows