Modifiche per Docker

Questo documento illustra le differenze tra Container Registry e Artifact Registry per l'autenticazione, il push e il pull delle immagini dei container con Docker.

In questa guida, i confronti si concentrano sui pkg.devrepository di Artifact Registry, ovvero repository di Artifact Registry regolari indipendenti da Container Registry e che supportano tutte le funzionalità di Artifact Registry.

Se l'amministratore ha configurato repository con supporto per il dominio gcr.io, le richieste ai nomi host gcr.io vengono reindirizzate automaticamente a un corrispondente repository Artifact Registry. Per utilizzare un repository gcr.io ospitato su Artifact Registry, devi disporre di un ruolo Artifact Registry appropriato o di un ruolo con autorizzazioni equivalenti.

Per scoprire le differenze tra Container Registry e Artifact Registry durante la compilazione con Cloud Build e il deployment su Cloud Run o Google Kubernetes Engine, consulta Modifiche per Cloud Build, Cloud Run e GKE.

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

Prima di iniziare

Questo documento presuppone che tu abbia:

1. Abilita Artifact Registry nel progetto.
2. Docker installato. Docker è incluso in Cloud Shell.

Panoramica

A livello generale, il flusso di lavoro per l'utilizzo di Docker con Container Registry o Artifact Registry è lo stesso.

Container Registry	Artifact Registry
Amministratore Abilita l'API Container Registry Aggiungi un host del registry, ad esempio "gcr.io", eseguendo il push di un'immagine iniziale sull'host. Concedi i ruoli Cloud Storage al bucket di archiviazione per consentire all'host del registry di fornire l'accesso alle immagini.	Amministratore Abilita l'API Artifact Registry Aggiungi un repository Docker. Concedi i ruoli Artifact Registry per fornire l'accesso alle immagini.
Utenti del registry Definisci l'immagine come file Dockerfile. Crea l'immagine. Esegui l'autenticazione nel registry. Tagga e esegui il push dell'immagine nel registry. Estrai l'immagine dal registry o esegui il deployment in un runtime Google Cloud.	Utenti del registry Definisci l'immagine come file Dockerfile. Crea l'immagine. Esegui l'autenticazione nel registry. Tagga e esegui il push dell'immagine nel registry. Estrai l'immagine dal registry o esegui il deployment in un runtime Google Cloud.

Tuttavia, una scorciatoia per Container Registry è la combinazione dei ruoli di amministratore e utente in un unico flusso di lavoro. Questa scorciatoia è comune in:

• Guide di avvio rapido e tutorial in cui esegui test in un ambiente in cui hai autorizzazioni ampie.
• Workflows che utilizzano Cloud Build, poiché l'account di servizio Cloud Build ha le autorizzazioni per aggiungere un host del registry nello stesso progetto Google Cloud.

Il flusso di lavoro delle scorciatoie è il seguente:

1. Abilita l'API Container Registry.
2. Concedi le autorizzazioni all'account che accederà a Container Registry.

3. Esegui l'autenticazione nel registry. L'opzione di autenticazione più semplice è utilizzare lo strumento di assistenza per le credenziali Docker in Google Cloud CLI. Si tratta di un passaggio di configurazione da eseguire una sola volta.

   gcloud auth configure-docker
   

4. Crea e tagga l'immagine. Ad esempio, questo comando crea e tagga l'immaginegcr.io/my-project/my-image:tag1:

   docker build -t gcr.io/my-project/my-image:tag1
   

5. Esegui il push dell'immagine nel registry. Ad esempio:

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

   Se l'host del registry gcr.io non esiste nel progetto, Container Registry aggiunge l'host prima di caricare l'immagine.

6. Estrai l'immagine dal registry o eseguine il deployment in un runtime Google Cloud. Ad esempio:

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

Questo flusso di lavoro si basa sulle seguenti scorciatoie:

• L'account che carica le immagini dispone del ruolo Amministratore dello spazio di archiviazione o di un ruolo con le stesse autorizzazioni, ad esempio Proprietario. Le autorizzazioni ampie di questo ruolo consentono accesso in lettura e scrittura per tutti i bucket di archiviazione di un progetto, inclusi i bucket non utilizzati da Container Registry.
• Quando attivi alcune API Google Cloud, l'API Container Registry viene attivata 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 nei registry e aggiungere gli host dei registry per impostazione predefinita.

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

1. Novità: 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 per te.

2. Novità: crea il repository Docker di destinazione se non esiste già. Devi creare un repository prima di poter eseguire il push delle immagini. 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. Concedi le autorizzazioni all'account che interagirà con Artifact Registry.

4. Modifica: esegui l'autenticazione nel repository. Se utilizzi lo script di utilità per le credenziali in gcloud CLI, devi specificare gli host da aggiungere alla configurazione del client Docker. Ad esempio, questo comando aggiunge l'host us-central1-docker.pkg.dev:

   gcloud auth configure-docker us-central1-docker.pkg.dev
   

5. Modifica: crea e tagga l'immagine.

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

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

6. Modifica: esegui il push dell'immagine nel repository utilizzando il percorso di Artifact Registry. Ad esempio:

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

7. Modifica: estrae l'immagine dal repository utilizzando il percorso di Artifact Registry. Ad esempio:

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

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 seguente confronto descrive l'attivazione dell'API per ciascun servizio:

Container Registry

Devi abilitare l'API Container Registry prima di utilizzare Docker o altri client di terze parti con Container Registry.

Quando attivi le seguenti API Google Cloud, viene attivata automaticamente anche l'API Container Registry:

• Ambiente flessibile di App Engine
• Cloud Build
• Funzioni Cloud Run
• Cloud Run
• Scansione dei contenitori o analisi on demand in Artifact Analysis
• Google Kubernetes Engine

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

Artifact Registry

Devi abilitare l'API Artifact Registry prima di utilizzare i client Docker o altri servizi Google Cloud con Artifact Registry.

Servizi come Cloud Build, Cloud Run e GKE non attivano 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 il 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 eseguire il push di un'immagine.

  Un passaggio di creazione del registry viene spesso escluso nella documentazione che descrive il push delle immagini in Container Registry perché un account con autorizzazioni di amministratore dello spazio di archiviazione può aggiungere un registry a un progetto con il push iniziale all'host del registry.

• Container Registry archivia tutte le immagini in un'unica multiregione nello stesso bucket di archiviazione. In Artifact Registry, puoi creare più repository nella stessa regione o in più regioni con criteri di accesso distinti.

Il seguente confronto descrive la configurazione del repository in ogni servizio:

Container Registry

In Container Registry puoi aggiungere fino a quattro host del registry al tuo progetto. Aggiungi un host del registry eseguendo il push della prima immagine.

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

   Ad esempio, se l'host gcr.io non esiste nel progettomy-project, l'invio 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. Memorizza l'immagine come gcr.io/my-project/my-image:1.0

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

All'interno di un progetto, un host del registry archivia tutte le immagini nello stesso bucket di archiviazione. Nel seguente esempio, il progetto my-project ha due immagini chiamate web-app nel registry gcr.io. Uno si trova 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

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

In Artifact Registry ogni repository è una risorsa separata. Pertanto, 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 include un repository) :

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

Gli esempi riportati di seguito mostrano situazioni in cui l'invio di un'immagine a un repository mancante non va a buon fine.

• Eseguire il push di un'immagine in us-central1-docker.pkg.dev/my-project/team1 se us-central1-docker.pkg.dev/my-project/team1 non esiste.
• Caricamento di un'immagine in us-central1-docker.pkg.dev/my-project/team2 quando esiste us-central1-docker.pkg.dev/my-project/team1, ma non esiste us-central1-docker.pkg.dev/my-project/team2.

Concessione di autorizzazioni

Punti chiave:

• Concedi il ruolo Artifact Registry appropriato all'account che stai utilizzando con Artifact Registry.
• I servizi Google Cloud hanno accesso in lettura o scrittura equivalente sia a Container Registry sia ad Artifact Registry. Tuttavia, l'account di servizio Cloud Build predefinito non può creare repository.
• 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 seguente confronto descrive la configurazione delle autorizzazioni in ogni servizio:

Container Registry

Container Registry utilizza i ruoli Cloud Storage per controllare l'accesso.

Visualizzatore oggetti Storage a livello di bucket di archiviazione

Esegui il pull (leggi) delle immagini dagli host del registry esistenti nel progetto.

Storage Legacy Bucket Writer a livello di bucket di archiviazione

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

Amministratore archiviazione a livello di progetto

Aggiungi un host del registry a un progetto eseguendo il push di un'immagine iniziale sull'host.

Dopo il push iniziale dell'immagine in un registry, 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 registry. Ad esempio, qualsiasi utente con autorizzazioni di Visualizzatore oggetti Storage per il 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 del repository.

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

Artifact Registry Reader

Elenca gli elementi e i repository. Scarica gli elementi.

Artifact Registry Writer

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

Artifact Registry Repository Administrator

Autorizzazioni di autore di Artifact Registry e autorizzazioni per eliminare elementi e tag.

Artifact Registry Administrator

Autorizzazioni e autorizzazioni di amministratore del repository 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 per us-central1-docker.pkg.dev/my-project/team2.

Per informazioni dettagliate sulla concessione delle autorizzazioni di Artifact Registry, consulta la documentazione sul controllo dell'accesso.

Autenticazione nel registry

Punti chiave:

• Artifact Registry supporta gli stessi metodi di autenticazione di Container Registry.
• Per l'helper delle credenziali Docker, devi specificare gli host da aggiungere alla configurazione del client Docker.
• Per l'autenticazione tramite docker login, utilizza l'host Artifact Registry instead of an Container Registry host.

Utilizzo dell'utilità di supporto delle credenziali

Il comando gcloud auth configure-docker e l'helper per le credenziali autonomo configurano Docker solo per i nomi host *.gcr.io per impostazione predefinita. Per Artifact Registry, devi specificare un elenco degli host di Artifact Registry da aggiungere alla configurazione del client Docker.

Ad esempio, per configurare l'autenticazione nei repository Docker della regione us-central1, esegui il seguente comando:

gcloud auth configure-docker us-central1-docker.pkg.dev

Se in un secondo momento aggiungi repository in us-east1 e asia-east1, devi eseguire nuovamente il comando per aggiungere i nomi host regionali corrispondenti alla configurazione di Docker.

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

Per informazioni dettagliate sui metodi di autenticazione di Artifact Registry, consulta Configurazione dell'autenticazione per Docker.

Utilizzo dell'autenticazione con password

Quando accedi a Docker, utilizza il nome host di Artifact Registry anziché un nome host *.gcr.io. L'esempio seguente mostra l'autenticazione con una chiave dell'account di servizio codificata in base64 all'host us-central1-docker.pkg.dev:

cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-central1-docker.pkg.dev

Creazione e tagging delle immagini

Punti chiave: - Artifact Registry utilizza un nome host diverso per i repository.

Quando contrassegna un'immagine, utilizza il percorso di Artifact Registry anziché il percorso di Container Registry. Ad esempio:

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

Eseguire il push delle immagini nel registry

Punti chiave: - In Artifact Registry, il repository di destinazione deve esistere prima di eseguire il push di un'immagine. - Artifact Registry utilizza un nome host diverso per i repository.

Quando esegui il push di un'immagine, utilizza il percorso di Artifact Registry anziché il percorso di Container Registry. Ad esempio:

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

Estrazione delle immagini dal registry

Punto chiave:

• I nomi host di Artifact Registry sono diversi da quelli di Container Registry.

Quando esamini un'immagine, utilizza il percorso di Artifact Registry anziché il percorso di Container Registry. Ad esempio:

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

Per esempi di deployment di immagini nei runtime di Google Cloud come Cloud Run e GKE, consulta Eseguire il deployment di immagini.