Eseguire il push e il pull delle immagini

Questa pagina descrive come eseguire il push e il pull delle immagini dei container con Docker. Fornisce inoltre informazioni su come estrarre le immagini con lo strumento crictl se stai risolvendo problemi in Google Kubernetes Engine.

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

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

Prima di iniziare

  1. Se il repository di destinazione non esiste, creane uno nuovo.
  2. Devi disporre almeno dell'accesso come autore di Artifact Registry al repository.
  3. Installa Docker se non è già installato.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per spingere e estrarre le immagini, chiedi all'amministratore di concederti i seguenti ruoli IAM nel repository:

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

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

Autenticazione in un repository

Devi autenticarti nei repository ogni volta che utilizzi Docker o un altro client di terze parti con un repository Docker. Questa sezione fornisce un breve riepilogo di ciò che ti serve per eseguire l'autenticazione. Per istruzioni dettagliate, consulta Configurare l'autenticazione per Docker.

Utilizzo di uno strumento di assistenza per le credenziali

Per l'assistente per le credenziali gcloud CLI o per l'assistente per le credenziali autonomo, gli host Artifact Registry che utilizzi devono essere presenti nel file di configurazione di 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 quando esiste un numero elevato di registry configurati. Per ridurre al minimo il numero di registri nel file di configurazione, aggiungi al file gli host di cui hai bisogno.

Per verificare quali host sono configurati, esegui il comando seguente per visualizzare i contenuti del file di configurazione:

  • Linux: cat ~/.docker/config.json
  • Windows: type %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 lo strumento di assistenza per le 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 è presente nell'elenco, esegui di nuovo lo strumento di assistenza per le credenziali per aggiungerlo. Ad esempio, il seguente comando aggiunge us-west1-docker.pkg.dev.

  • Assistente per le credenziali dell'interfaccia a riga di comando gcloud:

    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 tramite token di accesso, genera un token e utilizzalo come password con il comando docker login. I token sono validi per 60 minuti, quindi dovresti autenticarti poco prima di taggare, inviare o estrarre le immagini.

L'esempio seguente genera un token di accesso utilizzando l'appropriazione di identità dell'account di servizio e poi si autentica 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 disponi delle autorizzazioni per rubare l'identità di un account di servizio, puoi attivare l'account di servizio nella sessione della CLI gcloud e ottenere un token. Per maggiori dettagli, consulta le istruzioni per configurare l'autenticazione tramite token di accesso.

Utilizzo di una chiave dell'account di servizio

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

Ad esempio, il seguente comando utilizza la chiave dell'account di servizio codificata in base64 nel file key.json per autenticarsi 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 configurare l'autenticazione con la chiave dell'account di servizio.

Push di un'immagine

Modalità del 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 è attivata 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 che esegui il push nel repository. Per ulteriori informazioni su digest delle immagini, tag e immutabilità dei tag, consulta Versioni delle immagini 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.

Tagging dell'immagine locale

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

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

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

    Sostituisci i seguenti valori:

    • LOCATION è la località regionale o multiregionale del repository in cui è archiviata l'immagine.
    • PROJECT-ID è il tuo ID progetto della console Google Cloud. Se l'ID progetto contiene due punti (:), consulta Progetti basati sul 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, prendiamo in considerazione un'immagine con le seguenti caratteristiche:

    • Posizione del repository: us-west1
    • Nome del repository: my-repo
    • ID progetto: my-project
    • Nome immagine locale: my-image
    • Nome immagine target: test-image

    Il nome dell'immagine per questo esempio è:

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

    Per informazioni dettagliate sul formato del nome dell'immagine, inclusa la gestione dei progetti a livello di dominio, consulta Nomi di repository e immagini.

  3. Tagga 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 locale e TAG con il tag. Se non specifichi un tag, Docker applica il tag predefinito latest.

    Se l'impostazione dei tag immagine immutabili è attivata, 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, utilizza il seguente comando se l'immagine locale my-image si trova nella directory corrente:

    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 nel file di configurazione di Docker.

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

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

    Questo comando spinge l'immagine con il tag latest. Se vuoi spingere 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 caricato l'immagine, puoi:

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

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

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

    L'esempio di output seguente mostra digest di immagini troncati, ma il comando restituisce sempre il digest completo dell'immagine.

     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

Estrazione di immagini con Docker

Modalità del repository: standard, remoto, 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 nel file di configurazione di 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 località regionale o multiregionale del repository in cui è archiviata l'immagine.
    • PROJECT è il tuo ID progetto della console Google Cloud. Se l'ID progetto contiene due punti (:), consulta Progetti basati sul dominio.
    • PROJECT è il tuo ID progetto della console Google Cloud.
    • REPOSITORY è il nome del repository in cui è archiviata l'immagine.
    • IMAGE è il nome dell'immagine nel repository.
    • TAG è il tag della versione dell'immagine che vuoi estrarre.
    • IMAGE-DIGEST è il valore dell'hash SHA256 dei contenuti dell'immagine. Ogni versione di un'immagine ha un digest univoco. Nella console Google Cloud, fai clic sull'immagine specifica per visualizzarne i metadati. Il digest è indicato come Digest immagine.

    Ad esempio, prendiamo in considerazione un'immagine con le seguenti caratteristiche:

    • Posizione del repository: us-west1
    • Nome del repository: my-repo
    • ID progetto: my-project
    • Nome dell'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, questo la scarica e la memorizza nella cache dall'origine a monte se non esiste una copia memorizzata nella cache.

Se richiedi un'immagine da un repository virtuale, Artifact Registry cerca l'immagine richiesta nei repository a monte. 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 in questi repository. Poiché hanno entrambi lo stesso valore di priorità, Artifact Registry può scegliere di pubblicare 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 elemento archiviato se nessuno degli altri repository a monte lo ha.

Estrarre immagini con crictl

crictl è uno strumento a riga di comando utile per gli sviluppatori di runtime CRI per eseguire il debug del loro runtime senza dover configurare i componenti di Kubernetes. Se i tuoi nodi Google Kubernetes Engine utilizzano un runtime containerd, puoi estrarre le 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. Esegui SSH su il nodo di cui stai cercando di risolvere il problema.

  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. Estrai l'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 è il seguente:

    Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5

Passaggi successivi