Transizione ai repository standard

Se utilizzi Container Registry per gestire le immagini container, questa pagina spiega come configurare un repository pkg.dev Artifact Registry e in che modo l'utilizzo dei repository differisce dall'utilizzo di Container Registry.

Queste istruzioni sono rivolte principalmente agli amministratori dei repository. Per scoprire come è cambiata la creazione, il push, il pull e il deployment delle immagini, consulta le seguenti informazioni:

• Modifiche alla creazione e al deployment in Google Cloud
• Modifiche al push e al pull con Docker

Prima di iniziare

1. Abilita l'API Artifact Registry dalla consoleGoogle Cloud o con il comando:

   gcloud services enable artifactregistry.googleapis.com
   

2. Installa gcloud CLI se non è già installata. Per un'installazione esistente, esegui il seguente comando per aggiornare i componenti alle versioni più recenti:

   gcloud components update
   

3. Scopri di più sui prezzi di Artifact Registry prima di iniziare la transizione.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare i repository gcr.io, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto Google Cloud :

• Per creare repository Artifact Registry e concedere l'accesso a singoli repository: Artifact Registry Administrator (roles/artifactregistry.admin)
• Per visualizzare e gestire la configurazione di Container Registry esistente applicata ai bucket di archiviazione Cloud Storage: Amministratore spazio di archiviazione (roles/storage.admin)
• Per concedere l'accesso al repository a livello di progetto: Amministratore IAM progetto (roles/resourcemanager.projectIamAdmin) o un ruolo che include autorizzazioni equivalenti, ad esempio Amministratore cartelle (roles/resourcemanager.folderAdmin) o Amministratore organizzazione (roles/resourcemanager.organizationAdmin)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Panoramica

I repository pkg.dev sono repository Artifact Registry regolari che supportano tutte le funzionalità.

Per semplicità, le istruzioni riportate in questa pagina presuppongono che sia Container Registry sia Artifact Registry si trovino nello stesso progetto Google Cloud . Puoi continuare a utilizzare entrambi i servizi durante la transizione ad Artifact Registry in modo da eseguire gradualmente i passaggi di configurazione e aggiornare l'automazione. Se necessario, puoi configurare Artifact Registry in un progetto separato ed eseguire gli stessi passaggi generali.

Artifact Registry offre anche repository gcr.io. Questi repository possono reindirizzare il traffico gcr.io dai tuoi registri esistenti ai repository Artifact Registry corrispondenti. Offrono una certa compatibilità con le versioni precedenti di Container Registry, ma presentano anche alcune limitazioni delle funzionalità. Tuttavia, se hai molte configurazioni di strumenti, script o codice con riferimenti gcr.io, potrebbe essere necessario un approccio più tattico per la transizione ad Artifact Registry. Consulta la documentazione di transizione per i repository con supporto per il dominio gcr.io per prendere una decisione appropriata.

Passaggi per la transizione

Questa guida ti mostrerà come completare i seguenti passaggi:

1. Crea un repository Docker per i tuoi container. Prima di eseguire il push delle immagini, devi creare un repository.
2. Concedi le autorizzazioni al repository.
3. Configura l'autenticazione per connetterti al nuovo repository.
4. Se necessario, copia le immagini da Container Registry che vuoi utilizzare nel nuovo repository.
5. Prova a eseguire il push e il pull dei container.
6. Prova a eseguire il deployment delle immagini in un ambiente di runtime.
7. Configura le funzionalità aggiuntive.
8. Esegui la pulizia delle immagini in Container Registry al termine della transizione.

Creare repository

Container Registry crea automaticamente un bucket di archiviazione in una multi-regione se non hai mai eseguito il push di un'immagine in questa posizione.

In Artifact Registry, devi creare un repository prima di poter caricare le immagini. Quando crei un repository, devi specificare:

• Il formato del repository. Artifact Registry archivia i container nei repository Docker.

• Una posizione regionale o multiregionale per il repository.

  Quando scegli una località per i repository Artifact Registry, considera la vicinanza dei repository alle altre infrastrutture e ai tuoi utenti. Se intendi copiare immagini da Container Registry ad Artifact Registry, le differenze di posizione possono influire sul costo della copia.

• Una chiave Cloud Key Management Service, se utilizzi chiavi di crittografia gestite dal cliente (CMEK) per la crittografia.

  In Container Registry, configura il bucket di archiviazione di Container Registry in modo che utilizzi CMEK. In Artifact Registry, configuri i repository in modo che utilizzino CMEK quando li crei. Per saperne di più sull'utilizzo di CMEK con Artifact Registry, consulta Attivazione delle chiavi di crittografia gestite dal cliente.

Container Registry ospita i container sul dominio gcr.io. Artifact Registry ospita i container sul dominio pkg.dev.

Per informazioni sulla creazione di repository, inclusi quelli che utilizzano CMEK per la crittografia, consulta Creare repository.

Concedi le autorizzazioni

Container Registry utilizza i ruoli Cloud Storage per controllare l'accesso. Artifact Registry ha i propri ruoli IAM e questi ruoli separano i ruoli di lettura, scrittura e amministrazione del repository in modo più chiaro rispetto a Container Registry.

Per mappare rapidamente le autorizzazioni esistenti concesse sui bucket di archiviazione ai ruoli Artifact Registry suggeriti, utilizza lo strumento di mappatura dei ruoli.

In alternativa, puoi visualizzare un elenco di entità con accesso ai bucket di archiviazione utilizzando la console Google Cloud .

1. Nella console Google Cloud , vai alla pagina Bucket in Cloud Storage.
   

   Vai a Bucket

2. Fai clic sul bucket di archiviazione per l'host del registro che vuoi visualizzare. Nei nomi dei bucket, PROJECT-ID è il tuo Google Cloud ID progetto.

   • gcr.io: artifacts.PROJECT-ID.appspot.com
   • asia.gcr.io: asia.artifacts.PROJECT-ID.appspot.com
   • eu.gcr.io: eu.artifacts.PROJECT-ID.appspot.com
   • us.gcr.io: us.artifacts.PROJECT-ID.appspot.com

3. Fai clic sulla scheda Autorizzazioni.

4. Nella scheda Autorizzazioni, fai clic sulla scheda secondaria Visualizza per ruolo.

5. Espandi un ruolo per visualizzare le entità che lo hanno.

L'elenco include i ruoli IAM concessi direttamente sul bucket e i ruoli ereditati dal progetto padre. In base al ruolo, puoi scegliere il ruolo Artifact Registry più appropriato da concedere.

Cloud Storage e ruoli di base

Concedi agli utenti e ai service account che attualmente accedono a Container Registry l'accesso ai repository Artifact Registry. Per i ruoli Cloud Storage ereditati dal progetto padre, devi verificare che il principal utilizzi attualmente Container Registry. Alcuni principal potrebbero accedere solo ad altri bucket Cloud Storage non correlati a Container Registry.

I ruoli di base Proprietario, Editor e Visualizzatore esistenti prima di IAM hanno accesso limitato ai bucket di archiviazione. Non concedono intrinsecamente tutto l'accesso alle risorse Cloud Storage che i loro nomi implicano e forniscono autorizzazioni aggiuntive per altri servizi. Google Cloud Verifica quali utenti e service account richiedono l'accesso ad Artifact Registry e utilizza la tabella di mapping dei ruoli per concedere i ruoli giusti se l'accesso ad Artifact Registry è appropriato.

La seguente tabella mappa i ruoli Artifact Registry in base alle autorizzazioni concesse dai ruoli Cloud Storage predefiniti per l'accesso a Container Registry. I ruoli di Artifact Registry offrono una separazione aggiuntiva delle autorizzazioni non disponibile nei ruoli Cloud Storage predefiniti.

Accesso richiesto	Ruolo attuale	Ruolo Artifact Registry	Dove concedere il ruolo
Estrai solo immagini (sola lettura)	Storage Object Viewer (roles/storage.objectViewer)	Lettore Artifact Registry (roles/artifactregistry.reader)	Repository Artifact Registry o progetto Google Cloud
Esegui il push e il pull delle immagini (lettura e scrittura)	Storage Legacy Bucket Writer (roles/storage.legacyBucketWriter)	Artifact Registry Writer (roles/artifactregistry.writer)	Repository Artifact Registry o progetto Google Cloud
Eseguire il push, il pull e l'eliminazione delle immagini	Storage Legacy Bucket Writer (roles/storage.legacyBucketWriter)	Artifact Registry Repository Administrator (roles/artifactregistry.repoAdmin)	Repository Artifact Registry o progetto Google Cloud
Creare, gestire ed eliminare repository	Amministratore Storage (roles/storage.admin)	Amministratore Artifact Registry (roles/artifactregistry.admin)	Google Cloud project

Ruoli dell'agente di servizio ereditati dal progetto

Gli account di servizio predefiniti per i servizi Google Cloud hanno i propri ruoli concessi a livello di progetto. Ad esempio, l'agente di servizio per Cloud Run ha il ruolo Agente di servizio Cloud Run.

Nella maggior parte dei casi, questi ruoli dell'agente di servizio contengono autorizzazioni predefinite equivalenti per Container Registry e Artifact Registry e non devi apportare modifiche aggiuntive se esegui Artifact Registry nello stesso progetto del servizio Container Registry esistente.

Per informazioni dettagliate sulle autorizzazioni nei ruoli dell'agente di servizio, consulta il riferimento al ruolo dell'agente di servizio.

Ruoli personalizzati

Utilizza la tabella di mapping dei ruoli per decidere quale ruolo concedere agli utenti o ai service account in base al livello di accesso richiesto.

Per istruzioni sulla concessione dei ruoli Artifact Registry, vedi Configurare ruoli e autorizzazioni.

Autenticarsi nel repository

Artifact Registry supporta gli stessi metodi di autenticazione di Container Registry.

Se utilizzi l'helper delle credenziali Docker:

• Per interagire con i repository Artifact Registry, devi utilizzare la versione 2.0 o successive. La versione autonoma è disponibile su GitHub.
• Devi configurare l'helper delle credenziali con le posizioni di Artifact Registry che intendi utilizzare. Per impostazione predefinita, l'helper delle credenziali configura solo l'accesso agli host Container Registry.

Per informazioni dettagliate sulla configurazione dell'autenticazione, vedi Configurazione dell'autenticazione per Docker.

Copia dei container da Container Registry

Se in Container Registry sono presenti container che vuoi continuare a utilizzare in Artifact Registry, hai diverse opzioni per copiarli. Per istruzioni dettagliate, consulta Copia delle immagini da Container Registry

Push e pull delle immagini

I comandi Docker che utilizzi per taggare, eseguire il push e il pull delle immagini in Artifact Registry sono simili a quelli che utilizzi in Container Registry. Esistono due differenze principali:

• Il nome host per i repository Docker di Artifact Registry include un prefisso di località, seguito da -docker.pkg.dev. Gli esempi includono australia-southeast1-docker.pkg.dev, europe-north1-docker.pkg.dev e europe-docker.pkg.dev.
• Poiché Artifact Registry supporta più repository Docker in un unico progetto, devi specificare il nome del repository nei comandi.

Ad esempio, in Container Registry, questo comando esegue il push dell'immagine my-image nel registro eu.gcr.io nel progetto my-project.

docker push eu.gcr.io/my-project/my-image

In Artifact Registry, questo comando esegue il push dell'immagine my-image nel repository regionale europe-north1-docker.pkg.dev nel repository my-repo e nel progetto my-project.

docker push europe-north1-docker.pkg.dev/my-project/my-repo/my-image

Per informazioni dettagliate sul push e sul pull delle immagini in Artifact Registry, consulta Push e pull delle immagini.

Esegui il deployment delle immagini

I service account per le integrazioni comuni Google Cloud sono configurati con le autorizzazioni predefinite per i repository nello stesso progetto.

La creazione di immagini e il loro push in un repository con Cloud Build in genere funziona allo stesso modo di Container Registry. La differenza principale in Artifact Registry è che un repository di destinazione deve esistere prima di poter eseguire il push delle immagini, inclusa la prima immagine.

Assicurati di creare i repository necessari prima di eseguire i comandi che eseguono il push delle immagini, inclusi il comando Docker docker push e il comando Cloud Build gcloud builds submit.

I builder di Cloud Build sono ancora ospitati su gcr.io. Per maggiori informazioni, vedi Integrazione con Cloud Build.

Altre caratteristiche

Questa sezione descrive la configurazione di altre funzionalità che potresti aver configurato in Container Registry.

Artifact Analysis

Artifact Analysis supporta sia Container Registry che Artifact Registry. La documentazione di Artifact Analysis include entrambi i prodotti.

• Entrambi i prodotti utilizzano le stesse API di analisi degli artefatti. Quando abiliti le API Artifact Analysis in Container Registry o Artifact Registry, le API vengono attivate per entrambi i prodotti.
• Entrambi i prodotti utilizzano gli stessi argomenti Pub/Sub per le notifiche di analisi degli artefatti.
• Puoi continuare a utilizzare i comandi gcloud container images per elencare le note e le occorrenze associate ai percorsi delle immagini gcr.io.

Notifiche Pub/Sub

Artifact Registry pubblica le modifiche nello stesso argomento gcr di Container Registry. Non è necessaria alcuna configurazione aggiuntiva se utilizzi già Pub/Sub con Container Registry nello stesso progetto di Artifact Registry.

Se hai configurato Artifact Registry in un progetto separato, l'argomento gcr potrebbe non esistere. Per le istruzioni di configurazione, consulta Configurazione delle notifiche Pub/Sub.

Perimetri di servizio

Con i Controlli di servizio VPC, puoi configurare perimetri di sicurezza attorno alle risorse dei servizi gestiti da Google e controllare il movimento dei dati oltre il confine del perimetro.

Per istruzioni, consulta la sezione Protezione dei repository in un perimetro di servizio.

Pulire le immagini Container Registry

Quando vuoi smettere di utilizzare Container Registry, elimina le immagini rimanenti eliminando i bucket di archiviazione per Container Registry.

Per eliminare ogni bucket di archiviazione Container Registry:

gcloud storage rm gs://BUCKET-NAME --recursive

Removing gs://artifacts.my-project.appspot.com/...

Se altri servizi Google Cloud sono in esecuzione nello stesso progetto Google Cloud, lascia abilitata l'API Container Registry. Se provi a disabilitare l'API Container Registry. Container Registry mostra un avviso se nel progetto sono abilitati altri servizi con una dipendenza configurata. La disattivazione dell'API Container Registry disattiva automaticamente tutti i servizi nello stesso progetto con una dipendenza configurata, anche se al momento non utilizzi Container Registry con questi servizi.

Passaggi successivi

• Prova la guida rapida di Docker.