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 si concentra sul push e sul pull delle 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 Gestire le immagini.

Prima di iniziare

Assicurati di avere:

  1. Abilitato Container Registry nel progetto.

  2. Docker installato e configurato.

Aggiunta di un registry

A un progetto puoi aggiungere i seguenti registry Container Registry:

Nome host Località di archiviazione
gcr.io Memorizza le immagini in data center negli Stati Uniti
asia.gcr.io Memorizza le immagini nei data center in Asia
eu.gcr.io Memorizza le immagini nei data center all'interno degli stati membri dell'Unione europea
us.gcr.io Memorizza le immagini in data center negli Stati Uniti

Il primo push di un'immagine a un nome host attiva la creazione del registry 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.

Una volta che un host del registry esiste nel tuo progetto, puoi configurare le autorizzazioni sul bucket di archiviazione per controllare l'accesso alle immagini nel registry.

Per aggiungere un registry e configurare le autorizzazioni:

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

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

  2. Esegui il push di un'immagine iniziale sull'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'gcr.io host del registry e l'ID progetto my-project
    • Esegui il push dell'immagine nel registry
    docker pull busybox
docker tag busybox gcr.io/my-project/busybox
docker push gcr.io/my-project/busybox

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

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

Eseguire il push di un'immagine in un registry

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

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

Tempo di caricamento
Le richieste inviate a Container Registry hanno un limite di timeout di 2 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 si avvale di Cloud Storage per la capacità di archiviazione sottostante di ogni registro. A ogni registry si applicano le quote e i limiti di Cloud Storage, inclusa la dimensione massima di 5 TB per un oggetto nello spazio 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

Per eseguire il push di un'immagine è necessario uno dei seguenti ruoli Cloud Storage o un ruolo con le stesse autorizzazioni:

Eseguire il push della prima immagine in un registry nel progetto

Ruolo: Amministratore archiviazione (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 registry. Il ruolo Amministratore Storage dispone delle autorizzazioni necessarie per creare il bucket di archiviazione.

Eseguire il push delle immagini in un registry esistente nel progetto

Ruolo: Storage Legacy Bucket Writer (roles/storage.legacyBucketWriter) nel bucket di archiviazione del registry.

Questo ruolo dispone delle autorizzazioni per eseguire push e pull delle immagini per gli host del registry esistenti nel progetto. Ad esempio, se il tuo progetto contiene solo il registry gcr.io, un utente con il ruolo Scrittore di bucket legacy di archiviazione può inviare immagini a gcr.io, ma non a asia.gcr.io.

Per informazioni su come concedere autorizzazioni a un registry, consulta Configurare il controllo dell'accesso.

Tagga l'immagine locale con il nome del registry

Per taggare un'immagine:

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

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

    1. Scegli un nome host che specifichi la posizione in cui memorizzerai l'immagine.

      • gcr.io ospita le immagini in data center negli Stati Uniti, ma la sede potrebbe cambiare in futuro
      • us.gcr.io ospita le immagini in data center negli 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 le immagini in data center in Asia

      Queste località corrispondono alle regioni con più sedi per i bucket di archiviazione Cloud Storage. Quando esegui il push di un'immagine in un registry con un nuovo nome host, Container Registry crea un bucket di archiviazione nella regione multipla specificata. Questo bucket è lo spazio di archiviazione sottostante per il registro. 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 in Posizione.

    2. Scegli un nome per l'immagine di destinazione, che può essere diverso dal nome dell'immagine sul computer locale. Ad esempio, l'immagine locale potrebbe chiamarsi 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 l'esempio seguente:

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

      La combinazione del nome host, del progetto e dell'immagine di destinazione fornisce il percorso completo dell'immagine da utilizzare per il tagging:

      gcr.io/my-project/web-site

      Se l'ID progetto contiene due punti (:), consulta Progetti basati sul dominio.

  3. Contrassegna l'immagine locale con 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.
    • HOSTNAME è l'host del registry che hai scelto nel passaggio 2.
    • PROJECT è l'ID progetto Google Cloud.
    • TARGET-IMAGE è il nome dell'immagine quando è archiviata in Container Registry.
    • TAG è il tag che vuoi associare a questa versione dell'immagine.

    Ad esempio, questo comando contrassegna 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 predefinito latest. Poiché latest è un tag predefinito, rappresenta la versione dell'immagine con il tag latest più recente e non necessariamente la versione più recente di un'immagine.

Docker assegna un tag all'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 per Container Registry.

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

    Esegui il seguente 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 con il tag latest.

    Ad esempio, questo comando spinge l'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 in un host del registry che non esiste ancora nel tuo progetto, Container Registry crea un bucket di archiviazione per l'host del registry.

Per visualizzare l'immagine che hai inviato:

  • Vai alla console Google Cloud per visualizzare il registry 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-..-..

Estrazione di immagini da un registry

Per estrarre un'immagine è necessario il ruolo Visualizzatore oggetti archiviazione per il bucket di archiviazione del registry 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 sia elencato in Posizione nella console. Si tratta di 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 due punti (:), consulta Progetti basati sul 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 dell'hash SHA256 dei contenuti dell'immagine. Nella console Google Cloud, fai clic sull'immagine specifica per visualizzarne i metadati. Il digest è indicato come Digest immagine.

Per ottenere il comando pull per un'immagine specifica:

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

  2. Nel registry, seleziona la casella accanto alla versione dell'immagine che vuoi recuperare.

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

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

Passaggi successivi