Änderungen für Docker

In diesem Dokument werden die Unterschiede zwischen Container Registry und Artifact Registry zum Authentifizieren, Übertragen und Abrufen von Container-Images mit Docker erläutert.

In dieser Anleitung geht es insbesondere um Artefakte aus Standard-Artifact Registry, reguläre Artifact Registry-Repositories, die unabhängig von Container Registry sind und alle Artifact Registry-Features unterstützen.

Wenn Ihr Administrator Repositories mit Unterstützung für die gcr.io-Domain eingerichtet hat, werden Anfragen an gcr.io-Hostnamen automatisch an ein entsprechendes Artifact Registry-Repository weitergeleitet, aber Sie müssen trotzdem Berücksichtigen Sie einige Unterschiede im Workflow, einschließlich:

  • Repository-Erstellung: In Artifact Registry können Sie Images nur in ein vorhandenes Repository übertragen.
  • Berechtigungen: Artifact Registry hat eigene Berechtigungen, um den Zugriff auf Repositories zu steuern.

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

Mit diesen Informationen können Sie vorhandene Befehle, Konfigurationen oder Dokumentationen, die sich auf Container Registry mit Docker konzentrieren, anpassen.

Hinweis

In diesem Dokument wird Folgendes vorausgesetzt:

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

Übersicht

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

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 im Storage-Bucket Cloud Storage-Rollen zu, um Zugriff auf Images zu gewähren.
Administrator
  1. Artifact Registry API aktivieren
  2. Docker-Repository hinzufügen
  3. Weisen Sie Artifact Registry-Rollen zu, um Zugriff auf Images zu gewähren.
Registry-Nutzer
  1. Definieren Sie das Image in der Datei Dockerfile.
  2. Image erstellen
  3. Authentifizieren Sie sich in der Registry.
  4. Taggen Sie das Image und übertragen Sie es 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 Image in der Datei Dockerfile.
  2. Image erstellen
  3. Authentifizieren Sie sich in der Registry.
  4. Taggen Sie das Image und übertragen Sie es in die Registry.
  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:

  • Kurzanleitungen und Anleitungen, in denen Sie in einer Umgebung testen können, in der Sie weitreichende Berechtigungen haben.
  • Workflows, die Cloud Build verwenden, da das Cloud Build-Dienstkonto berechtigt ist, im selben Google Cloud-Projekt einen Registry-Host hinzuzufügen.

Der Verknüpfungsworkflow sieht so aus:

  1. Aktivieren Sie die Container Registry API.
  2. Gewähren Sie dem Konto, das auf Artifact Registry zugreifen soll, Berechtigungen.
  3. Authentifizieren Sie sich in der Registry. Die einfachste Authentifizierungsoption ist die Verwendung des Docker Credential Helper im Cloud SDK. Dies ist ein einmaliger Konfigurationsschritt.

    gcloud auth configure-docker
    
  4. Erstellen Sie ein 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
    

Dieser Workflow basiert auf den folgenden Tastenkombinationen:

  • Das Konto, das Images per Push überträgt, hat die Rolle "Storage-Administrator" oder eine Rolle mit denselben Berechtigungen wie "Inhaber". Die umfassenden Berechtigungen dieser Rolle gewähren 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. Dies bedeutet, dass Nutzer dieser Dienste impliziten Zugriff auf Container Registry im selben Projekt haben. Beispielsweise können Nutzer, die Builds in Cloud Build ausführen, standardmäßig Images in Registries übertragen und Registry-Hosts hinzufügen.

In Artifact Registry gibt es eine klare Trennung von Administrator- und Repository-Nutzerrollen, die die Schritte im Build- und Deployment-Workflow ändert. Nehmen Sie die folgenden Änderungen vor, um den Container Registry-Workflow für Artifact Registry anzupassen. Jeder Schritt enthält zusätzliche 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.

  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 in dieses Repository übertragen können. Das Hochladen eines Images kann nicht durch das Erstellen eines Repositorys ausgelöst werden und das Cloud Build-Dienstkonto ist nicht berechtigt, Repositories zu erstellen.

  3. Gewähren Sie dem Konto, das mit Artifact Registry interagiert, Berechtigungen.

  4. Geändert: Authentifizieren Sie sich beim Repository. Wenn Sie das Tool "Credential Helper" im Cloud SDK verwenden, müssen Sie die Hosts angeben, die Sie der Konfiguration des Docker-Clients hinzufügen möchten. Mit diesem Befehl wird beispielsweise der Host us-central-docker.pkg.dev hinzugefügt:

    gcloud auth configure-docker us-central-docker.pkg.dev
    
  5. Geändert: Image erstellen und mit Tag versehen

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

    docker build -t us-central-docker.pkg.dev/my-project/my-repo/my-image:tag1
    
  6. Geändert: Übertragen Sie das Image mithilfe des Artifact Registry-Pfads an das Repository. Beispiel:

    docker push us-central-docker.pkg.dev/my-project/my-repo/my-image:tag1
    
  7. Geändert: Pull-Image aus dem Repository mithilfe des Artifact Registry-Pfads. Beispiel:

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

API aktivieren

Wichtige Fakten:

Im folgenden Vergleich wird die Aktivierung der API für jeden Dienst beschrieben:

Container Registry

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

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

  • Flexible App Engine-Umgebung
  • Cloud Build
  • Cloud Functions
  • Cloud Run
  • Containerscans oder On-Demand-Scans in der Artefaktanalyse
  • Google Kubernetes Engine

Mit den Standardberechtigungen haben Nutzer, die Builds in Cloud Build ausführen, Container mit Artifact Analysis scannen oder Container in Google Cloud-Laufzeiten bereitstellen können, Zugriff auf Images in Container Registry, wenn sich die Registry in der innerhalb desselben Projekts.

Artifact Registry

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

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. 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 per Push übertragen.

    Ein Schritt der Registry-Erstellung wird häufig in der Dokumentation ausgeschlossen, die das Übertragen von Images an Container Registry beschreibt, da ein Konto mit Storage Admin-Berechtigungen einem Projekt eine Registrierung mit dem ersten Push zum Registry-Host hinzufügen kann.

  • Container Registry speichert alle Images in einer einzigen 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 für jeden Dienst beschrieben:

Container Registry

In Container Registry können Sie Ihrem Projekt bis zu vier Registry-Hosts hinzufügen. Fügen Sie 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, wird von einem Konto mit der Rolle StorageStorage-Administrator“ auf Projektebene ein erstes Image per Push übertragen.

    Wenn der Host gcr.io beispielsweise nicht im Projekt my-project vorhanden ist, werden durch Push 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 einen Storage-Bucket für gcr.io im Projekt.
    3. Bild als gcr.io/my-project/my-image:1.0 speichern
  2. Nach dieser ersten Übertragung können Sie dem Storage-Bucket für andere Nutzer 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 mit dem Namen 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 "Artifact Registry-Repository-Administrator" muss das Repository erstellen, bevor Sie Images per Push in das Repository übertragen. Sie können dem Repository dann Berechtigungen für andere Nutzer zuweisen.

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 Übertragen eines Images in ein fehlendes Repository fehlschlägt.

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

Berechtigungen gewähren

Wichtige Fakten:

  • Weisen Sie dem Konto, das Sie mit Artifact Registry verwenden, die entsprechende Rolle für Artifact Registry zu.
  • Google Cloud-Dienste haben entsprechenden Lese- oder Schreibzugriff auf Container Registry und Artifact Registry. Mit dem standardmäßigen Cloud Build-Dienstkonto können jedoch keine Repositories erstellt werden.
  • Container Registry unterstützt die Zugriffssteuerung auf Speicher-Bucket-Ebene. Artifact Registry unterstützt die Zugriffssteuerung auf Repository-Ebene.

Im folgenden Vergleich werden die Berechtigungen für die einzelnen Dienste beschrieben:

Container Registry

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

Storage-Objekt-Betrachter auf Ebene des Storage-Buckets
Images aus vorhandenen Registry-Hosts im Projekt abrufen (lesen)
Autor alter Storage-Buckets auf Ebene des Storage-Buckets
Images für vorhandene Registry-Hosts im Projekt per Push (Schreibvorgang) abrufen und abrufen (Pull)
Storage-Administrator auf Projektebene
Fügen Sie einem Projekt einen Registry-Host hinzu, indem Sie ein anfängliches Image an den Host übertragen.

Nachdem das erste Image in eine Registry übertragen wurde, weisen Sie anderen Konten, die Zugriff auf den Storage-Bucket benötigen, Cloud Storage-Rollen zu. Beachten Sie, dass jedes Konto mit allen Berechtigungen in der Rolle "Storage-Administrator" Storage-Buckets und Storage-Objekte 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 Storage Object Viewer-Berechtigungen für den Bucket für gcr.io/my-project Images in allen diesen 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 bieten eine klare Trennung zwischen Administrator- und Repository-Nutzerrollen.

Nur Konten, die Repositories verwalten, 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 sowie Tags hinzufügen oder aktualisieren.
Repository-Administrator für Artifact Registry
Berechtigungen und Berechtigungen von Artifact Registry-Autoren zum Löschen von Artefakten und Tags.
Artifact Registry-Administrator
Artifact Registry-Repository-Administratorberechtigungen 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:

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

Weitere Informationen zum Erteilen 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 statt eines Container Registry-Hosts.

Credential Helper verwenden

Der Befehl gcloud auth configure-docker und der eigenständige Credential Helper konfigurieren Docker nur für *.gcr.io-Hostnamen standardmäßig. 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 Artifact Registry-Authentifizierungsmethoden finden Sie unter Authentifizierung für Docker einrichten.

Passwortauthentifizierung verwenden

Verwenden Sie bei der Anmeldung in Docker den Artifact Registry-Hostnamen anstelle eines *.gcr.io-Hostnamens. 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.

Wenn Sie ein Image taggen, verwenden Sie 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 per Push übertragen. – Artifact Registry verwendet einen anderen Hostnamen für Repositories.

Wenn Sie ein Image per Push übertragen, 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

Wichtiger Hinweis:

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

Verwenden Sie beim Abrufen eines Images den Pfad der Artifact Registry anstelle des Container Registry-Pfads. 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-Laufzeiten wie Cloud Run und GKE finden Sie unter Images bereitstellen.