Configurare i repository con il supporto per il dominio gcr.io

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

Ti consigliamo di utilizzare il nostro strumento di migrazione automatica per passare ai 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, poi segui le istruzioni 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 di più sui 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 ruoli IAM seguenti sul progetto Google Cloud:

  • Per creare repository Artifact Registry e concedere l'accesso a singoli repository: Amministratore di Artifact Registry (roles/artifactregistry.admin)
  • Per visualizzare e gestire la configurazione esistente di Container Registry applicata ai bucket di archiviazione di Cloud Storage: Amministratore Storage (roles/storage.admin)
  • Per creare un repository gcr.io la prima volta che esegui il push di un'immagine su un nome host gcr.io: Writer Create-on-push di 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 include 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 essere in grado di ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Limitazioni

Le seguenti limitazioni si applicano ai repository che supportano il dominio gcr.io:

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

Se hai bisogno di un maggiore controllo sulla località dei repository, puoi passare ai repository standard sul dominio Artifact Registry 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. Per scoprire di più sulle differenze delle funzionalità, consulta Scegliere un'opzione di transizione.

Crea repository

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

Creazione rapida del repository

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

Per creare repository gcr.io:

  1. Apri la pagina Repositories nella console Google Cloud.

    Apri la pagina Repository

    Nella pagina, un banner mostra 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 gcr.io repository. La sezione Copia delle immagini elenca i nomi completi di ogni repository che verrà creato. Questi nomi di repository saranno necessari 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 di 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, tieni 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 consiste nella configurazione delle autorizzazioni per concedere l'accesso ai repository.

Creazione manuale del repository

Crea manualmente repository gcr.io se vuoi utilizzare 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 utilizzarla. Vedi Abilitazione delle chiavi di crittografia gestite dal cliente.

  2. Aggiungi il repository.

    Console

    1. Apri la pagina Repositories nella console Google Cloud.

      Apri la pagina Repository

    2. Fai clic su Crea repository.

    3. Specifica il nome del repository.

      Nome host di 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 più regioni per il repository:

      Nome host di 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, 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 crittografia gestita da Google.
      • Chiave gestita dal cliente: cripta i contenuti del repository con una chiave che puoi controllare 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 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 località a più regioni per il repository:

      Nome host di 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 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 nella configurazione delle autorizzazioni per concedere l'accesso ai repository.

Concedi le autorizzazioni ai repository

Container Registry utilizza i ruoli di Cloud Storage per controllare l'accesso. Artifact Registry dispone di ruoli IAM propri 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 di 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 di Cloud Storage.

    Vai a Bucket

  2. Fai clic sul bucket di archiviazione relativo all'host del registro che vuoi visualizzare. Nei nomi dei bucket, PROJECT-ID è l'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 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 agli account di servizio che attualmente accedono a Container Registry con accesso ai repository Artifact Registry. Per i ruoli 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 offrono intrinsecamente tutti gli accessi alle risorse Cloud Storage implicati dal loro nome, né 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 appropriati 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) 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 di 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 di Artifact Registry
(roles/artifactregistry.createOnPushRepoAdmin)		 Progetto Google Cloud
Creare, gestire ed eliminare i repository Amministratore Storage
(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 degli agenti 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 di agente di servizio, consulta la documentazione sul ruolo di agente di servizio.

Ruoli personalizzati

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

Per istruzioni sulla concessione dei ruoli 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 se il reindirizzamento è abilitato:

  • Analisi automatica di gcr.io repository 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 note e occorrenze associate ai percorsi delle immagini gcr.io.

Container Registry Artifact Registry
Analisi delle 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 analisi.
Analisi 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 solo informazioni sulle vulnerabilità del sistema operativo per le immagini in Container Registry con sistemi operativi supportati.
Analisi delle vulnerabilità dei pacchetti di sistemi operativi e linguaggi con analisi sia on demand che automatica. Scopri di più sui tipi di analisi.
Analisi on demand
Scansione automatica
  • Il comando gcloud artefatti docker images di Google Cloud 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 modifiche allo 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 abiliti 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 repository gcr.io e configurato le autorizzazioni e l'autenticazione per i client di terze parti, puoi abilitare il reindirizzamento del traffico gcr.io.

Se si verifica un problema dopo aver abilitato il reindirizzamento, puoi instradare il traffico di nuovo a Container Registry e poi riattivarlo dopo aver risolto il problema.

Verifica le autorizzazioni per abilitare 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 disponi di queste autorizzazioni, chiedi a un amministratore di concederle a livello di progetto.

I comandi seguenti 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 è 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 verifica la presenza di repository mappati a nomi host di Container Registry.

Anche se Artifact Registry può creare per te 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 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 il 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 attuale del reindirizzamento, esegui questo comando:

gcloud artifacts settings describe

Quando il reindirizzamento è abilitato, 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 su un nome host che non dispone di 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 Create-on-push Repository Amministratore (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 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. Esegui il push dell'immagine taggata. 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 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 di 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 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 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 apportate ai repository gcr.io.

Esegui la pulizia delle 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 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 ogni 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 almeno centomila immagini 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, usa 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 è l'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 disattivazione dell'API Container Registry disattiva automaticamente tutti i servizi nello stesso progetto con una dipendenza configurata, anche se non stai attualmente utilizzando Container Registry con quei servizi.

Passaggi successivi