Änderungen für Docker

In diesem Dokument werden die Unterschiede zwischen Container Registry und Artifact Registry bei der Authentifizierung, Übertragung und Abruf von Container-Images mit Docker erläutert.

In diesem Leitfaden konzentrieren sich die Vergleiche auf pkg.dev Artifact Registry-Repositories, reguläre Artifact Registry-Repositories, die unabhängig von Container Registry sind und alle Artifact Registry-Funktionen unterstützen.

Wenn Ihr Administrator Repositories mit Unterstützung von gcr.io-Domains eingerichtet hat, werden Anfragen an gcr.io-Hostnamen automatisch an ein entsprechendes Artifact Registry-Repository weitergeleitet. Wenn Sie ein in Artifact Registry gehostetes gcr.io-Repository verwenden möchten, 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 mit Cloud Build und Bereitstellen in Cloud Run oder der Google Kubernetes Engine finden Sie unter Änderungen für Cloud Build, Cloud Run und GKE.

Anhand dieser Informationen können Sie vorhandene Befehle, Konfigurationen oder Dokumentationen, die sich auf Container Registry mit Docker beziehen, anpassen.

Hinweis

In diesem Dokument wird davon ausgegangen, dass Sie Folgendes haben:

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

Übersicht

Im Großen und Ganzen 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 anfängliches 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. Fügen Sie ein Docker-Repository hinzu.
  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 übertragen Sie es per Push in die Registry.
  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 übertragen Sie es per Push in die Registry.
  5. Rufen Sie das Image aus der Registry ab oder stellen Sie es in einer Google Cloud Laufzeit bereit.

Für Container Registry besteht jedoch die Möglichkeit, Administrator- und Nutzerrollen in einem einzigen Workflow zu kombinieren. Diese Tastenkombination ist in folgenden Fällen üblich:

  • In Kurzanleitungen und Anleitungen, in denen Sie in einer Umgebung mit umfassenden Berechtigungen testen
  • Workflows, die Cloud Build verwenden, da das Cloud Build-Dienstkonto Berechtigungen zum Hinzufügen eines Registry-Hosts im selben Projekt hat Google Cloud

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

  1. Aktivieren Sie die Container Registry API.
  2. Gewähren Sie dem Konto, das auf Container Registry zugreifen soll, Berechtigungen.

  3. Authentifizieren Sie sich bei der Registry. Die einfachste Authentifizierungsoption ist die Verwendung des Docker Credential Helper in der Google Cloud CLI. Dieser Schritt muss nur einmal durchgeführt werden.

    gcloud auth configure-docker

  4. Erstellen und taggen Sie das Bild. 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 nicht im Projekt vorhanden ist, wird er von Container Registry hinzugefügt, 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 sind die folgenden Tastenkürzel erforderlich:

  • Das Konto, über das Bilder gepusht 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 für 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 standardmäßig Images in Repositories pushen und Registry-Hosts hinzufügen.

In Artifact Registry gibt es eine klare Trennung zwischen Administrator- und Repository-Nutzerrollen, die die Schritte im Build- und Bereitstellungsworkflow ändert. Nehmen Sie die folgenden Änderungen vor, um den Container Registry-Workflow für Artifact Registry anzupassen. Zu jedem Schritt gibt es einen Link zu weiteren Informationen zum Ändern des Workflows.

  1. Neu: Aktivieren Sie die Artifact Registry API.

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

  2. Neu: Erstellen Sie das Ziel-Docker-Repository, falls es noch nicht vorhanden ist. Sie müssen ein Repository erstellen, bevor Sie Images per Push übertragen können. Durch das Übertragen eines Images kann die Erstellung eines Repositorys nicht ausgelöst werden und das Cloud Build-Dienstkonto verfügt nicht über die Berechtigungen zum Erstellen von Repositories.

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

  4. Geändert: Beim Repository authentifizieren Wenn Sie den Credential Helper in der gcloud CLI verwenden, müssen Sie die Hosts angeben, die Sie Ihrer 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: Bild erstellen und taggen

    Der folgende Beispielbefehl entspricht dem Container Registry-Beispiel, verwendet aber einen Artifact Registry-Repositorypfad für das Image.

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

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

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

  7. Geändert: Holen Sie das Image über den Artifact Registry-Pfad aus dem Repository ab. Beispiel:

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

API aktivieren

Wichtige Fakten:

  • Sie müssen zusätzlich zur API für andere Google Cloud Dienste wie Cloud Build, Cloud Run und GKE die Artifact Registry API aktivieren.

Im folgenden Vergleich wird beschrieben, wie die API für jeden Dienst aktiviert wird:

Container Registry

Sie müssen die Container Registry API aktivieren, bevor Sie Docker oder andere Drittanbieter-Clients mit der Container Registry verwenden können.

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

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

Mit den Standardberechtigungen haben Nutzer, die Builds in Cloud Build ausführen, Container mit der Artefaktanalyse scannen oder Container inGoogle 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.

Dienste wie Cloud Build, Cloud Run und GKE aktivieren die Artifact Registry API nicht automatisch.

Mit gcloud können Sie mehrere APIs im selben Projekt aktivieren. Wenn Sie beispielsweise die Cloud Build API und die Artifact Registry API aktivieren möchten, führen Sie den Befehl aus:

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

Registries und Repositories hinzufügen

Wichtige Fakten:

  • Sie müssen ein Docker-Repository in Artifact Registry erstellen, bevor Sie ein Image per Push übertragen können.

    In der Dokumentation zum Hochladen von Images in die Container Registry wird der Schritt zum Erstellen einer Registry oft nicht erwähnt, da ein Konto mit Berechtigungen für Storage Admin einem Projekt beim ersten Push an den Registry-Host eine Registry hinzufügen kann.

  • Container Registry speichert alle Images in einer einzelnen Multiregion im selben Storage-Bucket. In Artifact Registry können Sie mehrere Repositories in derselben Region oder Multiregion 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 per Push übertragen.

  1. Wenn Sie Ihrem Projekt eine Registry wie gcr.io hinzufügen möchten, muss ein Konto mit der Rolle „Storage-Administrator“ auf Projektebene ein erstes Image per Push übertragen.

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

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

  2. Nach diesem ersten Push können Sie anderen Nutzern Berechtigungen für den Speicher-Bucket 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 Bild 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 „Artifact Registry Repository Administrator“ muss das Repository erstellen, bevor Sie Images per Push übertragen können. Anschließend können Sie anderen Nutzern Berechtigungen für das Repository erteilen.

In Artifact Registry ist jedes Repository eine separate Ressource. Daher müssen alle Bildpfade 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

In den folgenden Beispielen wird gezeigt, in welchen Fällen das Pushen eines Images in ein fehlendes Repository fehlschlägt.

  • Ein Bild wird an us-central1-docker.pkg.dev/my-project/team1 gesendet, wenn us-central1-docker.pkg.dev/my-project/team1 nicht vorhanden ist.
  • Ein Bild wird an us-central1-docker.pkg.dev/my-project/team2 gepusht, obwohl us-central1-docker.pkg.dev/my-project/team1 vorhanden ist, aber us-central1-docker.pkg.dev/my-project/team2 nicht.

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 Lese- oder Schreibzugriff auf Container Registry und Artifact Registry. Das standardmäßige Cloud Build-Dienstkonto kann jedoch keine Repositories erstellen.
  • Container Registry unterstützt die Zugriffssteuerung auf Storage-Bucket-Ebene. Artifact Registry unterstützt die Zugriffssteuerung auf Repository-Ebene.

Im folgenden Vergleich wird die Berechtigungseinrichtung in den einzelnen Diensten beschrieben:

Container Registry

In Container Registry wird der Zugriff mithilfe der Cloud Storage-Rollen gesteuert.

Storage-Objekt-Betrachter auf Ebene des Storage-Buckets
Images von vorhandenen Registry-Hosts im Projekt abrufen (lesen).
Autor alter Storage-Buckets auf Ebene des Storage-Buckets
Images für vorhandene Registry-Hosts im Projekt hochladen (schreiben) und abrufen (lesen).
Storage Admin auf Projektebene
Fügen Sie einem Projekt einen Registry-Host hinzu, indem Sie ein anfängliches Image auf den Host übertragen.

Nach dem ersten Push des Images an eine Registry gewähren Sie anderen Konten, die Zugriff auf den Storage-Bucket benötigen, Cloud Storage-Rollen. Hinweis: Jedes Konto mit allen Berechtigungen der Rolle „Storage Admin“ kann Storage-Buckets und -Objekte im gesamten Projekt lesen, schreiben und löschen.

Berechtigungen für einen Storage-Bucket gelten für alle Repositories in der Registry. So kann beispielsweise jeder Nutzer mit Storage Object Viewer-Berechtigungen für den Bucket für gcr.io/my-project Bilder 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 zur Zugriffssteuerung. Diese Rollen sorgen für eine klare Trennung zwischen Administrator- und Repository-Nutzerrollen.

Nur Konten, die Repositories verwalten, sollten die Rolle „Repository-Administrator für Artifact Registry“ oder „Administrator für Artifact Registry“ haben.

Artifact Registry-Leser
Artefakte und Repositories auflisten. Artefakte herunterladen.
Artifact Registry-Autor
Artefakte und Repositories auflisten. Sie können Artefakte herunterladen, neue Artefaktversionen hochladen und Tags hinzufügen oder aktualisieren.
Repository-Administrator für Artifact Registry
Artifact Registry Writer-Berechtigungen und Berechtigungen zum Löschen von Artefakten und Tags.
Artifact Registry-Administrator
Berechtigungen für Artifact Registry-Repository-Administratoren und Berechtigungen 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 auf us-central1-docker.pkg.dev/my-project/team1 gewähren
  • Gewähren Sie Team 2 Zugriff auf us-central1-docker.pkg.dev/my-project/team2.

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

Bei der Registry authentifizieren

Wichtige Fakten:

  • Artifact Registry unterstützt dieselben Authentifizierungsmethoden wie Container Registry.
  • Für den 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.

Wenn Sie beispielsweise die Authentifizierung für Docker-Repositories in der Region us-central1 einrichten möchten, führen Sie den folgenden Befehl aus:

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 Ihrer 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 Authentifizierungsmethoden von Artifact Registry finden Sie unter Authentifizierung für Docker einrichten.

Passwortauthentifizierung verwenden

Verwenden Sie beim Anmelden in Docker den Hostnamen der Artifact Registry anstelle eines *.gcr.io-Hostnamens. Im folgenden Beispiel wird die Authentifizierung mit einem base64-codierten Dienstkontoschlüssel beim Host us-central1-docker.pkg.dev gezeigt:

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 Tagging eines Images den Pfad in Artifact Registry anstelle des Pfads in Container Registry. 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 per Push übertragen. – Artifact Registry verwendet einen anderen Hostnamen für Repositories.

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

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

Images aus der Registry herunterladen

Wichtiger Punkt:

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

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

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

Beispiele für die Bereitstellung von Images in Google Cloud Laufzeitumgebungen wie Cloud Run und GKE finden Sie unter Images bereitstellen.