Änderungen für Docker

In diesem Dokument werden die Unterschiede zwischen Container Registry und Artifact Registry beim Authentifizieren, Hoch- und Herunterladen von Container-Images mit Docker beschrieben.

In diesem Leitfaden konzentrieren sich die Vergleiche auf standardmäßige Artifact Registry-Repositories und reguläre Artifact Registry-Repositories, die von Container Registry unabhängig sind und alle Artifact Registry-Features unterstützen.

Wenn Ihr Administrator Repositories mit Domainunterstützung für gcr.io eingerichtet hat, werden Anfragen an gcr.io-Hostnamen automatisch an ein entsprechendes Artifact Registry-Repository weitergeleitet. Zur Verwendung eines in Artifact Registry gehosteten gcr.io-Repositorys benötigen Sie eine entsprechende Artifact Registry-Rolle oder eine Rolle mit entsprechenden Berechtigungen.

Informationen zu den Unterschieden zwischen Container Registry und Artifact Registry beim Erstellen von Builds mit Cloud Build und beim Bereitstellen in Cloud Run oder Google Kubernetes Engine finden Sie unter Änderungen für Cloud Build, Cloud Run und GKE.

Verwenden Sie diese Informationen, um vorhandene Befehle, Konfigurationen oder Dokumentationen für Container Registry mit Docker anzupassen.

Hinweise

In diesem Dokument wird Folgendes vorausgesetzt:

  1. In Ihrem Projekt wurde Artifact Registry aktiviert.
  2. Sie haben Docker installiert. Docker ist in Cloud Shell enthalten.

Überblick

Auf übergeordneter Ebene ist der Workflow für die Verwendung von Docker mit Container Registry oder Artifact Registry derselbe.

Container Registry Artifact Registry
Administrator
  1. Container Registry API aktivieren
  2. Fügen Sie einen Registry-Host wie „gcr.io“ hinzu, indem Sie ein erstes Image auf den Host übertragen.
  3. Weisen Sie dem Registry-Host Cloud Storage-Rollen für den Storage-Bucket zu, um Zugriff auf Images zu gewähren.
 Administrator
  1. Artifact Registry API aktivieren
  2. Docker-Repository hinzufügen
  3. Gewähren Sie Artifact Registry-Rollen, um Zugriff auf Images zu gewähren.
Registry-Nutzer
  1. Definieren Sie das Bild als Dockerfile-Datei.
  2. Image erstellen
  3. Authentifizieren Sie sich bei der Registry.
  4. Taggen Sie das Image und laden Sie es in die Registry hoch.
  5. Rufen Sie das Image aus der Registry ab oder stellen Sie es in einer Google Cloud-Laufzeit bereit.
 Registry-Nutzer
  1. Definieren Sie das Bild als Dockerfile-Datei.
  2. Image erstellen
  3. Authentifizieren Sie sich bei der Registry.
  4. Taggen Sie das Image und laden Sie es in die Registry hoch.
  5. Rufen Sie das Image aus der Registry ab oder stellen Sie es in einer Google Cloud-Laufzeit bereit.

Eine Verknüpfung für Container Registry besteht jedoch darin, die Administrator- und Nutzerrollen in einem einzigen Workflow zu kombinieren. Diese Tastenkombination ist in folgenden Fällen üblich:

  • Kurzanleitungen und Anleitungen, in denen Sie Tests in einer Umgebung durchführen, in der Sie über umfassende Berechtigungen verfügen
  • Workflows, die Cloud Build verwenden, da das Cloud Build-Dienstkonto die Berechtigungen zum Hinzufügen eines Registry-Hosts im selben Google Cloud-Projekt hat.

Der Workflow für Verknüpfungen sieht so aus:

  1. Aktivieren Sie die Container Registry API.
  2. Gewähren Sie Berechtigungen für das Konto, mit dem auf Container Registry zugegriffen wird.

  3. Authentifizieren Sie sich bei der Registry. Die einfachste Authentifizierungsoption ist die Verwendung des Docker Credential Helpers in der Google Cloud CLI. Dies ist ein einmaliger Konfigurationsschritt.

    gcloud auth configure-docker

  4. Erstellen Sie das Image und taggen Sie es. Mit diesem Befehl wird beispielsweise das Image gcr.io/my-project/my-image:tag1 erstellt und getaggt:

    docker build -t gcr.io/my-project/my-image:tag1

  5. Laden Sie das Image in die Registry hoch. Beispiel:

    docker push gcr.io/my-project/my-image:tag1

    Wenn der Registry-Host gcr.io im Projekt nicht vorhanden ist, fügt Container Registry den Host hinzu, bevor das Image hochgeladen wird.

  6. Rufen Sie das Image aus der Registry ab oder stellen Sie es in einer Google Cloud-Laufzeit bereit. Beispiel:

    docker pull gcr.io/my-project/my-image:tag1

Für diesen Workflow stehen die folgenden Tastenkombinationen zur Verfügung:

  • Das Konto, über das Images übertragen werden, hat die Rolle „Storage-Administrator“ oder eine Rolle mit denselben Berechtigungen, z. B. „Inhaber“. Die umfassenden Berechtigungen dieser Rolle ermöglichen Lese- und Schreibzugriff auf alle Storage-Buckets in einem Projekt, einschließlich Buckets, die nicht von Container Registry verwendet werden.
  • Wenn Sie einige Google Cloud APIs aktivieren, wird die Container Registry API automatisch aktiviert. Das bedeutet, dass Nutzer dieser Dienste impliziten Zugriff auf Container Registry im selben Projekt haben. Nutzer, die Builds in Cloud Build ausführen können, können beispielsweise Images in Registrys übertragen und standardmäßig Registry-Hosts hinzufügen.

In Artifact Registry sind Administrator- und Repository-Nutzerrollen klar voneinander getrennt, wodurch die Schritte im Build- und Deployment-Workflow geändert werden. Nehmen Sie die folgenden Änderungen vor, um den Container Registry-Workflow für Artifact Registry anzupassen. Jeder Schritt enthält einen Link zu weiteren Informationen zum Ändern des Workflows.

  1. Neu: Artifact Registry API aktivieren.

    Sie müssen die Artifact Registry API aktivieren. In Cloud Build- und Laufzeitumgebungen wie Cloud Run und GKE wird die API nicht automatisch für Sie aktiviert.

  2. Neu: Erstellen Sie das Ziel-Docker-Repository, falls es noch nicht vorhanden ist. Sie müssen ein Repository erstellen, bevor Sie Images dorthin hochladen können. Das Erstellen eines Repositorys kann durch das Hochladen eines Images nicht ausgelöst werden und das Cloud Build-Dienstkonto ist nicht berechtigt, Repositories zu erstellen.

  3. Gewähren Sie Berechtigungen für das Konto, das mit Artifact Registry interagiert.

  4. Geändert: Authentifizieren Sie sich beim Repository. Wenn Sie Credential Helper in der gcloud CLI verwenden, müssen Sie die Hosts angeben, die Sie der Docker-Clientkonfiguration hinzufügen möchten. Mit diesem Befehl wird beispielsweise der Host us-central1-docker.pkg.dev hinzugefügt:

    gcloud auth configure-docker us-central1-docker.pkg.dev

  5. Geändert: Erstellen und taggen Sie das Image.

    Der folgende Beispielbefehl ist mit dem Container Registry-Beispiel identisch, verwendet jedoch einen Artifact Registry-Repository-Pfad für das Image.

    docker build -t us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

  6. Geändert: Übertragen Sie das Image über den Artifact Registry-Pfad in das Repository. Beispiel:

    docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

  7. Geändert: Das Image wird über den Artifact Registry-Pfad aus dem Repository abgerufen. Beispiel:

    docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

API aktivieren

Wichtige Fakten:

Im folgenden Vergleich wird das Aktivieren der API für jeden Dienst beschrieben:

Container Registry

Sie müssen die Container Registry API aktivieren, bevor Sie Docker oder Clients von Drittanbietern mit Container Registry verwenden können.

Wenn Sie die folgenden Google Cloud APIs aktivieren, wird automatisch auch die Container Registry API aktiviert:

  • Flexible App Engine-Umgebung
  • Cloud Build
  • Cloud Functions
  • Cloud Run
  • Container-Scan oder On-Demand-Scanning in der Artefaktanalyse
  • Google Kubernetes Engine

Mit den Standardberechtigungen haben Nutzer, die Builds in Cloud Build ausführen, Container mit Artefaktanalyse scannen oder Container in Google Cloud-Laufzeiten bereitstellen können, implizit Zugriff auf Images in Container Registry, wenn sich die Registry im selben Projekt befindet.

Artifact Registry

Sie müssen die Artifact Registry API aktivieren, bevor Sie Docker-Clients oder andere Google Cloud-Dienste mit Artifact Registry verwenden können.

Durch Dienste wie Cloud Build, Cloud Run und GKE wird die Artifact Registry API nicht automatisch aktiviert.

Mit gcloud können Sie mehrere APIs im selben Projekt aktivieren. Führen Sie beispielsweise den folgenden Befehl aus, um die Cloud Build API und die Artifact Registry API zu aktivieren:

gcloud services enable
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com

Registries und Repositories hinzufügen

Wichtige Fakten:

  • Sie müssen ein Artifact Registry-Docker-Repository erstellen, bevor Sie ein Image dorthin hochladen.

    In der Dokumentation, in der das Hochladen von Images in die Container Registry beschrieben wird, wird ein Schritt zum Erstellen einer Registry häufig ausgeschlossen, da ein Konto mit Storage-Administratorberechtigungen eine Registry einem Projekt mit der ersten Übertragung auf den Registry-Host hinzufügen kann.

  • Container Registry speichert alle Images an einem einzigen multiregionalen Standort im selben Storage-Bucket. In Artifact Registry können Sie mehrere Repositories in derselben oder mehreren Regionen mit separaten Zugriffsrichtlinien erstellen.

Im folgenden Vergleich wird die Repository-Einrichtung in den einzelnen Diensten beschrieben:

Container Registry

In Container Registry können Sie Ihrem Projekt bis zu vier Registry-Hosts hinzufügen. Sie fügen einen Registry-Host hinzu, indem Sie das erste Image hochladen.

  1. Um Ihrem Projekt eine Registry wie gcr.io hinzuzufügen, sendet ein Konto mit der Rolle „Storage-Administrator“ auf Projektebene ein erstes Image per Push.

    Wenn beispielsweise der Host gcr.io im Projekt my-project nicht vorhanden ist, werden durch Übertragen des Images gcr.io/my-project/my-image:1.0 die folgenden Schritte ausgelöst:

    1. Fügen Sie dem Projekt den Host gcr.io hinzu
    2. Erstellen Sie im Projekt einen Storage-Bucket für gcr.io.
    3. Bild als gcr.io/my-project/my-image:1.0 speichern

  2. Nach dieser ersten Übertragung können Sie dem Storage-Bucket Berechtigungen erteilen.

Innerhalb eines Projekts speichert ein Registry-Host alle Images im selben Storage-Bucket. Im folgenden Beispiel hat das Projekt my-project zwei Images namens web-app in der Registry gcr.io. Eine befindet sich direkt unter der Projekt-ID my-project. Das andere Image befindet sich im Repository team1.

gcr.io/my-project/web-app
gcr.io/my-project/team1/web-app

Artifact Registry

Ein Konto mit der Rolle eines Artifact Registry Repository-Administrators muss das Repository erstellen, bevor Sie Images dorthin übertragen. Anschließend können Sie dem Repository für andere Nutzer Berechtigungen erteilen.

In Artifact Registry ist jedes Repository eine separate Ressource. Daher müssen alle Image-Pfade ein Repository enthalten.

Gültige Bildpfade:

us-central1-docker.pkg.dev/my-project/team1/web-app:1.0
us-central1-docker.pkg.dev/my-project/team2/web-app:1.0

Ungültiger Image-Pfad (enthält kein Repository) :

us-central1-docker.pkg.dev/my-project/web-app:1.0

Die folgenden Beispiele zeigen Situationen, in denen das Hochladen eines Images in ein fehlendes Repository fehlschlägt.

  • Image per Push an us-central1-docker.pkg.dev/my-project/team1 übertragen, wenn us-central1-docker.pkg.dev/my-project/team1 nicht vorhanden ist.
  • Image per Push an us-central1-docker.pkg.dev/my-project/team2 übertragen, wenn us-central1-docker.pkg.dev/my-project/team1 vorhanden ist, us-central1-docker.pkg.dev/my-project/team2 aber nicht vorhanden ist.

Berechtigungen gewähren

Wichtige Fakten:

  • Weisen Sie dem Konto, das Sie mit Artifact Registry verwenden, die entsprechende Artifact Registry-Rolle zu.
  • Google Cloud-Dienste haben einen gleichwertigen Lese- oder Schreibzugriff auf Container Registry und Artifact Registry. Mit dem Cloud Build-Standarddienstkonto können jedoch keine Repositories erstellt werden.
  • Container Registry unterstützt die Zugriffssteuerung auf Storage-Bucket-Ebene. Artifact Registry unterstützt die Zugriffssteuerung auf Repository-Ebene.

Im folgenden Vergleich werden die in den einzelnen Diensten eingerichteten Berechtigungen beschrieben:

Container Registry

Container Registry verwendet die Cloud Storage-Rollen, um den Zugriff zu steuern.

Storage-Objekt-Betrachter auf Storage-Bucket-Ebene
Images aus vorhandenen Registry-Hosts im Projekt abrufen (lesen)
Autor alter Storage-Buckets auf Storage-Bucket-Ebene
Images für vorhandene Registry-Hosts im Projekt per Push (Schreiben) und Pull (Lesen) abrufen.
Storage-Administrator auf Projektebene
Sie können einem Projekt einen Registry-Host hinzufügen, indem Sie ein erstes Image auf den Host übertragen.

Nachdem das erste Image per Push in eine Registry übertragen wurde, gewähren Sie anderen Konten, die Zugriff auf den Storage-Bucket benötigen, Cloud Storage-Rollen. Beachten Sie, dass jedes Konto mit allen Berechtigungen in der Rolle „Storage-Administrator“ Speicher-Buckets und Speicherobjekte im gesamten Projekt lesen, schreiben und löschen kann.

Berechtigungen für einen Storage-Bucket gelten für alle Repositories in der Registry. Beispielsweise kann jeder Nutzer mit der Berechtigung „Storage-Objekt-Betrachter“ für den Bucket für gcr.io/my-project Images in allen folgenden Repositories lesen:

gcr.io/my-project/team1
gcr.io/my-project/team2
gcr.io/my-project/test
gcr.io/my-project/production

Artifact Registry

Artifact Registry hat eigene Rollen, um den Zugriff zu steuern. Diese Rollen ermöglichen eine klare Trennung zwischen Administrator- und Repository-Nutzerrollen.

Nur Konten, mit denen Repositories verwaltet werden, sollten die Rolle „Artifact Registry-Repository-Administrator“ oder „Artifact Registry-Administrator“ haben.

Artifact Registry-Leser
Artefakte und Repositories auflisten. Artefakte herunterladen.
Artifact Registry-Autor
Artefakte und Repositories auflisten. Artefakte herunterladen, neue Artefaktversionen hochladen und Tags hinzufügen oder aktualisieren.
Repository-Administrator für Artifact Registry
Artifact Registry-Schreibberechtigungen und -Berechtigungen zum Löschen von Artefakten und Tags.
Artifact Registry-Administrator
Berechtigungen von Artifact Registry-Repository-Administratoren zum Erstellen, Aktualisieren, Löschen und Gewähren von Berechtigungen für Repositories.

Sie können diese Berechtigungen auf Repository-Ebene anwenden. Beispiel:

  • Team 1 Zugriff für us-central1-docker.pkg.dev/my-project/team1 gewähren
  • Team 2 Zugriff für us-central1-docker.pkg.dev/my-project/team2 gewähren.

Weitere Informationen zum Gewähren von Artifact Registry-Berechtigungen finden Sie in der Dokumentation zur Zugriffssteuerung.

Authentifizierung bei der Registry

Wichtige Fakten:

  • Artifact Registry unterstützt dieselben Authentifizierungsmethoden wie Container Registry.
  • Für Docker Credential Helper müssen Sie Hosts angeben, die der Docker-Clientkonfiguration hinzugefügt werden sollen.
  • Verwenden Sie für die Authentifizierung mit docker login den Artifact Registry-Host anstelle eines Container Registry-Hosts.

Credential Helper verwenden

Mit dem Befehl gcloud auth configure-docker und dem eigenständigen Credential Helper wird Docker standardmäßig nur für *.gcr.io-Hostnamen konfiguriert. Für Artifact Registry müssen Sie eine Liste der Artifact Registry-Hosts angeben, die Sie der Docker-Clientkonfiguration hinzufügen möchten.

Führen Sie beispielsweise den folgenden Befehl aus, um die Authentifizierung bei Docker-Repositories in der Region us-central1 einzurichten:

gcloud auth configure-docker us-central1-docker.pkg.dev

Wenn Sie später Repositories in us-east1 und asia-east1 hinzufügen, müssen Sie den Befehl noch einmal ausführen, um der Docker-Konfiguration die entsprechenden regionalen Hostnamen hinzuzufügen.

gcloud auth configure-docker us-east-docker.pkg.dev,asia-east1-docker.pkg.dev

Weitere Informationen zu den Artifact Registry-Authentifizierungsmethoden finden Sie unter Authentifizierung für Docker einrichten.

Passwortauthentifizierung verwenden

Verwenden Sie bei der Anmeldung bei Docker den Artifact Registry-Hostnamen anstelle des Hostnamens *.gcr.io. Das folgende Beispiel zeigt die Authentifizierung mit einem base64-codierten Dienstkontoschlüssel beim Host us-central1-docker.pkg.dev:

cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-central1-docker.pkg.dev

Images erstellen und taggen

Wichtige Punkte: – Artifact Registry verwendet einen anderen Hostnamen für Repositories.

Verwenden Sie beim Taggen eines Images den Artifact Registry-Pfad anstelle des Container Registry-Pfads. Beispiel:

docker tag my-image us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Images auf die Registry hochladen

Wichtige Punkte: – In Artifact Registry muss das Ziel-Repository vorhanden sein, bevor Sie ein Image dorthin hochladen. – Artifact Registry verwendet einen anderen Hostnamen für Repositories.

Wenn Sie ein Image hochladen, verwenden Sie den Artifact Registry-Pfad anstelle des Container Registry-Pfads. Beispiel:

docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Images aus der Registry herunterladen

Wichtig:

  • Die Artifact Registry-Hostnamen unterscheiden sich von den Container Registry-Hostnamen.

Wenn Sie ein Image abrufen, verwenden Sie den Artifact Registry-Pfad anstelle des Container Registry-Pfads. Beispiel:

docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Beispiele für das Bereitstellen von Images in Google Cloud-Laufzeiten wie Cloud Run und GKE finden Sie unter Images bereitstellen.