Modifiche per la creazione e il deployment in Google Cloud

Questo documento illustra le differenze tra Container Registry e Artifact Registry durante la creazione di immagini container con Cloud Build e il loro deployment in ambienti di runtime Google Cloud come Cloud Run o Google Kubernetes Engine.

In questa guida, i confronti sono incentrati su repository Artifact Registry standard, repository Artifact Registry regolari indipendenti da Container Registry e che supportano tutte le funzionalità di Artifact Registry. Se l'amministratore configura repository con supporto per i domini gcr.io, le richieste a gcr.io nomi host vengono reindirizzate automaticamente a un repository di Artifact Registry corrispondente e gli account di servizio predefiniti che hanno accesso a Container Registry dispongono di autorizzazioni predefinite equivalenti per Artifact Registry.

Per scoprire le differenze tra Container Registry e Artifact Registry utilizzando un client Docker, consulta Modifiche al push e al pull con Docker.

Utilizza queste informazioni per adattare i comandi, la configurazione o la documentazione esistenti incentrati su Container Registry con Cloud Build.

Prima di iniziare

Questo documento presuppone che tu abbia:

1. Abilitare Artifact Registry nel tuo progetto.
2. Abilitare l'API Cloud Build e l'API per qualsiasi altro servizio Google Cloud che utilizzi con Artifact Registry.

Modifiche al flusso di lavoro

Quando utilizzi Cloud Build con Container Registry all'interno dello stesso progetto, il flusso di lavoro è simile al seguente:

1. Crea, tagga ed esegui il push di un'immagine nel repository con Cloud Build, utilizzando un Dockerfile o un file di configurazione della build.

   L'esempio seguente crea l'immagine my-image, la tagga con tag1 e la invia all'host gcr.io nel progetto my-project:

   gcloud builds submit --tag gcr.io/my-project/my-image:tag1
   

2. Gli ambienti di runtime di Google Cloud, come Cloud Run e Google Kubernetes Engine, eseguono il pull delle immagini dal registro.

   Ad esempio, questo comando esegue il deployment in Cloud Run dell'immagine del passaggio precedente come my-service.

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

Il flusso di lavoro di Container Registry combina le responsabilità dell'amministratore con la creazione e il deployment.

• Quando abiliti alcune API Google Cloud, l'API Container Registry viene abilitata automaticamente. Ciò significa che gli utenti di questi servizi hanno accesso implicito a Container Registry nello stesso progetto. Ad esempio, gli utenti che possono eseguire build in Cloud Build possono eseguire il push delle immagini ai registri e aggiungere host del registro per impostazione predefinita.
• L'account di servizio Cloud Build dispone delle autorizzazioni per creare bucket di archiviazione Cloud Storage. Ciò significa che l'account può aggiungere automaticamente host Container Registry a un progetto la prima volta che esegue il push di un'immagine all'host. Significa inoltre che l'account può creare, leggere e scrivere nei bucket di archiviazione dell'intero progetto, inclusi i bucket non utilizzati da Container Registry.

In Artifact Registry, esiste una chiara separazione dei ruoli di amministratore e di creazione che modificano i passaggi nel flusso di lavoro di creazione e deployment. Per adattare il flusso di lavoro di Container Registry ad Artifact Registry, apporta le seguenti modifiche. Ogni passaggio rimanda a ulteriori informazioni sulla modifica del flusso di lavoro.

1. Nuova: abilita l'API Artifact Registry.

   Devi abilitare l'API Artifact Registry. Cloud Build e gli ambienti di runtime come Cloud Run e GKE non abilitano automaticamente l'API.

2. Nuovo: se non esiste già, crea il repository Docker di destinazione. Devi creare un repository prima di potervi inviare qualsiasi immagine. Il push di un'immagine non può attivare la creazione di un repository e l'account di servizio Cloud Build non dispone delle autorizzazioni per creare repository.

3. Modificato: crea, tagga ed esegui il push di un'immagine nel repository con Cloud Build, utilizzando un Dockerfile o un file di configurazione della build.

   Il comando di esempio seguente è uguale all'esempio di Container Registry, ma utilizza un percorso del repository Artifact Registry per l'immagine.

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

4. Modificato: esegui il deployment dell'immagine in un ambiente di runtime di Google Cloud, come Cloud Run o GKE.

   Il comando di esempio seguente è uguale all'esempio di Container Registry, ma utilizza il percorso del repository di Artifact Registry per l'immagine.

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

Inoltre, Artifact Registry utilizza ruoli diversi rispetto a Container Registry per controllare l'accesso alle immagini. Devi configurare le autorizzazioni nelle seguenti situazioni:

• Gli ambienti di runtime Cloud Build o Google Cloud si trovano in un progetto diverso da Artifact Registry.
• Utilizzi gli account di servizio personalizzati per i servizi Google Cloud come Cloud Build o GKE, invece degli account di servizio predefiniti.
• Hai concesso le autorizzazioni ad altri account utente o di servizio.

Attivazione dell'API

Punti chiave:

• Devi abilitare l'API Artifact Registry oltre all'API per altri servizi Google Cloud come Cloud Build, Cloud Run e GKE.

Il confronto seguente descrive l'abilitazione dell'API per ciascun servizio:

Container Registry

Quando abiliti le seguenti API Google Cloud, viene abilitata automaticamente anche l'API Container Registry:

• Ambiente flessibile di App Engine
• Cloud Build
• Cloud Functions
• Cloud Run
• Container Scanning o On-Demand Scanning in Artifact Analysis
• Google Kubernetes Engine

Con le autorizzazioni predefinite, gli utenti che possono eseguire build in Cloud Build, scansionare container con Artifact Analysis o eseguire il deployment di container nei runtime di Google Cloud hanno implicitamente accesso alle immagini in Container Registry quando il registro si trova nello stesso progetto.

Artifact Registry

Devi abilitare l'API Artifact Registry. Servizi come Cloud Build, Cloud Run e GKE non abilitano automaticamente l'API Artifact Registry.

Puoi abilitare più API nello stesso progetto utilizzando gcloud. Ad esempio, per abilitare l'API Cloud Build e l'API Artifact Registry, esegui questo comando:

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

Aggiunta di registry e repository

Punti chiave:

• Devi creare un repository Docker di Artifact Registry prima di eseguirne il push.
• Container Registry archivia tutte le immagini in un'unica località a più regioni nello stesso bucket di archiviazione. In Artifact Registry, puoi creare più repository nella stessa regione o in più regioni con criteri di accesso separati.

Il confronto seguente descrive la configurazione dei repository in ciascun servizio:

Container Registry

In Container Registry puoi aggiungere fino a quattro host del registro al tuo progetto. Per aggiungere un host del Registro di sistema, esegui il push della prima immagine.

1. Per aggiungere un registro, come gcr.io, al tuo progetto, un account con il ruolo Amministratore archiviazione a livello di progetto esegue il push di un'immagine iniziale.

   Ad esempio, se l'host gcr.io non esiste nel progetto my-project, il push dell'immagine gcr.io/my-project/my-image:1.0 attiva i seguenti passaggi:

   1. Aggiungi l'host gcr.io al progetto
   2. Crea un bucket di archiviazione per gcr.io nel progetto.
   3. Archivia l'immagine come gcr.io/my-project/my-image:1.0

2. Dopo questo push iniziale, puoi concedere autorizzazioni al bucket di archiviazione ad altri utenti.

Per impostazione predefinita, Cloud Build dispone delle autorizzazioni necessarie per creare un bucket di archiviazione, pertanto il push iniziale dell'immagine e quelli successivi non sono distinguibili.

All'interno di un progetto, un host del registry archivia tutte le immagini nello stesso bucket di archiviazione. Nell'esempio seguente, il progetto my-project ha due immagini chiamate web-app nel registro gcr.io. Uno è direttamente sotto l'ID progetto my-project. L'altra immagine si trova nel repository team1.

gcr.io/my-project/web-app
gcr.io/my-project/team1/web-app

Artifact Registry

Cloud Build non dispone delle autorizzazioni per creare un repository standard nel dominio pkg.dev di Artifact Registry.

Un account con il ruolo Amministratore repository Artifact Registry deve creare il repository prima di eseguire il push delle immagini. Puoi quindi concedere autorizzazioni al repository ad altri utenti.

In Artifact Registry, ogni repository è una risorsa separata. Di conseguenza, tutti i percorsi delle immagini devono includere un repository.

Percorsi immagine validi:

us-central1-docker.pkg.dev/my-project/team1/web-app:1.0
us-central1-docker.pkg.dev/my-project/team2/web-app:1.0

Percorso immagine non valido (non è incluso un repository) :

us-central1-docker.pkg.dev/my-project/web-app:1.0

I seguenti esempi mostrano situazioni in cui il push di un'immagine in un repository mancante ha esito negativo.

• Push di un'immagine a us-central1-docker.pkg.dev/my-project/team1 se us-central1-docker.pkg.dev/my-project/team1 non esiste.
• Push di un'immagine a us-central1-docker.pkg.dev/my-project/team2 quando esiste us-central1-docker.pkg.dev/my-project/team1, ma us-central1-docker.pkg.dev/my-project/team2 non esiste.

Concessione di autorizzazioni

Punti chiave:

• I servizi Google Cloud hanno un accesso in lettura o scrittura equivalente sia a Container Registry che ad Artifact Registry. Tuttavia, l'account di servizio Cloud Build predefinito non può creare repository standard sul dominio pkg.dev.
• Concedi i ruoli Artifact Registry appropriati ad altri account che accedono ad Artifact Registry.
• Container Registry supporta il controllo dell'accesso a livello di bucket di archiviazione. Artifact Registry supporta il controllo dell'accesso a livello di repository.

Il confronto seguente descrive le autorizzazioni per ciascun servizio:

Container Registry

Container Registry utilizza i ruoli Cloud Storage per controllare l'accesso. Cloud Build dispone delle autorizzazioni necessarie nel ruolo Amministratore archiviazione per aggiungere host Container Registry a un progetto.

Visualizzatore oggetti Storage a livello di bucket di archiviazione

Esegui il pull (lettura) delle immagini dagli host del registro esistenti nel progetto.

Writer bucket legacy Storage a livello di bucket di archiviazione

Esegui il push (scrittura) e il pull (lettura) delle immagini per gli host del registro esistenti nel progetto.

Amministratore Storage a livello di progetto

Aggiungi un host del registro a un progetto eseguendo il push di un'immagine iniziale all'host.

Dopo il push iniziale dell'immagine a un registro, concedi i ruoli Cloud Storage ad altri account che richiedono l'accesso al bucket di archiviazione. Tieni presente che qualsiasi account con tutte le autorizzazioni nel ruolo Amministratore Storage può leggere, scrivere ed eliminare bucket e oggetti di archiviazione nell'intero progetto.

Le autorizzazioni su un bucket di archiviazione si applicano a tutti i repository nel registro. Ad esempio, qualsiasi utente con autorizzazioni Visualizzatore oggetti Storage nel bucket per gcr.io/my-project può leggere le immagini in tutti questi repository:

gcr.io/my-project/team1
gcr.io/my-project/team2
gcr.io/my-project/test
gcr.io/my-project/production

Artifact Registry

Artifact Registry ha i propri ruoli per controllare l'accesso. Questi ruoli forniscono una chiara separazione tra i ruoli utente di amministratore e di repository.

Cloud Build dispone delle autorizzazioni per il ruolo Writer Artifact Registry, in quanto deve solo eseguire il push e il pull di immagini con repository standard sul dominio pkg.dev.

Solo gli account che gestiscono i repository devono avere il ruolo Amministratore repository Artifact Registry o Amministratore Artifact Registry.

Lettore Artifact Registry

Elenca artefatti e repository. Scarica gli elementi.

Writer Artifact Registry

Elenca artefatti e repository. Scarica gli artefatti, carica nuove versioni degli elementi e aggiungi o aggiorna i tag.

Amministratore repository Artifact Registry

Autorizzazioni e autorizzazioni di Writer di Artifact Registry per eliminare artefatti e tag.

Amministratore Artifact Registry

Autorizzazioni e autorizzazioni di Amministratore repository di Artifact Registry per creare, aggiornare, eliminare e concedere autorizzazioni ai repository.

Puoi applicare queste autorizzazioni a livello di repository. Ad esempio:

• Concedi l'accesso al Team 1 per us-central1-docker.pkg.dev/my-project/team1
• Concedi l'accesso al Team 2 a us-central1-docker.pkg.dev/my-project/team2.

Per maggiori dettagli sulla concessione delle autorizzazioni ad Artifact Registry, consulta la documentazione sul controllo dell'accesso.

Creazione e push delle immagini

Punti chiave:

• Devi creare un repository Docker di Artifact Registry prima di eseguirne il push.
• I nomi host di Artifact Registry sono diversi dai nomi host di Container Registry.

Cloud Build può creare, taggare ed eseguire il push di un'immagine in un solo passaggio.

Con Container Registry, Cloud Build può eseguire correttamente il push di un'immagine in un host del registro che non esiste ancora nel progetto Google Cloud. Per questo push iniziale dell'immagine, Cloud Build dispone delle autorizzazioni per aggiungere automaticamente l'host del registro al progetto.

Per adattare un flusso di lavoro di Container Registry:

1. Configura i repository prima di eseguirne il push.
2. Aggiorna i percorsi delle immagini nel file di configurazione o nella build o nei comandi gcloud builds submit.

Creazione con un file di configurazione della build

Sostituisci i percorsi di Container Registry per le immagini create con il percorso a un repository Artifact Registry esistente.

Il seguente file cloudbuild.yaml di esempio crea l'immagine us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1:

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'

Puoi quindi creare l'immagine con il comando:

gcloud builds submit --config cloudbuild.yaml

Creazione con un Dockerfile

Sostituisci i percorsi di Container Registry per le immagini create con il percorso a un repository Artifact Registry esistente.

Il comando di esempio seguente crea l'immagine us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1 con Dockerfile nella directory attuale:

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

Deployment delle immagini

Punto chiave:

• I nomi host di Artifact Registry sono diversi dai nomi host di Container Registry.

Per adattare un flusso di lavoro di Container Registry, aggiorna i percorsi delle immagini nella configurazione e nei comandi di deployment. Le seguenti sezioni mostrano esempi per Cloud Build, Cloud Run e GKE, ma lo stesso approccio si applica a qualsiasi altro servizio Google Cloud che esegue il deployment delle immagini.

Cloud Build

Sostituisci i percorsi di Container Registry per le immagini di cui esegui il deployment con il percorso di un repository Artifact Registry esistente.

Il seguente file cloudbuild.yaml di esempio esegue il deployment dell'immagine di esempio us-docker.pkg.dev/cloudrun/container/hello.

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

Sostituisci i percorsi di Container Registry per le immagini di cui esegui il deployment con il percorso di un repository Artifact Registry esistente.

Ad esempio, questo comando esegue il deployment dell'immagine di esempio us-docker.pkg.dev/cloudrun/container/hello.

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

GKE

Sostituisci i percorsi di Container Registry per le immagini create con il percorso a un repository Artifact Registry esistente.

I seguenti esempi per Artifact Registry utilizzano l'immagine di esempio us-docker.pkg.dev/artifact-registry-samples/containers/gke/hello-app:1.0.

Creazione di un cluster dalla riga di comando:

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

Specifica di un'immagine in un manifest del deployment:

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