Esegui il push e il pull delle immagini

Questa pagina descrive il push e il pull delle immagini container con Docker. Fornisce inoltre informazioni sul pull di immagini con lo strumento crictl se stai risolvendo problemi in Google Kubernetes Engine.

Per informazioni sul deployment in ambienti di runtime Google Cloud, consulta Eseguire il deployment in Google Cloud.

Per istruzioni su come elencare, taggare ed eliminare le immagini, consulta la pagina Gestire le immagini.

Prima di iniziare

  1. Se il repository di destinazione non esiste, crea un nuovo repository.
  2. Devi disporre almeno dell'access in Writer al repository Artifact Registry.
  3. Installa Docker se non è già installato.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per eseguire il push e il pull delle immagini, chiedi all'amministratore di concederti i seguenti ruoli IAM nel repository:

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.

Autenticazione in un repository

Devi eseguire l'autenticazione nei repository ogni volta che usa Docker o un altro client di terze parti con un repository Docker. Questa sezione fornisce un breve riepilogo di ciò che è necessario per eseguire correttamente l'autenticazione. Per istruzioni dettagliate, vedi Configurare l'autenticazione per Docker.

Utilizzo di un assistente per le credenziali

Per l'helper delle credenziali dell'interfaccia a riga di comando gcloud o l'helper delle credenziali standalone, gli host Artifact Registry che utilizzi devono essere nel file di configurazione Docker.

Artifact Registry non aggiunge automaticamente tutti gli host del registry al file di configurazione di Docker. Il tempo di risposta di Docker è notevolmente più lento se i registri configurati sono numerosi. Per ridurre al minimo il numero di registri nel file di configurazione, aggiungi al file gli host necessari.

Per confermare quali host sono configurati, esegui questo comando per visualizzare i contenuti del file di configurazione:

  • Linux: cat ~/.docker/config.json
  • Windows: cat %USERPROFILE%\.docker\config.json

La sezione credHelpers elenca gli host Docker di Artifact Registry configurati. I nomi host terminano con -docker.pkg.dev. L'esempio seguente mostra alcuni host configurati per l'helper delle credenziali gcloud CLI.

"credHelpers": {
  "asia.gcr.io": "gcloud",
  "eu.gcr.io": "gcloud",
  "gcr.io": "gcloud",
  "marketplace.gcr.io": "gcloud",
  "northamerica-northeast1-docker.pkg.dev": "gcloud",
  "us-central1-docker.pkg.dev": "gcloud",
  "us-east1-docker.pkg.dev": "gcloud",
  "us.gcr.io": "gcloud"
}

Se un host che vuoi utilizzare non è nell'elenco, esegui di nuovo l'helper delle credenziali per aggiungere l'host. Ad esempio, il seguente comando aggiunge us-west1-docker.pkg.dev.

  • Assistente per le credenziali gcloud CLI:

    gcloud auth configure-docker us-west1-docker.pkg.dev

  • Assistente per le credenziali autonomo

    docker-credential-gcr configure-docker us-west1-docker.pkg.dev

Utilizzo di un token di accesso

Per l'autenticazione dei token di accesso, devi generare un token e utilizzarlo come password con il comando docker login. I token sono validi per 60 minuti, quindi devi autenticarti subito prima di taggare, eseguire il push o il pull delle immagini.

L'esempio seguente genera un token di accesso utilizzando l'impersonazione dell'account di servizio, quindi esegue l'autenticazione in Artifact Registry. Per generare un token in questo modo, devi disporre delle autorizzazioni nel ruolo Creatore token account di servizio (roles/iam.serviceAccountTokenCreator).

Linux

gcloud auth print-access-token \
  --impersonate-service-account  ACCOUNT | docker login \
  -u oauth2accesstoken \
  --password-stdin https://LOCATION-docker.pkg.dev

Windows

gcloud auth print-access-token \
--impersonate-service-account  ACCOUNT

ya29.8QEQIfY_...

docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
https://LOCATION-docker.pkg.dev

Se non hai le autorizzazioni per impersonare un account di servizio, puoi attivare l'account di servizio nella sessione gcloud CLI e quindi ottenere un token. Per maggiori dettagli, consulta le istruzioni per configurare l'autenticazione del token di accesso.

Utilizzo di una chiave dell'account di servizio

Per una chiave dell'account di servizio, puoi utilizzare la chiave come password con il comando docker login.

Ad esempio, il comando seguente utilizza la chiave dell'account di servizio con codifica Base64 nel file key.json per l'autenticazione in us-west1-docker.pkg.dev.

Linux

cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-west1-docker.pkg.dev

Windows

docker login -u _json_key_base64 --password-stdin https://us-west1-docker.pkg.dev < key.json

Per maggiori dettagli, consulta le istruzioni per la configurazione dell'autenticazione della chiave dell'account di servizio.

Push di un'immagine

Modalità repository: standard

Per eseguire il push di un'immagine locale in un repository Docker standard, contrassegnala con il nome del repository ed esegui il push dell'immagine.

Se nel repository Docker di Artifact Registry è abilitata l'immutabilità dei tag, un tag deve sempre fare riferimento allo stesso digest immagine nel repository. Non puoi utilizzare il tag su un'altra versione della stessa immagine di cui esegui il push nel repository. Per ulteriori informazioni su sintesi delle immagini, tag e immutabilità dei tag, consulta Versioni immagine container.

Per le immagini di grandi dimensioni si applicano i seguenti limiti:

Tempo di caricamento
Se esegui l'autenticazione in Artifact Registry utilizzando un token di accesso, il token è valido solo per 60 minuti. Se prevedi che il tempo di caricamento supererà i 60 minuti, utilizza un metodo di autenticazione diverso.
Dimensioni dell'immagine
La dimensione massima dell'artefatto è 5 TB.
Artifact 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 Artifact Registry.

Taggare l'immagine locale

  1. Assicurati di aver eseguito l'autenticazione nel repository.

  2. Determina il nome dell'immagine. Il formato del nome completo di un'immagine è:

    LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE

    Sostituisci i seguenti valori:

    • LOCATION è la regione o più regioni località del repository in cui è archiviata l'immagine.

    • PROJECT-ID è l'ID progetto della console Google Cloud. Se l'ID progetto contiene i due punti (":"), vedi Progetti con ambito dominio.

    • REPOSITORY è il nome del repository in cui è archiviata l'immagine.

    • IMAGE è il nome dell'immagine. Può essere diverso dal nome locale dell'immagine.

    Ad esempio, considera un'immagine con le seguenti caratteristiche:

    • Località del repository: us-west1
    • Nome repository: my-repo
    • ID progetto: my-project
    • Nome immagine locale: my-image
    • Nome immagine di destinazione: test-image

    Il nome dell'immagine per questo esempio è:

    us-west1-docker.pkg.dev/my-project/my-repo/test-image

    Per maggiori dettagli sul formato dei nomi delle immagini, compresa la gestione dei progetti con ambito di dominio, consulta Nomi di repository e immagini.

  3. Contrassegna l'immagine locale con il nome del repository.

    docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

    Sostituisci SOURCE-IMAGE con il nome o l'ID immagine dell'immagine locale e TAG con il tag. Se non specifichi un tag, Docker applica il tag latest predefinito.

    Se l'impostazione dei tag immagine immutabili è abilitata, i tag devono essere univoci per ogni versione dell'immagine, incluso il tag latest. Non puoi eseguire il push di un'immagine nel repository se il tag è già utilizzato da un'altra versione della stessa immagine nel repository. Per verificare se l'impostazione è abilitata per il repository, esegui il comando:

    gcloud artifacts repositories describe REPOSITORY \
    --project=PROJECT-ID \
    --location=LOCATION

    Per l'immagine di esempio del passaggio precedente, useresti il seguente comando se l'immagine locale my-image si trova nella directory attuale:

    docker tag my-image us-west1-docker.pkg.dev/my-project/my-repo/test-image

    Se vuoi applicare un tag specifico, utilizza il comando:

    docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

    Per utilizzare il tag staging con l'immagine di esempio, aggiungi :staging al comando:

    docker tag my-image us-west1-docker.pkg.dev/my-project/my-repo/test-image:staging

Esegui il push dell'immagine taggata in Artifact Registry

  1. Assicurati di aver eseguito l'autenticazione nel repository.

    Se hai utilizzato gcloud auth configure-docker o docker-credential-gcr configure-docker per configurare il client Docker, verifica che il nome host di destinazione sia presente nel file di configurazione Docker.

  2. Esegui il push dell'immagine taggata con il comando:

    docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE

    Questo comando esegue il push dell'immagine che ha il tag latest. Se vuoi eseguire il push di un'immagine con un tag diverso, utilizza il comando:

    docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

Quando esegui il push di un'immagine, questa viene archiviata nel repository specificato.

Dopo aver eseguito il push dell'immagine, puoi:

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

  • Esegui il comando gcloud per visualizzare i tag dell'immagine e il digest generato automaticamente:

    gcloud artifacts docker images list \
LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE [--include-tags]

    L'output di esempio seguente mostra i digest dell'immagine troncata, ma il comando restituisce sempre il digest dell'immagine completa.

     IMAGE                                                 DIGEST         CREATE_TIME          UPDATE_TIME
  us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
  us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
  us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:46  2019-04-10T15:08:46

Pull delle immagini con Docker

Modalità repository: standard, remota, virtuale

  1. Assicurati di aver eseguito l'autenticazione nel repository.

    Se hai utilizzato gcloud auth configure-docker o docker-credential-gcr configure-docker per configurare il client Docker, verifica che il nome host di destinazione sia presente nel file di configurazione Docker.

  2. Per eseguire il pull da un repository, utilizza il comando:

    docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

    o

    docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST

    Sostituisci i seguenti valori:

    • LOCATION è la regione o più regioni località del repository in cui è archiviata l'immagine.
    • PROJECT è l'ID progetto della console Google Cloud. Se l'ID progetto contiene i due punti (":"), vedi Progetti con ambito dominio.
    • REPOSITORY è il nome del repository in cui è archiviata l'immagine.
    • IMAGE è il nome dell'immagine nel repository.
    • TAG è il tag della versione dell'immagine di cui vuoi eseguire il pull.
    • IMAGE-DIGEST è il valore hash sha256 dei contenuti dell'immagine. Ogni versione di un'immagine ha un digest immagine univoco. Nella console Google Cloud, fai clic sull'immagine specifica per vedere i relativi metadati. Il digest è elencato come Digest immagine.

    Ad esempio, considera un'immagine con le seguenti caratteristiche:

    • Località del repository: us-west1
    • Nome repository: my-repo
    • ID progetto: my-project
    • Nome immagine: test-image
    • Tag: staging

    Questo comando per eseguire il pull dell'immagine è:

    docker pull us-west1-docker.pkg.dev/my-project/my-repo/test-image:staging

Docker scarica l'immagine specificata.

Se richiedi un'immagine da un repository remoto, il repository remoto scarica e memorizza nella cache l'immagine dall'origine upstream se non esiste una copia memorizzata nella cache.

Se richiedi un'immagine da un repository virtuale, Artifact Registry cerca l'immagine richiesta nei repository upstream. Se richiedi una versione disponibile in più di un repository upstream, Artifact Registry sceglie un repository upstream da utilizzare in base alle impostazioni di priorità configurate per il repository virtuale.

Ad esempio, considera un repository virtuale con le seguenti impostazioni di priorità per i repository upstream:

  • main-repo: priorità impostata su 100
  • secondary-repo1: priorità impostata su 80.
  • secondary-repo2: priorità impostata su 80.
  • test-repo: priorità impostata su 20.

main-repo ha il valore di priorità più alto, quindi il repository virtuale lo cerca sempre per primo.

Sia secondary-repo1 che secondary-repo2 hanno la priorità impostata su 80. Se un'immagine richiesta non è disponibile in main-repo, Artifact Registry cerca successivamente questi repository. Poiché entrambi hanno lo stesso valore di priorità, Artifact Registry può scegliere di gestire un'immagine da uno dei due repository se la versione è disponibile in entrambi.

test-repo ha il valore di priorità più basso e pubblicherà un artefatto archiviato se nessuno degli altri repository upstream lo include.

Pull delle immagini con crictl

crictl è un utile strumento a riga di comando che consente agli sviluppatori di runtime CRI di eseguire il debug del runtime senza dover configurare i componenti di Kubernetes. Se i tuoi nodi di Google Kubernetes Engine utilizzano un runtime containerd, puoi eseguire il pull delle immagini da Artifact Registry utilizzando crictl.

Poiché crictl è principalmente uno strumento per la risoluzione dei problemi, alcuni comandi Docker, come il push o il tagging delle immagini, non sono disponibili.

Per eseguire il pull di un'immagine da Artifact Registry:

  1. Nella console Google Cloud, vai alla pagina Istanze VM.

    Vai a Istanze VM

  2. Accedi tramite SSH al nodo di cui stai eseguendo la risoluzione.

  3. Ottieni un token di accesso per l'autenticazione con il repository.

    curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" -H "Metadata-Flavor: Google"

  4. Esegui il pull dell'immagine utilizzando crictl pull --creds e il valore access_token

    crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

    o

    crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST

    L'output è simile al seguente:

    Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5

Passaggi successivi