Änderungen für Docker

In diesem Dokument werden Sie durch die Unterschiede zwischen Container Registry und Artifact Registry zum Authentifizieren, Übertragen und Abrufen von Container-Images mit Docker geführt.

Die Unterschiede zwischen Container Registry und Artifact Registry beim Erstellen mit Cloud Build und dem Bereitstellen in Cloud Run oder Google Kubernetes Engine finden Sie unterÄnderungen für Cloud Build, Cloud Run und GKE auf.

Verwenden Sie diese Informationen, um vorhandene Befehle, Konfigurationen oder Dokumentationen anzupassen, die auf Container Registry mit Docker spezialisiert sind.

Hinweis

In diesem Dokument wird davon ausgegangen, dass Sie über Folgendes verfügen:

  1. Artifact Registry in Ihrem Projekt aktiviert haben.
  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 oder 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 an den Host übertragen.
  3. Weisen Sie dem Storage-Bucket Cloud Storage-Rollen für den Registry-Host zu, um Zugriff auf Images zu gewähren.
Administrator
  1. Artifact Registry API aktivieren
  2. Fügen Sie ein Docker-Repository hinzu.
  3. Weisen Sie Artifact Registry-Rollen den Zugriff auf Images an.
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. Ziehen Sie das Image aus der Registry 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. Ziehen Sie das Image aus der Registry oder stellen Sie es in einer Google Cloud-Laufzeit bereit.

Eine Verknüpfung für Container Registry stellt jedoch die Administrator- und Nutzerrollen in einem einzigen Workflow zusammen. Diese Tastenkombination ist üblich in:

  • Kurzanleitungen und Anleitungen, in denen Sie Tests in einer Umgebung durchführen, in der Sie umfassende Berechtigungen haben.
  • Workflows, die Cloud Build verwenden, da das Cloud Build-Dienstkonto berechtigt ist, einen Registry-Host im selben Google Cloud-Projekt hinzuzufügen.

Der Ablauf der Verknüpfung sieht so aus:

  1. Aktivieren Sie die Container Registry API.
  2. Berechtigungen für das Konto erteilen, mit dem auf die Artifact Registry zugegriffen wird
  3. Authentifizieren Sie sich in der Registry. Die einfachste Authentifizierungsmethode ist die Verwendung des Docker Credential Helper im Cloud SDK. Dies ist ein einmaliger Konfigurationsschritt.

    gcloud auth configure-docker
    
  4. Erstellen und taggen Sie das Image. 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. Image in die Registry hochladen. Beispiel:

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

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

  6. Ziehen Sie das Image aus der Registry 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, mit dem Images übertragen werden, hat die Rolle "Storage-Administrator" oder eine Rolle mit denselben Berechtigungen wie "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 Registry-Hosts standardmäßig hinzufügen.

In Artifact Registry gibt es eine klare Trennung von Administrator- und Repository-Nutzerrollen, die die Schritte im Build- und Bereitstellungsworkflow ändern. 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 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 darauf hochladen können. Durch das Übertragen eines Images kann kein Erstellen eines Repositorys ausgelöst werden und das Cloud Build-Dienstkonto ist nicht berechtigt, Repositories zu erstellen.

  3. Weisen Sie dem Konto Berechtigungen zu, die mit Artifact Registry interagieren.

  4. Geändert: Authentifizierung für das Repository Wenn Sie Credential Helper im Cloud SDK verwenden, müssen Sie die Hosts angeben, die Sie der Docker-Clientkonfiguration 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: 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-central-docker.pkg.dev/my-project/my-repo/my-image:tag1
    
  6. Geändert: Push das Image mithilfe des Artifact Registry-Pfads in das Repository. Beispiel:

    docker push us-central-docker.pkg.dev/my-project/my-repo/my-image:tag1
    
  7. Geändert: Übertragen Sie das 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 beschrieben, wie Sie die API für jeden Dienst aktivieren:

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 die Container Registry API ebenfalls automatisch aktiviert:

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

Mit den Standardberechtigungen können Nutzer, die Builds in Cloud Build ausführen, Container mit Artifact Analysis scannen oder Container in Google Cloud-Laufzeiten bereitstellen, implizit implizit auf Images in Container Registry zugreifen, wenn sich die Registry in der Projekt verwendet wird.

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. Verwenden Sie beispielsweise den folgenden Befehl, um die Cloud Build API und die Artifact Registry API zu aktivieren:

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

Registrys und Repositories hinzufügen

Wichtige Fakten:

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

    Ein Schritt zur Erstellung von Registrys wird häufig in der Dokumentation enthalten, in der das Hochladen von Images in Container Registry beschrieben wird, da ein Konto mit Storage-Administratorberechtigungen einem Projekt eine Registry hinzufügen kann.

  • Container Registry speichert alle Images in einem multiregionalen Speicherort im selben Storage-Bucket. In Artifact Registry können Sie mehrere Repositories in derselben Region oder Mehrfachregion mit separaten Zugriffsrichtlinien erstellen.

Der folgende Vergleich beschreibt die Einrichtung des Repositorys in jedem Dienst:

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, sendet ein Konto mit der Rolle "Storage-Administrator" auf Projektebene ein erstes Image.

    Wenn der gcr.io-Host beispielsweise nicht im Projekt my-project vorhanden ist, werden beim Hochladen 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. Speichern Sie das Image als gcr.io/my-project/my-image:1.0
  2. Nach diesem ersten Push 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 "Artefakte-Repository-Administrator" muss das Repository erstellen, bevor Sie Images darauf übertragen. Sie können dem Repository dann Berechtigungen für andere Nutzer 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.

  • Übertragen 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 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 nicht existiert.

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 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 Berechtigungen der einzelnen Dienste beschrieben:

Container Registry

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

Storage-Objekt-Betrachter auf Storage-Bucket-Ebene
Pull-Images von vorhandenen Registry-Hosts im Projekt abrufen.
Storage-Objekt-Administrator auf Storage-Bucket-Ebene
Hochladen (Schreiben) und Abrufen (Lesen) von Images für vorhandene Registry-Hosts im Projekt.
Storage-Administrator auf Projektebene
Fügen Sie einem Projekt einen Registry-Host hinzu, indem Sie ein erstes Image an den Host übertragen.

Nach dem ersten Image-Push in eine Registry 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 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 den Storage-Objekt-Betrachter-Berechtigungen im 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 verfügt über eigene Rollen, um den Zugriff zu steuern. Diese Rollen ermöglichen eine klare Trennung zwischen Administrator- und Repository-Nutzerrollen.

Nur Konten, die Repositories verwalten, sollten die Administratorrolle "Artefakte-Repository" oder "Artifact Registry-Administrator" 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
Artefakte-Berechtigungen und Berechtigungen zum Löschen von Artefakten und Tags.
Artifact Registry-Administrator
Artifact Registry-Repository-Administrator 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:

  • us-central1-docker.pkg.dev/my-project/team1 Zugriff auf Team 1 gewähren
  • Zugriff für Team 2 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.

Bei der Registrierung 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 zur Authentifizierung mit docker login den Artifact Registry-Host anstelle eines Container Registry-Hosts.

Credential Helper verwenden

Der Befehl gcloud auth configure-docker und der eigenständige Credential Helper konfigurieren Docker standardmäßig nur für *.gcr.io-Hostnamen. 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 die Docker-Konfiguration der entsprechenden regionalen Hostnamen hinzuzufügen.

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

Weitere Informationen zur Authentifizierung von Artifact Registry finden Sie unter Authentifizierung für Docker einrichten.

Passwortauthentifizierung verwenden

Verwenden Sie beim Anmelden in Docker den Hostnamen von Artifact Registry anstelle des Hostnamens *.gcr.io. Das folgende Beispiel zeigt die Authentifizierung mit einem base64-codierten Dienstkontoschlüssel für den 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

Wichtiger Hinweis: - Artifact Registry verwendet für die Repositories einen anderen Hostnamen.

Wenn Sie ein Image taggen, verwenden Sie anstelle des Container Registry-Pfads den Artifact Registry-Pfad. 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 für Repositories einen anderen Hostnamen.

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

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

Images aus der Registry herunterladen

Wichtigstes Thema:

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

Wenn Sie ein Image abrufen, verwenden Sie anstelle des Container Registry-Pfads den Artifact 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 finden Sie unter Images bereitstellen.