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), compila 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à installato. 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 la presenza di una delle autorizzazioni richieste.

    Esegui questo comando:

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

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

Per saperne di più sulla concessione dei ruoli, consulta Gestire 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:

  • Durante la transizione da Container Registry, non puoi mappare un host Container Registry a un repository Artifact Registry in un altro progetto.
  • Ogni nome host di Container Registry viene mappato a un solo repository gcr.io Artifact Registry corrispondente nella stessa regione multipla.
  • I nomi dei repository gcr.io sono predefiniti e non puoi modificarli.

Se hai bisogno di un maggiore controllo sulla posizione dei tuoi 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 alle automazioni 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 di Container Registry esistenti in Artifact Registry prima di attivare la reindirizzamento.

Creazione manuale del repository

Crea manualmente i repository gcr.io se vuoi utilizzare chiavi di crittografia gestite dal cliente (CMEK) per criptare i contenuti dei repository o se nella tua organizzazione Google Cloud è presente un vincolo di località 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 utilizzarla. Consulta Abilitazione delle chiavi di crittografia gestite dal cliente.

  2. Aggiungi il repository.

    Console

    1. Apri la pagina Repositories (Repositoi) nella console Google Cloud.

      Apri la pagina Repository

    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.

      • Chiave gestita da Google: cripta i contenuti del repository con una chiave di proprietà e gestita da Google.
      • 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 di 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 di 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.

    Puoi verificare che il repository sia stato creato elencando 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 più chiaramente i ruoli di lettura, scrittura e amministrazione del repository rispetto a Container Registry.

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

In alternativa, puoi visualizzare un elenco di principali 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 registry che vuoi visualizzare. Nei nomi dei bucket, PROJECT-ID è il tuo ID progetto Google Cloud.

    • 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 sottoscheda Visualizza per ruolo.

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

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

Cloud Storage e ruoli di base

Concedi agli utenti e agli account di servizio che attualmente accedono a Container Registry l'accesso ai repository di Artifact Registry. Per i ruoli Cloud Storage ereditati dal progetto principale, devi verificare che il principale utilizzi attualmente Container Registry. Alcuni principali 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 forniscono intrinsecamente tutto l'accesso alle risorse Cloud Storage suggerito dai loro nomi e non forniscono autorizzazioni aggiuntive per altri servizi Google Cloud. Verifica quali utenti e account di servizio richiedono accesso ad Artifact Registry e utilizza la tabella di mappatura dei ruoli per assegnare i ruoli corretti, se l'accesso ad Artifact Registry è appropriato.

La tabella seguente mappa i ruoli di 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
Esporta solo immagini (sola lettura) Storage Object Viewer
(roles/storage.objectViewer)		 Lettore di Artifact Registry
(roles/artifactregistry.reader) 		Repository Artifact Registry o progetto Google Cloud
  • Eseguire 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 un'immagine viene pushata a un nome host gcr.io in un progetto. Storage Admin
(roles/storage.admin)		 Artifact Registry Create-on-push Repository Administrator
(roles/artifactregistry.createOnPushRepoAdmin)		 Progetto Google Cloud
Creare, gestire ed eliminare i repository Storage Admin
(roles/storage.admin)		 Amministratore di Artifact Registry
(roles/artifactregistry.Admin)		 Progetto Google Cloud
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 di agente di servizio contengono autorizzazioni predefinite equivalenti per Container Registry e Artifact Registry e non è necessario apportare ulteriori modifiche se esegui Artifact Registry nello stesso progetto del servizio Container Registry esistente.

Per informazioni dettagliate sulle autorizzazioni nei ruoli dell'agente di servizio, consulta la sezione Riferimento ai ruoli dell'agente di servizio.

Ruoli personalizzati

Utilizza la tabella di mappatura dei ruoli per decidere il ruolo da concedere agli utenti o agli account di servizio in base al livello di accesso richiesto.

Per istruzioni su come concedere i ruoli di Artifact Registry, consulta Configurare i ruoli e le autorizzazioni.

Copiare i 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 Copiare le immagini da Container Registry

Configurare altre funzionalità

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

Artifact Analysis

Artifact Analysis supporta sia Container Registry che Artifact Registry. Entrambi i prodotti utilizzano le stesse API di Artifact Analysis per la scansione dei metadati delle immagini e delle vulnerabilità e gli stessi argomenti Pub/Sub per le notifiche di Artifact Analysis.

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

  • 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.

Container Registry Artifact Registry
Cerca le vulnerabilità del sistema operativo e dei pacchetti di linguaggio con l'analisi on demand nelle immagini con un sistema operativo supportato. La scansione automatica restituisce solo informazioni sulle vulnerabilità del sistema operativo. Scopri di più sui tipi di scansione.
Scansione on demand
Scansione automatica
  • Il comando CLI di Google Cloud gcloud container images include flag per visualizzare i risultati dell'analisi, tra cui vulnerabilità e altri metadati.
  • Le analisi restituiscono informazioni sulle vulnerabilità del sistema operativo solo per le immagini in Container Registry con sistemi operativi supportati.
Cerca le vulnerabilità del sistema operativo e dei pacchetti di lingua con l'analisi automatica e on demand. Scopri di più sui tipi di scansione.
Scansione on demand
Scansione automatica
  • Il comando CLI di Google Cloud gcloud artifacts docker images include flag per visualizzare i risultati della scansione, tra cui vulnerabilità e altri metadati.
  • Le analisi restituiscono informazioni sulle vulnerabilità del sistema operativo per le immagini in Artifact Registry con sistemi operativi supportati e informazioni sulle vulnerabilità del pacchetto di linguaggio sia per i sistemi operativi supportati sia per quelli non supportati.

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 configuri Artifact Registry in un progetto separato, l'argomento gcr potrebbe non esistere. Per le istruzioni di configurazione, consulta Configurazione delle notifiche Pub/Sub.

Attiva il reindirizzamento del traffico gcr.io

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

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

Verifica le autorizzazioni per abilitare il reindirizzamento

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

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

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

I comandi seguenti assegnano i ruoli Amministratore Artifact Registry e Amministratore archiviazione a 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 è l'ID progetto Google Cloud.
  • 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 il seguente comando:

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

Sostituisci PROJECT_ID con il tuo ID progetto Google Cloud.

Artifact Registry controlla la presenza di repository mappati ai nomi host di Container Registry.

Anche se Artifact Registry può 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:

Attivare il reindirizzamento

Per attivare il reindirizzamento per il traffico gcr.io:

Per abilitare il reindirizzamento, esegui il seguente comando:

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

Sostituisci PROJECT_ID con il tuo ID progetto Google Cloud.

Artifact Registry inizia ad attivare il reindirizzamento.

Per controllare lo stato corrente del reindirizzamento, esegui il seguente comando:

gcloud artifacts settings describe

Quando il reindirizzamento è attivo, 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 di Container Registry. Se esegui il push di un'immagine a un nome host che non ha un repository Artifact Registry corrispondente, Artifact Registry crea il repository se disponi di un ruolo con l'autorizzazione artifactregistry.repositories.createOnPush. I ruoli predefiniti Create-on-push Writer (artifactregistry.createOnPushWriter) e Create-on-push Repository Administrator (artifactregistry.createOnPushRepoAdmin) dispongono di questa autorizzazione.

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

Verifica il 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. Pubblica l'immagine che hai taggato. Ad esempio, questo comando spinge l'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 l'immagine sia stata caricata correttamente. 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 relativo percorso in 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 la creazione e il deployment delle immagini funzioni come previsto, ad esempio:

  • Gli utenti e gli account di servizio che utilizzano Container Registry possono comunque eseguire push, pull e deployment delle immagini quando il reindirizzamento è attivo.
  • L'automazione esegue il push delle immagini solo nei repository esistenti.
  • Se l'analisi delle vulnerabilità di Artifact Analysis è attivata, la scansione identifica le immagini con vulnerabilità nei repository gcr.io.
  • Se utilizzi l'autorizzazione binaria, i criteri esistenti funzionano correttamente per le immagini messe in produzione dai repository gcr.io.
  • Gli abbonamenti Pub/Sub configurati includono notifiche per le modifiche nei repository gcr.io.

Ripulire le immagini di Container Registry

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

Per rimuovere in sicurezza tutte le immagini di Container Registry, elimina i bucket Cloud Storage per ogni nome host di Container Registry.

Per eliminare ogni bucket di archiviazione di Container Registry:

Console

  1. Vai alla pagina Cloud Storage nella console Google Cloud.

  2. Seleziona il bucket di archiviazione da eliminare. Nei nomi dei bucket, PROJECT-ID è il tuo ID progetto Google Cloud.

    • 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 su Elimina. Viene visualizzata una finestra di dialogo di conferma.

  4. Per confermare l'eliminazione, inserisci il nome del bucket e fai clic su Elimina.

gcloud

Se vuoi eliminare in blocco almeno centomila immagini in un bucket, evita di utilizzare l'interfaccia a riga di comando gcloud poiché il processo di eliminazione richiede molto tempo. Utilizza la console Google Cloud per eseguire l'operazione. Per ulteriori informazioni, consulta la sezione sulla eliminazione collettiva degli oggetti Cloud Storage.

Per eliminare un bucket, utilizza il comando gcloud storage rm con il flag --recursive.

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

Sostituisci BUCKET-NAME con il nome del bucket di archiviazione di Container Registry. Nei nomi dei bucket, PROJECT-ID è il tuo ID progetto Google Cloud.

  • 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

La risposta è simile al seguente esempio:

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

Se nello stesso progetto Google Cloud sono in esecuzione altri servizi Google Cloud, lascia attiva l'API Container Registry. Se provi a disattivare 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