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

In diesem Dokument werden die Unterschiede zwischen Container Registry und Artifact Registry beschrieben, wenn Sie Container-Images mit Cloud Build erstellen und in Google Cloud-Laufzeitumgebungen wie Cloud Run oder Google Kubernetes Engine bereitstellen.

In diesem Leitfaden konzentrieren sich die Vergleiche auf standardmäßige Artifact Registry-Repositories und reguläre Artifact Registry-Repositories, die von Container Registry unabhängig sind und alle Artifact Registry-Features unterstützen. Wenn Ihr Administrator Repositories mit gcr.io-Domainunterstützung eingerichtet hat, werden Anfragen an gcr.io-Hostnamen automatisch an ein entsprechendes Artifact Registry-Repository weitergeleitet. Standarddienstkonten mit Zugriff auf Container Registry haben entsprechende Standardberechtigungen für Artifact Registry.

Informationen zu den Unterschieden zwischen Container Registry und Artifact Registry mithilfe eines Docker-Clients finden Sie unter Änderungen beim Hoch- und Herunterladen mit Docker.

Verwenden Sie diese Informationen, um vorhandene Befehle, Konfigurationen oder Dokumentationen für Container Registry mit Cloud Build anzupassen.

Hinweise

In diesem Dokument wird Folgendes vorausgesetzt:

In Ihrem Projekt wurde Artifact Registry aktiviert.
Sie haben die Cloud Build API und die API für jeden anderen Google Cloud-Dienst aktiviert, den Sie mit Artifact Registry verwenden.

Änderungen am Workflow

Wenn Sie Cloud Build mit Container Registry im selben Projekt verwenden, sieht der Workflow so aus:

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

Im folgenden Beispiel wird das Image my-image erstellt, mit tag1 gekennzeichnet und per Push an den Host gcr.io im Projekt my-project übertragen:
```
gcloud builds submit --tag gcr.io/my-project/my-image:tag1
```
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 vereint die Verantwortung eines Administrators mit der Erstellung und Bereitstellung.

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 standardmäßig Registry-Hosts hinzufügen.
Das Cloud Build-Dienstkonto hat Berechtigungen zum Erstellen von Cloud Storage-Storage-Buckets. Das bedeutet, dass das Konto automatisch Container Registry-Hosts zu einem Projekt hinzufügen kann, wenn es zum ersten Mal ein Image auf den Host überträgt. Es bedeutet auch, dass das Konto Storage-Buckets im gesamten Projekt erstellen, lesen und schreiben kann, einschließlich Buckets, die nicht von Container Registry verwendet werden.

In Artifact Registry sind Administrator- und Build-Rollen klar voneinander getrennt, wodurch die Schritte im Build- und Bereitstellungsworkflow geändert werden. Nehmen Sie die folgenden Änderungen vor, um den Container Registry-Workflow für Artifact Registry anzupassen. Jeder Schritt enthält einen Link zu weiteren Informationen zum Ändern des Workflows.

Neu: Artifact Registry API aktivieren.

Sie müssen die Artifact Registry API aktivieren. In Cloud Build- und Laufzeitumgebungen wie Cloud Run und GKE wird die API nicht automatisch für Sie aktiviert.
Neu: Erstellen Sie das Ziel-Docker-Repository, falls es noch nicht vorhanden ist. Sie müssen ein Repository erstellen, bevor Sie Images dorthin hochladen können. Das Erstellen eines Repositorys kann durch das Hochladen eines Images nicht ausgelöst werden und das Cloud Build-Dienstkonto ist nicht berechtigt, Repositories zu erstellen.
Geändert: Verwenden Sie eine Dockerfile- oder Build-Konfigurationsdatei, um ein Image mit Cloud Build zu erstellen, zu taggen und in das Repository zu übertragen.

Der folgende Beispielbefehl ist mit dem Container Registry-Beispiel identisch, verwendet jedoch einen Artifact Registry-Repository-Pfad für das Image.
```
gcloud builds submit --tag us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
```
Geändert: Stellen Sie das Image in einer Google Cloud-Laufzeitumgebung wie Cloud Run oder GKE bereit.

Der folgende Beispielbefehl ist mit dem Container Registry-Beispiel identisch, verwendet jedoch den Artifact Registry-Repository-Pfad für das Image.
```
gcloud run deploy my-service --image us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
```

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

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

API aktivieren

Wichtige Fakten:

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

Im folgenden Vergleich wird das Aktivieren der API für jeden Dienst beschrieben:

Container Registry

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

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

Mit den Standardberechtigungen haben Nutzer, die Builds in Cloud Build ausführen, Container mit Artefaktanalyse scannen oder Container in Google 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. Durch Dienste wie Cloud Build, Cloud Run und GKE wird die Artifact Registry API nicht automatisch aktiviert.

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 dorthin hochladen.
Container Registry speichert alle Images an einem einzigen multiregionalen Standort im selben Storage-Bucket. In Artifact Registry können Sie mehrere Repositories in derselben oder mehreren Regionen 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 hochladen.

Um Ihrem Projekt eine Registry wie gcr.io hinzuzufügen, sendet ein Konto mit der Rolle „Storage-Administrator“ auf Projektebene ein erstes Image per Push.

Wenn beispielsweise der Host gcr.io im Projekt my-project nicht vorhanden ist, werden durch Übertragen 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 im Projekt einen Storage-Bucket für gcr.io.
3. Bild als gcr.io/my-project/my-image:1.0 speichern
Nach dieser ersten Übertragung können Sie dem Storage-Bucket Berechtigungen erteilen.

Cloud Build hat standardmäßig die erforderlichen Berechtigungen zum Erstellen eines Storage-Buckets. Daher sind die anfängliche und die nachfolgende Übertragung des Images nicht unterscheidbar.

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 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 Standard-Repository in der Artifact Registry-Domain pkg.dev zu erstellen.

Ein Konto mit der Rolle eines Artifact Registry Repository-Administrators muss das Repository erstellen, bevor Sie Images dorthin übertragen. Anschließend können Sie dem Repository für andere Nutzer Berechtigungen 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.

Image per Push an us-central1-docker.pkg.dev/my-project/team1 übertragen, wenn us-central1-docker.pkg.dev/my-project/team1 nicht vorhanden ist.
Image per Push an us-central1-docker.pkg.dev/my-project/team2 übertragen, wenn us-central1-docker.pkg.dev/my-project/team1 vorhanden ist, us-central1-docker.pkg.dev/my-project/team2 aber nicht vorhanden ist.

Berechtigungen gewähren

Wichtige Fakten:

Google Cloud-Dienste haben einen gleichwertigen Lese- oder Schreibzugriff auf Container Registry und Artifact Registry. Das Cloud Build-Standarddienstkonto kann jedoch keine Standard-Repositories in der Domain pkg.dev erstellen.
Gewähren Sie anderen Konten, die auf Artifact Registry zugreifen, die entsprechenden Artifact Registry-Rollen.
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 für die einzelnen Dienste beschrieben:

Container Registry

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

Storage-Objekt-Betrachter auf Storage-Bucket-Ebene: Images aus 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 (Lesen) abrufen.
Storage-Administrator auf Projektebene: Sie können einem Projekt einen Registry-Host hinzufügen, indem Sie ein erstes Image auf den Host übertragen.

Nachdem das erste Image per Push in eine Registry übertragen wurde, gewähren Sie anderen Konten, die Zugriff auf den Storage-Bucket benötigen, Cloud Storage-Rollen. Beachten Sie, dass jedes Konto mit allen Berechtigungen in der Rolle „Storage-Administrator“ Speicher-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 der Berechtigung „Storage-Objekt-Betrachter“ für den Bucket für gcr.io/my-project Images 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, um den Zugriff zu steuern. Diese Rollen ermöglichen eine klare Trennung zwischen Administrator- und Repository-Nutzerrollen.

Cloud Build hat Berechtigungen in der Rolle "Artifact Registry-Autor", da es nur Images mit Standard-Repositories in der Domain pkg.dev hoch- und herunterladen muss.

Nur Konten, mit denen Repositories verwaltet werden, 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 und Tags hinzufügen oder aktualisieren.
Repository-Administrator für Artifact Registry: Artifact Registry-Schreibberechtigungen und -Berechtigungen zum Löschen von Artefakten und Tags.
Artifact Registry-Administrator: Berechtigungen von Artifact Registry-Repository-Administratoren 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 für us-central1-docker.pkg.dev/my-project/team1 gewähren
Team 2 Zugriff 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.

Images erstellen und per Push übertragen

Wichtige Fakten:

Sie müssen ein Artifact Registry-Docker-Repository erstellen, bevor Sie ein Image dorthin hochladen.
Die Artifact Registry-Hostnamen unterscheiden sich von den Container Registry-Hostnamen.

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

Mit Container Registry kann Cloud Build ein Image erfolgreich auf einen Registry-Host übertragen, der im Google Cloud-Projekt noch nicht vorhanden ist. Bei dieser ersten Image-Übertragung hat Cloud Build die Berechtigungen, den Registry-Host automatisch dem Projekt hinzuzufügen.

So passen Sie einen Container Registry-Workflow an:

Richten Sie Ihre Repositories ein, bevor Sie Images dorthin übertragen.
Aktualisieren Sie die Image-Pfade in der Build-Konfigurationsdatei oder in gcloud builds submit-Befehlen.

Mit einer Build-Konfigurationsdatei erstellen

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

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'

Anschließend können Sie 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 erstellen, durch den Pfad zu einem vorhandenen Artifact Registry-Repository.

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-project/my-repo/my-image:tag1

Images bereitstellen

Wichtig:

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

Aktualisieren Sie die Image-Pfade in der Bereitstellungskonfiguration und in den Bereitstellungsbefehlen, um einen Container Registry-Workflow anzupassen. Die folgenden Abschnitte enthalten Beispiele für Cloud Build, Cloud Run und GKE. Dieser 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 bereitstellen, durch den Pfad zu einem vorhandenen Artifact Registry-Repository.

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 bereitstellen, durch den Pfad zu einem vorhandenen Artifact Registry-Repository.

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 erstellen, durch den Pfad zu einem vorhandenen Artifact Registry-Repository.

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 Bereitstellungsmanifest 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