Änderungen für die Erstellung und Bereitstellung in Google Cloud

In diesem Dokument werden die Unterschiede zwischen Container Registry und Artifact Registry beim Erstellen von Container-Images mit Cloud Build und der Bereitstellung in Google Cloud-Laufzeitumgebungen wie Cloud Run oder Google Kubernetes Engine 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 Dabei müssen Sie dennoch einige Unterschiede im Workflow berücksichtigen:

  • 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 mit einem Docker-Client finden Sie unter Änderungen am Push und Abrufen mit Docker.

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

Hinweis

In diesem Dokument wird Folgendes vorausgesetzt:

  1. Artifact Registry in Ihrem Projekt aktiviert.
  2. Aktivieren Sie die Cloud Build API und die API für jeden anderen Google Cloud-Dienst, den Sie mit Artifact Registry verwenden.

Änderungen am Workflow

Wenn Sie Cloud Build mit Container Registry innerhalb desselben Projekts verwenden, sieht der Workflow so aus:

  1. Erstellen Sie mit Cloud Build ein Image, taggen Sie es und übertragen Sie es per Push in das Repository. Verwenden Sie dazu Dockerfile oder eine Build-Konfigurationsdatei.

    Im folgenden Beispiel wird das Image erstellt:my-image , versehen es mittag1 und überträgt diesen per Push an den Host.gcr.io im Projektmy-project :

    gcloud builds submit --tag gcr.io/my-project/my-image:tag1
    
  2. Google Cloud-Laufzeitumgebungen wie Cloud Run und Google Kubernetes Engine rufen Images aus der Registry ab.

    Mit diesem Befehl wird beispielsweise das Image aus dem vorherigen Schritt als my-service in Cloud Run bereitgestellt.

    gcloud run deploy my-service --image gcr.io/my-project/my-image:tag1
    

Der Container Registry-Workflow kombiniert Administratoraufgaben mit dem Erstellen und Bereitstellen.

  • 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.
  • Das Cloud Build-Dienstkonto hat Berechtigungen zum Erstellen von Cloud Storage-Storage-Buckets. Dies bedeutet, dass das Konto Container Registry-Hosts automatisch zu einem Projekt hinzufügen kann, wenn es zum ersten Mal ein Image per Push an den Host überträgt. Dies bedeutet auch, dass das Konto Speicher-Buckets über das gesamte Projekt erstellen, lesen und in diesen schreiben kann, einschließlich Buckets, die nicht von Container Registry verwendet werden.

In Artifact Registry gibt es eine klare Trennung von Administrator- und Build-Rollen, die die Schritte im Workflow für Build und Deployment ä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.

  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. Geändert: Erstellen, taggen und per Push übertragen ein Image mit Cloud Build mithilfe eines Dockerfile oder einer Build-Konfigurationsdatei in das Repository verschieben.

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

    gcloud builds submit --tag us-central1-docker.pkg.dev/my-repo/my-image:tag1
    
  4. Geändert: Image in einer Google Cloud-Laufzeitumgebung wie Cloud Run oder GKE bereitstellen.

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

    gcloud run deploy my-service --image us-central1-docker.pkg.dev/my-repo/my-image:tag1
    

Darüber hinaus verwendet Artifact Registry andere Rollen als Container Registry, um den Zugriff auf Images zu steuern. Sie müssen in den folgenden Situationen Berechtigungen konfigurieren:

  • Cloud Build- oder Google Cloud-Laufzeitumgebungen befinden sich in einem anderen Projekt als Artifact Registry.
  • Sie verwenden anstelle der Standarddienstkonten benutzerdefinierte Dienstkonten für Google Cloud-Dienste wie Cloud Build oder GKE.
  • Sie haben anderen Nutzern oder Dienstkonten Berechtigungen gewährt.

API aktivieren

Wichtige Fakten:

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

Container Registry

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 dasselbe Projekt.

Artifact Registry

Sie müssen die Artifact Registry API aktivieren. 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.
  • 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.

Standardmäßig hat Cloud Build die erforderlichen Berechtigungen zum Erstellen eines Storage-Buckets. Daher sind die anfänglichen Image-Push- und nachfolgenden Push-Vorgänge nicht zu unterscheiden.

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

Cloud Build ist nicht berechtigt, ein Repository zu erstellen.

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:

  • 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.
  • Den anderen Konten, die auf Artifact Registry zugreifen, die entsprechenden Artifact Registry-Rollen zuweisen.
  • 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 jeden Dienst beschrieben:

Container Registry

Container Registry verwendet die Cloud Storage-Rollen, um den Zugriff zu steuern. Cloud Build hat die erforderlichen Berechtigungen in der Rolle "Storage-Administrator", um einem Projekt Container Registry-Hosts hinzuzufügen.

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.

Cloud Build hat Berechtigungen in der Rolle "Artifact Registry-Autor", da nur Images per Push und Pull übertragen werden müssen.

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.

Images erstellen und per Push übertragen

Wichtige Fakten:

  • Sie müssen ein Artifact Registry-Docker-Repository erstellen, bevor Sie ein Image per Push übertragen.
  • Die Artifact Registry-Hostnamen unterscheiden sich von den Container Registry-Hostnamen.

Cloud Build kann ein Image in einem einzigen Schritt erstellen, taggen und per Push übertragen.

Mit Container Registry kann Cloud Build ein Image erfolgreich an einen Registry-Host übertragen, der im Google Cloud-Projekt noch nicht vorhanden ist. Für diese erste Image-Übertragung hat Cloud Build die Berechtigung, dem Registry-Host automatisch den Projekteintrag hinzuzufügen.

So passen Sie einen Container Registry-Workflow an:

  1. Repositories einrichten, bevor Images per Push übertragen werden
  2. Aktualisieren Sie die Image-Pfade in der Build-Konfigurationsdatei oder in den gcloud builds submit-Befehlen.

Mit einer Build-Konfigurationsdatei erstellen

Ersetzen Sie Container Registry-Pfade für Images, die Sie mit dem Pfad zu einem vorhandenen Artifact Registry-Repository erstellen.

Mit der folgenden Beispieldatei cloudbuild.yaml wird das Image us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1 erstellt:

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: [ 'build', '-t', 'us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1', '.' ]
images:
- 'us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1'

Sie können das Image mit dem folgenden Befehl erstellen:

gcloud builds submit --config cloudbuild.yaml

Mit einem Dockerfile erstellen

Ersetzen Sie Container Registry-Pfade für Images, die Sie mit dem Pfad zu einem vorhandenen Artifact Registry-Repository erstellen.

Mit dem folgenden Beispielbefehl wird das Image us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1 mit einer Dockerfile im aktuellen Verzeichnis erstellt:

gcloud builds submit --tag us-central1-docker.pkg.dev/my-repo/my-image:tag1

Images bereitstellen

Wichtiger Hinweis:

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

Zum Anpassen eines Container Registry-Workflows aktualisieren Sie Image-Pfade in Ihrer Bereitstellungskonfiguration und Ihren Bereitstellungsbefehlen. Die folgenden Abschnitte zeigen Beispiele für Cloud Build, Cloud Run und GKE. Der gleiche Ansatz gilt jedoch auch für alle anderen Google Cloud-Dienste, die Images bereitstellen.

Cloud Build

Ersetzen Sie Container Registry-Pfade für Images, die Sie durch den Pfad zu einem vorhandenen Artifact Registry-Repository bereitstellen.

Mit der folgenden Beispieldatei cloudbuild.yaml wird das Beispiel-Image us-docker.pkg.dev/cloudrun/container/hello bereitgestellt.

steps:
- name: 'gcr.io/cloud-builders/gcloud'
  args:
  - 'run'
  - 'deploy'
  - 'cloudrunservice'
  - '--image'
  - 'us-docker.pkg.dev/cloudrun/container/hello'
  - '--region'
  - 'us-central1'
  - '--platform'
  - 'managed'
  - '--allow-unauthenticated'

Cloud Run

Ersetzen Sie Container Registry-Pfade für Images, die Sie durch den Pfad zu einem vorhandenen Artifact Registry-Repository bereitstellen.

Mit diesem Befehl wird beispielsweise das Beispiel-Image us-docker.pkg.dev/cloudrun/container/hello bereitgestellt.

gcloud run deploy my-service --image us-docker.pkg.dev/cloudrun/container/hello

GKE

Ersetzen Sie Container Registry-Pfade für Images, die Sie mit dem Pfad zu einem vorhandenen Artifact Registry-Repository erstellen.

In den folgenden Beispielen für Artifact Registry wird das Beispiel-Image us-docker.pkg.dev/artifact-registry-samples/containers/gke/hello-app:1.0 verwendet.

Cluster über die Befehlszeile erstellen:

kubectl create deployment hello-server --image=us-docker.pkg.dev/artifact-registry-samples/containers/gke/hello-app:1.0

Image in einem Deployment-Manifest angeben:

In a deployment manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      run: my-app
  template:
    metadata:
      labels:
        run: my-app
    spec:
      containers:
      - name: hello-app
        image: us-docker.pkg.dev/artifact-registry-samples/containers/gke/hello-app:1.0