Push e pull delle immagini

Il push (caricamento) e il pull (download) delle immagini sono due delle attività più comuni di Container Registry. Questo documento è incentrato sull'esecuzione di push e pull di immagini con Docker.

Se utilizzi Cloud Build, consulta la documentazione di Cloud Build per informazioni sulla creazione e sul push dei container in Container Registry.

Per istruzioni su come elencare, taggare ed eliminare le immagini, consulta Gestione delle immagini.

Prima di iniziare

Assicurati di avere:

  1. Abilitato Container Registry nel tuo progetto.

  2. Docker installato e configurato.

Aggiunta di un registro

Puoi aggiungere i seguenti registri di Container Registry a un progetto:

Nome host Località di archiviazione
gcr.io Archivia le immagini nei data center degli Stati Uniti
asia.gcr.io Archivia le immagini nei data center in Asia
eu.gcr.io Archivia le immagini nei data center degli stati membri dell'Unione Europea
us.gcr.io Archivia le immagini nei data center degli Stati Uniti

Il push della prima immagine a un nome host attiva la creazione del registro in un progetto e del bucket di archiviazione Cloud Storage corrispondente. Questo push iniziale richiede autorizzazioni a livello di progetto per creare bucket di archiviazione.

Quando nel progetto esiste un host del Registro di sistema, puoi configurare le autorizzazioni nel bucket di archiviazione per controllare l'accesso alle immagini nel registro.

Per aggiungere un registro e configurare le autorizzazioni:

  1. Verifica di disporre delle autorizzazioni necessarie. Devi avere il ruolo Amministratore archiviazione (roles/storage.admin), un ruolo personalizzato o un ruolo predefinito con le stesse autorizzazioni.

    Per istruzioni su come concedere il ruolo Amministratore Storage a livello di progetto, consulta la documentazione di IAM.

  2. Esegui il push di un'immagine iniziale all'host. Ad esempio, i seguenti comandi:

    • Esegui il pull dell'immagine busybox da Docker Hub
    • Tagga l'immagine con il relativo percorso di destinazione in Container Registry, inclusi l'host del registro gcr.io e l'ID progetto my-project
    • Esegui il push dell'immagine al registro
    docker pull busybox
docker tag busybox gcr.io/my-project/busybox
docker push gcr.io/my-project/busybox

Container Registry aggiunge il registro al tuo progetto, crea un bucket di archiviazione per il registro e archivia l'immagine.

Ora puoi configurare il controllo dell'accesso nel bucket di archiviazione del Registro di sistema per concedere l'accesso al registro ad altri utenti.

Push di un'immagine a un registro

Per eseguire il push di un'immagine locale in Container Registry utilizzando Docker o un altro strumento di terze parti, devi prima taggarla con il nome del registro ed eseguire il push dell'immagine.

I seguenti fattori potrebbero influire sui caricamenti di immagini di grandi dimensioni:

Tempo di caricamento
Qualsiasi richiesta inviata a Container Registry ha un limite di timeout di due ore. Se esegui l'autenticazione in Container Registry utilizzando un token di accesso, il token scade dopo 60 minuti. Se prevedi che il tempo di caricamento supererà i 60 minuti, utilizza un metodo di autenticazione diverso.
Dimensioni dell'immagine
Container Registry usa Cloud Storage per lo spazio di archiviazione sottostante di ciascun registro. A ogni registro si applicano quote e limiti di Cloud Storage, compresa la dimensione massima di 5 TB per un oggetto di archiviazione.
Container Registry non supporta i caricamenti a blocchi Docker. Alcuni strumenti supportano il caricamento di immagini di grandi dimensioni tramite caricamenti a blocchi o un singolo caricamento monolitico. Devi utilizzare caricamenti monolitici per eseguire il push delle immagini in Container Registry.

Autorizzazioni obbligatorie

Il push di un'immagine richiede uno dei seguenti ruoli Cloud Storage o un ruolo con le stesse autorizzazioni:

Push della prima immagine a un registro del progetto

Ruolo: Amministratore Storage (roles/storage.admin) a livello di progetto Google Cloud. Il ruolo Proprietario predefinito include queste autorizzazioni.

La prima volta che esegui il push di un'immagine in un host del registry nel tuo progetto (ad esempio gcr.io), Container Registry crea un bucket di archiviazione per il Registro di sistema. Il ruolo Amministratore Storage dispone delle autorizzazioni necessarie per creare il bucket di archiviazione.

Push delle immagini a un registro esistente nel progetto

Ruolo: Writer bucket legacy di archiviazione (roles/storage.legacyBucketWriter) nel bucket di archiviazione del Registro di sistema.

Questo ruolo dispone delle autorizzazioni per eseguire il push e il pull delle immagini per gli host del registro esistenti nel progetto. Ad esempio, se il progetto contiene solo il Registro di sistema gcr.io, un utente con il ruolo Writer bucket legacy di archiviazione può eseguire il push delle immagini in gcr.io, ma non può eseguire il push delle immagini in asia.gcr.io.

Per informazioni sulla concessione delle autorizzazioni a un registro, consulta Configurazione del controllo dell'accesso.

Aggiungi all'immagine locale il nome del registro

Per taggare un'immagine:

  1. Verifica di aver configurato l'autenticazione in Container Registry.

  2. Determina il nome dell'immagine in Container Registry:

    1. Scegli un nome host, che specifica la posizione in cui archivierai l'immagine.

      • gcr.io ospita immagini nei data center degli Stati Uniti, ma la località potrebbe cambiare in futuro
      • us.gcr.io ospita le immagini nei data center degli Stati Uniti, in un bucket di archiviazione separato dalle immagini ospitate da gcr.io
      • eu.gcr.io ospita le immagini nell'Unione Europea
      • asia.gcr.io ospita immagini nei data center in Asia

      Queste località corrispondono a più regioni per i bucket di archiviazione di Cloud Storage. Quando esegui il push di un'immagine in un registro con un nuovo nome host, Container Registry crea un bucket di archiviazione nella località multiregionale specificata. Questo bucket è lo spazio di archiviazione sottostante per il registry. All'interno di un progetto, tutti i registry con lo stesso nome host condividono un bucket di archiviazione.

      Nella console, il nome host delle immagini sarà elencato sotto Posizione.

    2. Scegli un nome per l'immagine di destinazione, che può essere diverso dal nome dell'immagine sulla macchina locale. Ad esempio, l'immagine locale potrebbe essere denominata web-image, ma vuoi archiviarla in Container Registry come web-site

    3. Combina il nome host, l'ID progetto della console Google Cloud e il nome dell'immagine di destinazione:

      HOSTNAME/PROJECT-ID/TARGET-IMAGE

      Considera il seguente esempio:

      • Nome host: gcr.io
      • Progetto Google Cloud: my-project
      • Nome immagine di destinazione: web-site

      Se combini il nome host, il progetto e il nome dell'immagine di destinazione, ottieni il percorso completo dell'immagine da utilizzare per il tagging:

      gcr.io/my-project/web-site

      Se l'ID progetto contiene i due punti (:), consulta Progetti con ambito di dominio.

  3. Aggiungi all'immagine locale il nome del passaggio precedente. Se vuoi etichettare questa versione dell'immagine con un tag, includi il nome del tag.

    docker tag SOURCE_IMAGE HOSTNAME/PROJECT-ID/TARGET-IMAGE:TAG

    Sostituisci quanto segue:

    • SOURCE_IMAGE è il nome o l'ID immagine locale dell'immagine.
    • HOSTNAME è l'host del Registro di sistema che hai scelto nel passaggio 2.
    • PROJECT è l'ID del progetto Google Cloud.
    • TARGET-IMAGE è il nome dell'immagine quando viene archiviata in Container Registry.
    • TAG è il tag che vuoi associare a questa versione dell'immagine.

    Ad esempio, questo comando tagga l'immagine locale web-image come gcr.io/my-project/web-site in Container Registry con il tag v1.5

    docker tag web-image gcr.io/my-project/web-site:v1.5

    Se non specifichi un tag, Docker aggiunge il tag latest predefinito. Poiché latest è un tag predefinito, rappresenta la versione dell'immagine taggata più di recente con il tag latest, non necessariamente la versione più recente di un'immagine.

Docker tagga l'immagine con il nome e il tag specificati nel comando.

Esegui il push dell'immagine taggata in Container Registry

  1. Verifica di aver configurato l'autenticazione in Container Registry.

  2. Esegui il push dell'immagine taggata in Container Registry:

    Esegui questo comando per eseguire il push di un'immagine con un tag specifico:

    docker push HOSTNAME/PROJECT-ID/IMAGE:TAG

    Se ometti :TAG, Docker esegue il push della versione dell'immagine taggata con latest.

    Ad esempio, questo comando esegue il push dell'immagine gcr.io/my-project/web-site con il tag v1.5:

    docker push gcr.io/my-project/web-site:v1.5

Quando esegui il push di un'immagine su un host del registro che non esiste ancora nel progetto, Container Registry crea un bucket di archiviazione per l'host del registro.

Per visualizzare l'immagine che hai inviato:

  • Vai alla console Google Cloud per visualizzare il registro e l'immagine.

  • Esegui gcloud container images list-tags per visualizzare il tag immagine e il digest generato automaticamente:

    gcloud container images list-tags HOSTNAME/PROJECT-ID/IMAGE

    L'output del comando è simile al seguente:

    DIGEST        TAGS        TIMESTAMP
44bde...      test        2017-..-..

Pull delle immagini da un registro

Per eseguire il pull di un'immagine è necessario il Visualizzatore oggetti Storage per il bucket di archiviazione del Registro di sistema o un ruolo con le stesse autorizzazioni.

Per eseguire il pull da Container Registry, utilizza il comando:

docker pull HOSTNAME/PROJECT-ID/IMAGE:TAG

o

docker pull HOSTNAME/PROJECT-ID/IMAGE@IMAGE_DIGEST

dove:

  • HOSTNAME è elencato in Posizione nella console. È una delle quattro opzioni: gcr.io, us.gcr.io, eu.gcr.io o asia.gcr.io.
  • PROJECT-ID è l'ID progetto della console Google Cloud. Se l'ID progetto contiene i due punti (:), consulta Progetti con ambito di dominio.
  • IMAGE è il nome dell'immagine in Container Registry.
  • TAG è il tag applicato all'immagine. In un registry, i tag sono univoci per un'immagine.
  • IMAGE_DIGEST è il valore hash sha256 dei contenuti dell'immagine. Nella console Google Cloud, fai clic sull'immagine specifica per visualizzarne i metadati. La digest è indicata come Digest immagine.

Per ottenere il comando pull per un'immagine specifica:

  1. Fai clic sul nome di un'immagine per accedere al registro specifico.

  2. Nel Registro di sistema, seleziona la casella accanto alla versione dell'immagine di cui vuoi eseguire il pull.

  3. Fai clic su MOSTRA COMANDO nella parte superiore della pagina.

  4. Copia il comando pull, che identifica l'immagine usando il tag o il digest.

Passaggi successivi