Questo documento illustra le differenze tra Container Registry e Artifact Registry per l'autenticazione, il push e il pull delle immagini container con Docker.
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 ha configurato
repository con supporto per il dominio gcr.io, le richieste
a gcr.io
nomi host vengono reindirizzate automaticamente a un repository
Artifact Registry corrispondente. Per utilizzare un repository gcr.io ospitato su
Artifact Registry, devi avere un
ruolo Artifact Registry appropriato o un ruolo con
autorizzazioni equivalenti.
Per scoprire le differenze tra Container Registry e Artifact Registry durante la creazione con Cloud Build e il deployment in 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:
- Abilitare Artifact Registry nel tuo progetto.
- 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
|
Amministratore
|
Utenti del registro
|
Utenti del registro
|
Tuttavia, una scorciatoia per Container Registry combina i ruoli utente e amministratore in un unico flusso di lavoro. Questa scorciatoia è comune in:
- Guide rapide e tutorial in cui stai eseguendo test in un ambiente in cui disponi di ampie autorizzazioni.
- Workflows che utilizzano Cloud Build, poiché l'account di servizio Cloud Build dispone delle autorizzazioni per aggiungere un host di registro nello stesso progetto Google Cloud.
Il flusso di lavoro della scorciatoia ha il seguente aspetto:
- Abilitare l'API Container Registry.
- Concedi le autorizzazioni all'account che accederà a Container Registry.
Esegui l'autenticazione nel registro. L'opzione di autenticazione più semplice consiste nell'utilizzare l'helper per le credenziali Docker in Google Cloud CLI. Si tratta di un passaggio di configurazione da eseguire una sola volta.
gcloud auth configure-docker
Crea e tagga l'immagine. Ad esempio, questo comando crea e tagga l'immagine
gcr.io/my-project/my-image:tag1
:docker build -t gcr.io/my-project/my-image:tag1
Esegui il push dell'immagine al registro. Ad esempio:
docker push gcr.io/my-project/my-image:tag1
Se l'host del Registro di sistema
gcr.io
non esiste nel progetto, Container Registry aggiunge l'host prima di caricare l'immagine.Esegui il pull dell'immagine dal registro o 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 esegue il push delle immagini dispone del ruolo Amministratore Storage o di un ruolo con le stesse autorizzazioni, ad esempio Proprietario. Le ampie autorizzazioni di questo ruolo consentono l'accesso in lettura e scrittura a tutti i bucket di archiviazione di un progetto, inclusi i bucket non utilizzati da Container Registry.
- 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.
In Artifact Registry, è presente una chiara separazione dei ruoli utente di amministratore e di repository che modificano i passaggi nel flusso di lavoro di creazione e deployment. Per adattare il flusso di lavoro di Container Registry per Artifact Registry, apporta le modifiche seguenti. Ogni passaggio rimanda a ulteriori informazioni sulla modifica del flusso di lavoro.
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.
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.
Concedi le autorizzazioni all'account che interagirà con Artifact Registry.
Modificato: esegui l'autenticazione nel repository. Se utilizzi l'helper credenziali in gcloud CLI, devi specificare gli host che vuoi 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
Modificata: crea e tagga l'immagine.
Il comando di esempio seguente è uguale all'esempio 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
Modificata: 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
Modificato: esegui il pull dell'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 confronto seguente descrive l'abilitazione 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 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 prima di utilizzare i client Docker o altri servizi Google Cloud con 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.
Un passaggio di creazione del Registro di sistema è spesso escluso nella documentazione che descrive il push delle immagini in Container Registry perché un account con autorizzazioni di Amministratore Storage può aggiungere un registro a un progetto con il push iniziale all'host del Registro di sistema.
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.
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 progettomy-project
, il push dell'immaginegcr.io/my-project/my-image:1.0
attiva i seguenti passaggi:- Aggiungi l'host
gcr.io
al progetto - Crea un bucket di archiviazione per
gcr.io
nel progetto. - Archivia l'immagine come
gcr.io/my-project/my-image:1.0
- Aggiungi l'host
Dopo questo push iniziale, puoi concedere autorizzazioni al bucket di archiviazione ad altri utenti.
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
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
seus-central1-docker.pkg.dev/my-project/team1
non esiste. - Push di un'immagine a
us-central1-docker.pkg.dev/my-project/team2
quando esisteus-central1-docker.pkg.dev/my-project/team1
, maus-central1-docker.pkg.dev/my-project/team2
non esiste.
Concessione di autorizzazioni
Punti chiave:
- Concedi il ruolo Artifact Registry appropriato all'account che stai utilizzando con Artifact Registry.
- 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.
- 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 la configurazione delle autorizzazioni in ciascun 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 (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.
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.
Autenticazione nel registro
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 mediante
docker login
, utilizza l'host Artifact Registry anziché un host Container Registry.
Utilizzo dell'helper per le credenziali
Il comando gcloud auth configure-docker
e l'helper autonomo delle credenziali configurano Docker solo per i nomi host *.gcr.io
per impostazione predefinita. Per Artifact Registry, devi specificare un elenco di host Artifact Registry che vuoi aggiungere alla configurazione del client Docker.
Ad esempio, per configurare l'autenticazione nei repository Docker nella regione us-central1
, esegui questo 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 di nuovo il comando per aggiungere i nomi host regionali corrispondenti alla configurazione 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 Configurare l'autenticazione per Docker.
Utilizzo dell'autenticazione tramite 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 nell'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 tagghi un'immagine, utilizza il percorso Artifact Registry anziché il percorso Container Registry. Ad esempio:
docker tag my-image us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0
Push delle immagini al registro
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 Artifact Registry anziché il percorso Container Registry. Ad esempio:
docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0
Pull delle immagini dal registro
Punto chiave:
- I nomi host di Artifact Registry sono diversi dai nomi host di Container Registry.
Quando esegui il pull di un'immagine, utilizza il percorso Artifact Registry anziché il percorso 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 Deployment delle immagini.