Migrazione manuale ai repository `gcr.io` in Artifact Registry

Questo documento spiega come configurare manualmente i repository gcr.io in Artifact Registry.

Se vuoi creare repository gcr.io in Artifact Registry utilizzando chiavi di crittografia gestite dal cliente (CMEK), completa i passaggi descritti in Prima di iniziare, quindi segui le istruzioni riportate in Creazione manuale del repository.

Prima di iniziare

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

   gcloud components update
   

2. Abilita le API Artifact Registry e Resource Manager. gcloud CLI utilizza l'API Resource Manager per verificare una delle autorizzazioni richieste.

   Esegui questo comando:

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

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:

• Per creare repository Artifact Registry e concedere l'accesso a singoli repository: Amministratore Artifact Registry (roles/artifactregistry.admin) sul progetto Google Cloud
• Per visualizzare e gestire la configurazione di Container Registry esistente applicata ai bucket di archiviazione Cloud Storage: Amministratore Storage (roles/storage.admin) sul progetto Google Cloud
• Per creare un repository gcr.io la prima volta che esegui il push di un'immagine in un nome host gcr.io: Artifact Registry Create-on-push Writer (roles/artifactregistry.createOnPushWriter) sul progetto Google Cloud
• Per concedere l'accesso al repository a livello di progetto: Project IAM Admin (roles/resourcemanager.projectIamAdmin) sul progetto Google Cloud
• Per elencare i servizi abilitati in un'organizzazione: Visualizzatore di asset cloud (roles/cloudasset.viewer) sull'organizzazione

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.

Limitazioni

Ai repository gcr.io di Artifact Registry si applicano le seguenti limitazioni:

• Quando esegui la transizione da Container Registry, non puoi mappare un host Container Registry a un repository Artifact Registry in un altro progetto.

• Ogni nome host Container Registry viene mappato a un solo repository gcr.io Artifact Registry corrispondente nella stessa multiregione.

• I nomi dei repository gcr.io sono predefiniti e non possono essere modificati.

Se hai bisogno di un maggiore controllo sulla posizione dei repository, puoi eseguire la transizione ai repository pkg.dev in Artifact Registry. Poiché i repository pkg.dev non supportano il dominio gcr.io, questo approccio di transizione richiede più modifiche all'automazione e ai flussi di lavoro esistenti. Consulta Scegliere un'opzione di transizione per scoprire le differenze tra le funzionalità.

Creare repository

Crea repository gcr.io in modo da poter configurare l'accesso per i tuoi utenti e copiare le immagini Container Registry esistenti in Artifact Registry prima di attivare il reindirizzamento.

Creazione manuale del repository

Crea manualmente i repository gcr.io se vuoi utilizzare le chiavi di crittografia gestite dal cliente (CMEK) per criptare i contenuti del repository o se esiste un vincolo di località nella tua organizzazioneGoogle Cloud che blocca la creazione di nuove risorse in località specifiche.

Per creare manualmente un repository gcr.io:

1. Se utilizzi CMEK, crea la chiave che utilizzerai con questo repository e concedi le autorizzazioni per utilizzare la chiave. Vedi Abilitazione delle chiavi di crittografia gestite dal cliente.

2. Aggiungi il repository.

   Console

   1. Apri la pagina Repository nella console Google Cloud .

      Apri la pagina Repositori

   2. Fai clic su Crea repository.

   3. Specifica il nome del repository.

      Nome host Container Registry	Nome del repository Artifact Registry
      gcr.io	gcr.io
      asia.gcr.io	asia.gcr.io
      eu.gcr.io	eu.gcr.io
      us.gcr.io	us.gcr.io

   4. Specifica Docker come formato del repository.

   5. In Tipo di località, specifica la regione multipla per il repository:

      Nome host Container Registry	Posizione del repository Artifact Registry	Nome del repository Artifact Registry
      gcr.io	us	gcr.io
      asia.gcr.io	asia	asia.gcr.io
      eu.gcr.io	europe	eu.gcr.io
      us.gcr.io	us	us.gcr.io

   6. Aggiungi una descrizione per il repository. Non includere dati sensibili, poiché le descrizioni dei repository non sono criptate.

   7. Nella sezione Crittografia, scegli il meccanismo di crittografia per il repository.

      • Google-managed encryption key: cripta i contenuti del repository con un Google-owned and Google-managed encryption key.
      • Chiave gestita dal cliente: cripta i contenuti del repository con una chiave che controlli tramite Cloud Key Management Service. Per le istruzioni di configurazione delle chiavi, consulta Configurare CMEK per i repository.

   8. Fai clic su Crea.

   gcloud

   Esegui questo comando per creare un nuovo repository:

   gcloud artifacts repositories create REPOSITORY \
       --repository-format=docker \
       --location=LOCATION \
       --description=DESCRIPTION \
       --kms-key=KMS-KEY
   

   Sostituisci i seguenti valori:

   • REPOSITORY è il nome del repository.

     Nome host Container Registry	Nome del repository Artifact Registry
     gcr.io	gcr.io
     asia.gcr.io	asia.gcr.io
     eu.gcr.io	eu.gcr.io
     us.gcr.io	us.gcr.io

   • LOCATION è la regione multipla per il repository:

     Nome host Container Registry	Posizione del repository Artifact Registry	Nome del repository Artifact Registry
     gcr.io	us	gcr.io
     asia.gcr.io	asia	asia.gcr.io
     eu.gcr.io	europe	eu.gcr.io
     us.gcr.io	us	us.gcr.io

   • DESCRIPTION è una descrizione del repository. Non includere dati sensibili, poiché le descrizioni dei repository non sono criptate.

   • KMS-KEY è il percorso completo della chiave di crittografia Cloud KMS, se utilizzi una chiave di crittografia gestita dal cliente per criptare i contenuti del repository. Il percorso è nel formato:

     projects/KMS-PROJECT/locations/KMS-LOCATION/keyRings/KEY-RING/cryptoKeys/KEY

     Sostituisci i seguenti valori:

     • KMS-PROJECT è il progetto in cui è archiviata la chiave.
     • KMS-LOCATION è la posizione della chiave.
     • KEY-RING è il nome del keyring.
     • KEY è il nome della chiave.

   Per verificare che il repository sia stato creato, elenca i tuoi repository con il seguente comando:

   gcloud artifacts repositories list
   

Prima di reindirizzare il traffico ai nuovi repository, devi assicurarti che l'automazione esistente possa accedere al repository. Il passaggio successivo consiste nel configurare le autorizzazioni per concedere l'accesso ai repository.

Concedi le autorizzazioni ai repository

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.

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) Elimina immagini	Storage Legacy Bucket Writer (roles/storage.legacyBucketWriter)	Artifact Registry Repository Administrator (roles/artifactregistry.repoAdmin)	Repository Artifact Registry o progetto Google Cloud
Crea un repository gcr.io in Artifact Registry la prima volta che viene eseguito il push di un'immagine in un nome host gcr.io in un progetto.	Amministratore Storage (roles/storage.admin)	Artifact Registry Create-on-push Repository Administrator (roles/artifactregistry.createOnPushRepoAdmin)	Google Cloud project
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.

Copia dei container da Container Registry

Ti consigliamo di utilizzare il nostro strumento di migrazione automatica per copiare le immagini da Container Registry ad Artifact Registry.

Se vuoi utilizzare altri strumenti per copiare le immagini, consulta Copia le immagini da Container Registry

Configurare altre funzionalità

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. Entrambi i prodotti utilizzano le stesse API Artifact Analysis per i metadati delle immagini e la scansione delle vulnerabilità, nonché gli stessi argomenti Pub/Sub per le notifiche di Artifact Analysis.

Tuttavia, le seguenti azioni si verificano solo quando il reindirizzamento è attivato:

• Scansione automatica dei repository gcr.io in Artifact Registry.
• Inclusione dell'attività del repository gcr.io nelle notifiche Pub/Sub.

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. Tuttavia, Artifact Registry non pubblica messaggi per i repository gcr.io finché non attivi il reindirizzamento.

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.

Abilita il reindirizzamento del traffico di gcr.io

Dopo aver creato i repository gcr.io e configurato le autorizzazioni e l'autenticazione per i client di terze parti, puoi attivare il reindirizzamento del traffico gcr.io.

Se riscontri un problema dopo aver attivato il reindirizzamento, puoi reindirizzare il traffico a Container Registry eseguendo il comando gcloud artifacts settings disable-upgrade-redirection e poi riattivare il reindirizzamento dopo aver risolto il problema.

Verifica le autorizzazioni per attivare il reindirizzamento

Per abilitare il reindirizzamento, devi disporre delle seguenti autorizzazioni a livello di progetto:

• artifactregistry.projectsettings.update - Autorizzazioni per aggiornare le impostazioni del progetto Artifact Registry. Questa autorizzazione è inclusa nel ruolo Amministratore di Artifact Registry (roles/artifactregistry.admin).
• storage.buckets.update - Autorizzazioni per aggiornare i bucket di archiviazione nell'intero progetto. Questa autorizzazione è inclusa nel ruolo Amministratore Storage (roles/storage.admin).

Se non disponi di queste autorizzazioni, chiedi a un amministratore di concederle a livello di progetto.

I seguenti comandi concedono i ruoli Amministratore Artifact Registry e Amministratore Storage per un progetto.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='roles/artifactregistry.admin'

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='roles/storage.admin'

Sostituisci i seguenti valori:

• PROJECT_ID è Google Cloud l'ID progetto.
• PRINCIPAL è l'indirizzo email dell'account che stai aggiornando. Ad esempio, my-user@example.com

Convalida la configurazione del progetto

Per convalidare la configurazione del progetto, esegui questo comando:

gcloud artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID --dry-run

Sostituisci PROJECT_ID con l' Google Cloud ID progetto.

Artifact Registry verifica la presenza di repository che mappano i nomi host di Container Registry.

Sebbene Artifact Registry possa creare i repository gcr.io mancanti per te quando attivi il reindirizzamento, ti consigliamo di crearli prima in modo da poter eseguire queste azioni prima di attivare il reindirizzamento:

• Configurare le autorizzazioni a livello di repository.
• Copia le immagini da Container Registry che vuoi ancora utilizzare.
• Esegui qualsiasi configurazione aggiuntiva.

Attivare il reindirizzamento

Per attivare il reindirizzamento del traffico gcr.io:

Per abilitare il reindirizzamento, esegui questo comando:

gcloud artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID

Sostituisci PROJECT_ID con l' Google Cloud ID progetto.

Artifact Registry inizia ad attivare il reindirizzamento.

Per controllare lo stato attuale del reindirizzamento, esegui questo comando:

gcloud artifacts settings describe

Quando il reindirizzamento è attivato, il risultato è:

legacyRedirectionState: REDIRECTION_FROM_GCR_IO_ENABLED

Tutto il traffico verso gcr.io, asia.gcr.io, eu.gcr.io e us.gcr.io viene reindirizzato, anche se non hai creato repository gcr.io per tutti i nomi host Container Registry. Se esegui il push di un'immagine in un nome host che non ha un repository Artifact Registry corrispondente, Artifact Registry crea il repository se hai un ruolo con l'autorizzazione artifactregistry.repositories.createOnPush. I ruoli predefiniti Writer Create-on-push (artifactregistry.createOnPushWriter) e Amministratore repository Create-on-push (artifactregistry.createOnPushRepoAdmin) dispongono di questa autorizzazione.

Con il reindirizzamento attivato, puoi testare l'automazione e verificare di poter eseguire il push e il pull delle immagini utilizzando i nuovi repository gcr.io.

Verifica reindirizzamento

Verifica che le richieste pull e push ai nomi host gcr.io funzionino.

1. Esegui il push di un'immagine di test in uno dei tuoi repository gcr.io utilizzando il relativo percorso gcr.io.

   1. Tagga l'immagine utilizzando il percorso gcr.io. Ad esempio, questo comando tagga l'immagine local-image come us.gcr.io/my-project/test-image:

      docker tag local-image us.gcr.io/my-project/test-image
      

   2. Spingi l'immagine che hai taggato. Ad esempio, questo comando esegue il push dell'immagine us.gcr.io/my-project/test-image:

      docker push us.gcr.io/my-project/test-image
      

2. Elenca le immagini nel repository per verificare che il caricamento sia andato a buon fine. Ad esempio, per elencare le immagini in us.gcr.io/my-project, esegui il comando:

   gcloud container images list --repository=us.gcr.io/my-project
   

3. Esegui il pull dell'immagine dal repository utilizzando il percorso Container Registry. Ad esempio, questo comando esegue il pull dell'immagine us.gcr.io/my-project/test-image.

   docker pull us.gcr.io/my-project/test-image
   

Dopo questo test iniziale, verifica che l'automazione esistente per creare ed eseguire il deployment delle immagini funzioni come previsto, tra cui:

• Gli utenti e gli account di servizio che utilizzano Container Registry possono comunque eseguire il push, il pull e il deployment delle immagini quando il reindirizzamento è abilitato.
• L'automazione esegue il push delle immagini solo nei repository esistenti.
• Se l'analisi delle vulnerabilità di Artifact Analysis è abilitata, la scansione identifica le immagini con vulnerabilità nei repository gcr.io.
• Se utilizzi l'autorizzazione binaria, le tue norme esistenti funzionano correttamente per le immagini di cui è stato eseguito il deployment dai repository gcr.io.
• Gli abbonamenti Pub/Sub configurati includono notifiche per le modifiche apportate ai repository gcr.io.

Pulire le immagini Container Registry

Quando il reindirizzamento è abilitato, i comandi per eliminare le immagini nei percorsi gcr.io eliminano le immagini nel repository Artifact Registry gcr.io corrispondente. I comandi di eliminazione per eliminare le immagini nei percorsi gcr.io non eliminano le immagini archiviate sugli host Container Registry.

Per rimuovere in sicurezza tutte le immagini Container Registry, elimina i bucket Cloud Storage per ogni nome host 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.
• Scopri di più sui repository gcr.io.