Änderungen für Docker

In diesem Dokument werden die Unterschiede zwischen Container Registry erläutert. und Artifact Registry zum Authentifizieren, Hoch- und Herunterladen von Container-Images mit Docker erstellen.

In diesem Leitfaden konzentrieren sich die Vergleiche auf Standard-Artifact Registry-Repositories, also reguläre Artifact Registry-Repositories, die unabhängig von der 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 der Bereitstellung in Cloud Run oder Google Kubernetes Engine, siehe Ä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.

Hinweise

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

  1. Artifact Registry wurde 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 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 Tastenkombination für Container Registry ist jedoch, und Nutzerrollen in einem Workflow zusammengefasst. Diese Tastenkombination ist häufig in folgenden Sprachen verfügbar:

  • Kurzanleitungen und Tutorials, in denen Sie Tests in einer Umgebung durchführen, in der Sie umfassende Berechtigungen haben.
  • Workflows, die Cloud Build verwenden, da der Cloud Build-Dienst Konto hat die Berechtigung zum Hinzufügen eines Registry-Hosts in derselben Google Cloud Projekt arbeiten.

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

  1. Aktivieren Sie die Container Registry API.
  2. Erteilen Sie dem Konto Berechtigungen für den Zugriff auf Container Registry.

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

    gcloud auth configure-docker

  4. Erstellen und taggen Sie das Image. Mit diesem Befehl wird z. B. das Image erstellt und mit Tags versehen. gcr.io/my-project/my-image:tag1:

    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 vor dem Hochladen des Images hinzugefügt.

  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 Tastenkürzeln:

  • Das Konto, über das Bilder gepusht werden, hat die Rolle „Storage-Administrator“ oder eine Rolle mit denselben Berechtigungen, z. B. „Inhaber“. Aufgrund der umfassenden Berechtigungen dieser Rolle 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, Die Container Registry API wird automatisch aktiviert. Das bedeutet, dass Nutzer dieser Dienste impliziten Zugriff auf Container Registry im selben Projekt haben. Für Nutzer, die Builds in Cloud Build ausführen können, können z. B. Images an Registry-Hosts standardmäßig 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. Jeder Schritt ist mit zusätzlichen Informationen zum Ändern des Workflows verknüpft.

  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, die API nicht automatisch für Sie aktivieren.

  2. Neu: Erstellen Sie das Ziel-Docker-Repository, falls nicht bereits vorhanden sind. Sie müssen ein Repository erstellen, bevor Sie Images per Push an . 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 dem Artifact Registry.

  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 ist mit dem Container Registry-Beispiel identisch: Für das Image wird jedoch ein Artifact Registry-Repository-Pfad verwendet.

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

  6. Geändert: Übertragen Sie das Image mittels Push in das Repository. Artifact Registry-Pfad. 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

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 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 Run-Funktionen
  • Cloud Run
  • Container-Scan oder On-Demand-Scan in der Artefaktanalyse
  • Google Kubernetes Engine

Mit den Standardberechtigungen können Nutzer, die Builds in Cloud Build ausführen können, Scannen Sie Container mit der Artefaktanalyse oder stellen Sie Container bereit, Google Cloud-Laufzeiten haben 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.

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

Registrys 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.

    Ein Schritt zur Registry-Erstellung wird in der Dokumentation, die beschreibt das Hochladen von Images in Container Registry, da ein Konto mit Storage Mit Administratorberechtigungen kann einem Projekt eine Registry mit der ersten Übertragung an den Registry-Host.

  • Container Registry speichert alle Images an einer einzigen Multiregion im selben Storage-Bucket. In Artifact Registry können Sie mehrere Repositories in derselben Region oder Mehrfachregion mit separaten Zugriffsrichtlinien.

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 ID Die Rolle „Storage Admin“ auf Projektebene überträgt ein anfängliches Image.

    Beispiel: Der Host gcr.io ist im Projekt nicht vorhanden. my-project, die gcr.io/my-project/my-image:1.0-Trigger für das Image werden übertragen führen Sie die folgenden Schritte aus:

    1. gcr.io-Host zum Projekt hinzufügen
    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 davon 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. Dementsprechend wird Alle Image-Pfade müssen 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 ein Bild per Push-Funktion fehlendes Repository schlägt fehl.

  • Bild per Push an us-central1-docker.pkg.dev/my-project/team1 übertragen, wenn us-central1-docker.pkg.dev/my-project/team1 ist nicht vorhanden.
  • 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 gleichwertigen Lese- oder Schreibzugriff auf beides Container Registry und Artifact Registry. Die Standardeinstellung Das Cloud Build-Dienstkonto kann keine Repositories erstellen.
  • Container Registry unterstützt die Zugriffssteuerung auf Ebene des Storage-Buckets. Artifact Registry unterstützt die Zugriffssteuerung auf Repository-Ebene.

Im folgenden Vergleich wird beschrieben, wie die Berechtigungen in den einzelnen Diensten eingerichtet werden:

Container Registry

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

Storage-Objekt-Betrachter auf Storage-Bucket-Ebene
Images von 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 (Lesezugriff) senden.
Storage-Administrator auf Projektebene
Fügen Sie einem Projekt einen Registry-Host hinzu, indem Sie ein anfängliches Image auf den Host übertragen.

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

Berechtigungen für einen Storage-Bucket gelten für alle Repositories in der Registry. Beispiel: Jeder Nutzer mit Storage Object Viewer-Berechtigungen für die Bucket für gcr.io/my-project kann 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 Steuerung des Zugriffs. Diese Rollen sorgen für eine klare Trennung zwischen Administrator- und Repository-Nutzerrollen.

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

Artifact Registry-Leser
Artefakte und Repositories auflisten. Artefakte herunterladen.
Artifact Registry-Autor
Artefakte und Repositories auflisten. Artefakte herunterladen, neues Artefakt hochladen und fügen Sie Tags hinzu oder aktualisieren Sie sie.
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:

  • Zugriff auf Team 1 für 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 statt auf einen Container Registry-Host.

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 und fügen Sie die entsprechenden regionalen Hostnamen Docker-Konfiguration.

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 beim Anmelden in Docker den Hostnamen der Artifact Registry 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

Bilder erstellen und taggen

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

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 eine ein Bild hinzufügen. – 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

Wichtig:

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

Verwenden Sie beim Abrufen eines Images den Artifact Registry-Pfad anstelle des Container Registry-Pfad. 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, siehe Images bereitstellen