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.
Hinweise
- Prüfen Sie, ob Sie die Container Registry API aktiviert und die gcloud CLI installiert haben. Anleitungen finden Sie unter Dienst aktivieren und deaktivieren.
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.
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.
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 keine Google Cloud CLI 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 unsicherste 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. 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 Dienstkont oschlü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.
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
Die Datei enthält separate Abschnitte für verschiedene Authentifizierungsmethoden:
credHelpers
- Wenn Sie Docker Credential Helper für die Authentifizierung verwenden, speichert Container Registry die Einstellungen für die Credential Helper im Abschnitt
credHelpers
der Datei. auths
- Wenn Sie sich mit Docker mit einem Token oder Dienstkontoschlüssel als Passwort anmelden, speichert Docker Ihre Anmeldedaten im Abschnitt
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 Container Registry-Einstellungen in den Abschnitten 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 sicheren, kurzlebigen Zugriff auf Ihre Projektressourcen.
Verwenden Sie die gcloud CLI, um die Authentifizierung in Cloud Shell oder in einer Umgebung zu konfigurieren, in der die Google Cloud CLI installiert ist. Cloud Shell enthält eine aktuelle Version von Docker.
So konfigurieren Sie die Authentifizierung:
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
- ACCOUNT ist der Name des Dienstkontos im Format
[USERNAME]@[PROJECT-ID].iam.gserviceaccount.com
. Sie können vorhandene Dienstkonten auf der Seite Dienstkonten der Google Cloud Console oder mit dem Befehlgcloud 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).
- ACCOUNT ist der Name des Dienstkontos im Format
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
- Linux:
Eigenständiger Credential Helper
Der eigenständige Docker Credential Helper konfiguriert Docker für die Authentifizierung bei Container Registry auf einem System, auf dem die gcloud CLI 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:
Melden Sie sich auf dem Computer als der Nutzer an, der Docker-Befehle ausführt.
Laden Sie
docker-credential-gcr
aus GitHub unter "Releases" herunter:Sie können optional das
curl
-Befehlszeilentool verwenden. Beispiel:VERSION=2.1.23 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 docker-credential-gcr \ && chmod +x docker-credential-gcr && sudo mv docker-credential-gcr /usr/bin/
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
- Linux:
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
Sie können ein kurzlebiges OAuth-Zugriffstoken generieren, um sich bei Container Registry zu authentifizieren. 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.
Erstellen Sie ein neues Dienstkonto, das mit Container Registry interagiert.
Console
Wechseln Sie in der Google Cloud Console zur Seite Dienstkonto erstellen.
Wählen Sie das Projekt aus, das Sie verwenden möchten.
Geben Sie im Feld Dienstkontoname einen Namen ein.
Optional: Geben Sie im Feld Dienstkontobeschreibung eine Beschreibung ein.
Klicken Sie auf Erstellen.
Klicken Sie auf das Feld Rolle auswählen. Wählen Sie unter Alle Rollen basierend auf den Berechtigungen, die Sie dem Dienstkonto zuweisen möchten, eine geeignete Cloud Storage-Rolle aus.
Klicken Sie auf Fertig.
gcloud
Sie können die folgenden Befehle mit der Google Cloud CLI auf Ihrem lokalen Computer oder in Cloud Shell ausführen.
Erstellen Sie das Dienstkonto. Ersetzen Sie NAME durch einen Namen für das Dienstkonto.
gcloud iam service-accounts create NAME
Weisen Sie dem Dienstkonto die Rolle zu. Ersetzen Sie PROJECT_ID durch Ihre 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 auch verschiedene Rollen zuweisen.
gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
Rufen Sie einen Schlüssel für das Dienstkonto ab, das mit Container Registry interagiert.
Console
Rufen Sie in der Google Cloud Console die Seite Dienstkonten auf.
Klicken Sie auf die E-Mail-Adresse des Dienstkontos, das Sie nutzen möchten.
Klicken Sie auf Schlüssel.
Klicken Sie auf Schlüssel hinzufügen > Neuen Schlüssel erstellen.
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.Klicken Sie auf Schließen.
gcloud
Sie können den folgenden Befehl mit der Google Cloud CLI auf Ihrem lokalen Computer 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
Führen Sie den folgenden Befehl aus, um sich in der Google Cloud CLI 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.
- ACCOUNT ist der Name des Dienstkontos im Format
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.
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.
Führen Sie dazu diesen Befehl aus:
Linux
gcloud auth print-access-token | docker login -u oauth2accesstoken \ --password-stdin https://HOSTNAME
Windows
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
oderasia.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. Im Gegensatz zum OAuth-Zugriffstoken läuft ein Dienstkontoschlüssel nicht ab.
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:
- Erstellen Sie dedizierte Dienstkonten, die nur für die Interaktion mit Container Registry verwendet werden.
- Gewähren Sie die Rolle mit dem geringstmöglichen Zugriff, den das Dienstkonto benötigt.
- 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 Container Registry-Repositories:
Erstellen Sie ein neues Dienstkonto, das mit Container Registry interagiert.
Console
Wechseln Sie in der Google Cloud Console zur Seite Dienstkonto erstellen.
Wählen Sie das Projekt aus, das Sie verwenden möchten.
Geben Sie im Feld Dienstkontoname einen Namen ein.
Optional: Geben Sie im Feld Dienstkontobeschreibung eine Beschreibung ein.
Klicken Sie auf Erstellen.
Klicken Sie auf das Feld Rolle auswählen. Wählen Sie unter Alle Rollen eine geeignete Cloud Storage-Rolle für das Dienstkonto aus.
Klicken Sie auf Fertig.
gcloud
Sie können die folgenden Befehle mit der Google Cloud CLI auf Ihrem lokalen Computer oder in Cloud Shell ausführen.
Erstellen Sie das Dienstkonto. Ersetzen Sie NAME durch einen Namen für das Dienstkonto.
gcloud iam service-accounts create NAME
Weisen Sie dem Dienstkonto die Rolle zu. Ersetzen Sie PROJECT_ID durch Ihre 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"
Rufen Sie einen Schlüssel für das Dienstkonto ab, das mit Container Registry interagiert.
Console
Rufen Sie in der Google Cloud Console die Seite Dienstkonten auf.
Klicken Sie auf die E-Mail-Adresse des Dienstkontos, das Sie nutzen möchten.
Klicken Sie auf Schlüssel.
Klicken Sie auf Schlüssel hinzufügen > Neuen Schlüssel erstellen.
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.Klicken Sie auf Schließen.
gcloud
Sie können den folgenden Befehl mit der Google Cloud CLI auf Ihrem lokalen Computer 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
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 als Passwort für die Authentifizierung bei Docker.
Linux/macOS
cat KEY-FILE | docker login -u _json_key --password-stdin \ https://HOSTNAME
Windows
Get-Content KEY-FILE | docker login -u _json_key --password-stdin https://HOSTNAME
Ersetzen Sie Folgendes:
- KEY-FILE ist der Name der Dienstkonto-Schlüsseldatei im JSON-Format.
- HOSTNAME ist
gcr.io
,us.gcr.io
,eu.gcr.io
oderasia.gcr.io
.
Docker ist jetzt bei Container Registry authentifiziert.