Configura repository con il supporto del dominio gcr.io

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

Ti consigliamo di utilizzare il nostro strumento di migrazione automatica per eseguire la transizione ai repository gcr.io in Artifact Registry.

Se vuoi creare gcr.io repository in Artifact Registry utilizzando le chiavi di crittografia gestite dal cliente (CMEK), completa i passaggi descritti in Prima di iniziare e poi 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 questo 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 i pricing 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: Amministratore Artifact Registry (roles/artifactregistry.admin)
  • Per visualizzare e gestire la configurazione esistente di Container Registry applicata ai bucket di archiviazione di Cloud Storage: Storage Admin (roles/storage.admin)
  • Per creare un repository gcr.io la prima volta che esegui il push di un'immagine a un nome host gcr.io: Writer Create-on-push Artifact Registry (roles/artifactregistry.createOnPushWriter)
  • Per concedere l'accesso al repository a livello di progetto: Amministratore IAM progetto (roles/resourcemanager.projectIamAdmin) o un ruolo che includa autorizzazioni equivalenti, come Amministratore cartelle (roles/resourcemanager.folderAdmin) o Amministratore organizzazione (roles/resourcemanager.organizationAdmin)

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

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

Limitazioni

Le seguenti limitazioni si applicano ai repository che supportano i domini gcr.io:

  • Non puoi mappare un host di Container Registry a un repository Artifact Registry in un altro progetto.
  • Ogni nome host di Container Registry viene mappato a un solo repository Artifact Registry gcr.io corrispondente nella stessa località multiregionale.
  • I nomi dei repository gcr.io sono predefiniti e non puoi modificarli.

Se hai bisogno di un maggiore controllo sulla località dei tuoi repository, puoi eseguire la transizione ai repository standard nel dominio pkg.dev. Poiché i repository standard non hanno supporto per il dominio gcr.io, questo approccio di transizione richiede ulteriori modifiche all'automazione e ai flussi di lavoro esistenti. Consulta Scegliere un'opzione di transizione per scoprire le differenze delle funzionalità.

Crea 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 abilitare il reindirizzamento.

Creazione rapida di repository

Questi passaggi creano repository gcr.io criptati con chiavi di proprietà di Google e gestite da Google. Se vuoi utilizzare chiavi di crittografia gestite dal cliente (CMEK), devi creare i repository manualmente.

Per creare gcr.io repository:

  1. Apri la pagina Repository nella console Google Cloud.

    Apri la pagina Repository

    Nella pagina è visualizzato un banner con il messaggio You have gcr.io repositories in Container Registry.

    Apri la pagina Impostazioni

  2. Nel banner, fai clic su Crea gcr.io repository.

    Si apre il riquadro Crea repository gcr.io. La sezione Copia delle immagini elenca i nomi completi di ciascun repository che verrà creato. Questi nomi di repository ti serviranno se vuoi copiare immagini da Container Registry prima di attivare il reindirizzamento.

  3. Fai clic su Crea.

Artifact Registry crea gcr.io repository per tutti i nomi host di Container Registry:

Nome host Container Registry Nome 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

Per visualizzare l'URL di Artifact Registry per il repository, posiziona il puntatore sopra l'icona di avviso ( ) accanto al nome del repository.

Prima di reindirizzare il traffico ai nuovi repository, devi assicurarti che l'automazione esistente possa accedere al repository. Il passaggio successivo prevede la configurazione delle autorizzazioni per concedere l'accesso ai repository.

Creazione manuale del repository

Crea manualmente 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 organizzazione Google 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. Consulta Attivazione delle chiavi di crittografia gestite dal cliente.

  2. Aggiungi il repository.

    Console

    1. Apri la pagina Repository 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 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 località multiregionale del repository:

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

    6. Aggiungi una descrizione per il repository. Non includere dati sensibili, perché 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 puoi controllare tramite Cloud Key Management Service. Per istruzioni sulla configurazione delle chiavi, consulta Configurazione di 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 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 indica la località multiregionale del repository:

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

    • 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 di Cloud KMS, se utilizzi una chiave di crittografia gestita dal cliente per criptare i contenuti del repository. Il percorso ha il seguente 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 confermare che il repository è stato creato elencando i 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 prevede la configurazione delle autorizzazioni per concedere l'accesso ai repository.

Concedi autorizzazioni ai repository

Container Registry utilizza i ruoli di Cloud Storage per controllare l'accesso. Artifact Registry ha i propri ruoli IAM che 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 delle entità con accesso ai bucket di archiviazione utilizzando la console Google Cloud.

  1. Nella console Google Cloud, vai alla pagina Bucket di 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 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 scheda secondaria 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 con accesso ai repository Artifact Registry. Per i ruoli di Cloud Storage ereditati dal progetto padre, devi verificare che l'entità utilizzi attualmente Container Registry. Alcune entità 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 danno intrinsecamente tutto l'accesso alle risorse Cloud Storage sottintesi dal loro nome e non forniscono autorizzazioni aggiuntive per altri servizi Google Cloud. Verifica quali utenti e account di servizio richiedono l'accesso ad Artifact Registry e utilizza la tabella di mappatura dei ruoli per concedere i ruoli corretti se l'accesso ad Artifact Registry è appropriato.

La seguente tabella mappa i ruoli di Artifact Registry in base alle autorizzazioni concesse dai ruoli di Cloud Storage predefiniti per l'accesso a Container Registry.

Accesso richiesto Ruolo attuale Ruolo Artifact Registry Dove concedere il ruolo
Esegui il pull delle immagini solo (sola lettura) Visualizzatore oggetti Storage
(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
 Writer bucket legacy Storage
(roles/storage.legacyBucketWriter)		 Amministratore repository Artifact Registry
(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 a un nome host gcr.io in un progetto. Amministratore Storage
(roles/storage.admin)		 Amministratore repository Create-on-push Artifact Registry
(roles/artifactregistry.createOnPushRepoAdmin)		 Progetto Google Cloud
Crea, gestisci ed elimina repository Amministratore Storage
(roles/storage.admin)		 Amministratore Artifact Registry
(roles/artifactregistry.Admin)		 Progetto Google Cloud
Ruoli dell'agente di servizio ereditati dal progetto

Agli account di servizio predefiniti per i servizi Google Cloud vengono assegnati ruoli specifici 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 è necessario apportare ulteriori modifiche se esegui Artifact Registry nello stesso progetto del servizio Container Registry esistente.

Per maggiori dettagli sulle autorizzazioni nei ruoli dell'agente di servizio, consulta Riferimento per il ruolo dell'agente di servizio.

Ruoli personalizzati

Utilizza la tabella della 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 sulla concessione dei ruoli di Artifact Registry, consulta Configurare ruoli e autorizzazioni.

Copia 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 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 Artifact Analysis per i metadati delle immagini e l'analisi delle vulnerabilità e gli stessi argomenti Pub/Sub per le notifiche di Artifact Analysis.

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

  • Analisi automatica di gcr.io repository in Artifact Registry.
  • Include l'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
Analizza le vulnerabilità del sistema operativo e dei pacchetti di linguaggio con l'analisi on demand delle immagini con un sistema operativo supportato. La scansione automatica restituisce solo le informazioni sulle vulnerabilità del sistema operativo. Scopri di più sui tipi di analisi.
Scansione on demand
Scansione automatica
  • Il comando Google Cloud CLI gcloud container images include flag per visualizzare i risultati della scansione, 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.
Analizza le vulnerabilità del sistema operativo e dei pacchetti in lingua con scansione sia on demand sia automatica. Scopri di più sui tipi di analisi.
Scansione on demand
Scansione automatica
  • Il comando Google Cloud CLI gcloud artefatti 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à dei pacchetti di linguaggio per i sistemi operativi supportati e non supportati.

Notifiche Pub/Sub

Artifact Registry pubblica le modifiche nello stesso argomento gcr di Container Registry. Se utilizzi già Pub/Sub con Container Registry nello stesso progetto di Artifact Registry, non è necessaria alcuna configurazione aggiuntiva. Tuttavia, Artifact Registry non pubblica messaggi per gcr.io repository 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 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 di gcr.io.

Se si verifica un problema dopo aver abilitato il reindirizzamento, puoi reindirizzare il traffico a Container Registry e quindi riattivarlo una volta 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 è nel ruolo Amministratore di Artifact Registry (roles/artifactregistry.admin).
  • storage.buckets.update - Autorizzazioni per aggiornare i bucket di archiviazione nell'intero progetto. Questa autorizzazione è nel ruolo Amministratore Storage (roles/storage.admin).

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

I comandi seguenti concedono i ruoli Amministratore Artifact Registry e Amministratore Storage su 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 user: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 il tuo ID progetto Google Cloud.

Artifact Registry controlla i repository che mappano ai nomi host di Container Registry.

Anche se Artifact Registry può creare automaticamente i repository gcr.io mancanti quando abiliti il reindirizzamento, ti consigliamo di crearli prima in modo da poter eseguire queste azioni prima di attivare il reindirizzamento:

Attiva il reindirizzamento

Per attivare il reindirizzamento per il traffico di gcr.io:

Console

  1. Apri la pagina Impostazioni nella console Google Cloud.

    Apri la pagina Impostazioni

  2. Fai clic su Instrada ad Artifact Registry.

gcloud

Per abilitare il reindirizzamento, esegui questo comando:

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

Sostituisci PROJECT_ID con il tuo ID progetto Google Cloud.

Artifact Registry avvia l'attivazione del reindirizzamento.

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

gcloud artifacts settings describe

Se 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 di Container Registry. Se esegui il push di un'immagine a un nome host senza 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 Amministratore repository Create-on-push (artifactregistry.createOnPushRepoAdmin) dispongono di questa autorizzazione.

Se 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 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 codifica l'immagine local-image come us.gcr.io/my-project/test-image:

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

    2. Esegui il push dell'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 siano state caricate 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 percorso di Container Registry. Ad esempio, questo comando estrae l'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, incluso:

  • 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, l'analisi identifica le immagini con vulnerabilità nei repository gcr.io.
  • Se utilizzi Autorizzazione binaria, i criteri esistenti funzionano correttamente per le immagini di cui è stato eseguito il deployment dai repository gcr.io.
  • Le sottoscrizioni Pub/Sub configurate includono notifiche per le modifiche nei repository gcr.io.

Esegui la pulizia delle immagini di Container Registry

Se 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 per eliminare le immagini nei percorsi gcr.io non eliminano le immagini archiviate negli host di Container Registry.

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

Per eliminare ciascun bucket di archiviazione di Container Registry:

Console

  1. Vai alla pagina di 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.

gsutil

Se vuoi eliminare in blocco un centinaio di immagini o più in un bucket, evita di utilizzare gsutil poiché il processo di eliminazione richiede molto tempo. Utilizza la console Google Cloud per eseguire l'operazione.

Per eliminare un bucket, utilizza il comando gsutil rm con il flag -r.

gsutil rm -r gs://BUCKET-NAME

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 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 disabilitazione dell'API Container Registry disabilita automaticamente tutti i servizi nello stesso progetto con una dipendenza configurata, anche se attualmente non utilizzi Container Registry con questi servizi.

Passaggi successivi