Eseguire il push e il pull delle immagini

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

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

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

Prima di iniziare

  1. Se il repository di destinazione non esiste, creane uno nuovo.
  2. Devi disporre almeno dell'accesso di scrittura di Artifact Registry al repository.
  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 Gestisci 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 servirà per eseguire l'autenticazione. Per istruzioni dettagliate, vedi Configurazione dell'autenticazione per Docker.

Utilizzo di un helper delle credenziali

Per l'assistente per le credenziali gcloud CLI o l'assistente per le credenziali autonomo, gli host Artifact Registry utilizzati devono essere presenti nel file di configurazione Docker.

Artifact Registry non aggiunge automaticamente tutti gli host del registro al file di configurazione Docker. Il tempo di risposta di Docker è notevolmente più lento quando è presente un numero elevato di registri configurati. Per ridurre al minimo il numero di registri nel file di configurazione, aggiungi gli host necessari al file.

Per confermare 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 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 è presente nell'elenco, esegui di nuovo l'helper delle credenziali per aggiungerlo. 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 autonome

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

Utilizzo di un token di accesso

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

L'esempio seguente genera un token di accesso utilizzando l'impersonificazione account di servizio e poi 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 disponi delle autorizzazioni per rappresentare un account di servizio, puoi attivare ilaccount di serviziot nella sessionegcloud CLId e poi ottenere un token. Per maggiori dettagli, consulta le istruzioni per configurare l'autenticazione con token di accesso.

Utilizzo di una chiave del account di servizio

Per una chiave account di servizio, utilizzi 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 l'autenticazione a 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 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 digest, tag e immutabilità dei tag delle immagini, 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 posizione regionale o multiregionale del repository in cui è archiviata l'immagine.
    • PROJECT-ID è l'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, considera un'immagine con le seguenti caratteristiche:

    • Posizione del repository: us-west1
    • Nome repository: my-repo
    • ID progetto: my-project
    • Nome dell'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 con ambito 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 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 è 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, utilizzeresti 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 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 con 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 Google Cloud console 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 delle 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

Pull delle immagini con Docker

Modalità 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 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 posizione regionale o multiregionale del repository in cui è archiviata l'immagine.
    • PROJECT è l'ID progetto della console Google Cloud . Se l'ID progetto contiene due punti (:), consulta Progetti basati sul dominio.
    • PROJECT è l'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 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 riepilogo è elencato come Riepilogo immagini.

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

    • Posizione del repository: us-west1
    • Nome 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, il repository remoto scarica e memorizza nella cache l'immagine dalla sorgente 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 esegue la ricerca in questi repository. Poiché hanno 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 servirà un artefatto archiviato se nessuno degli altri repository upstream lo contiene.

Recupero delle immagini con crictl

crictl è uno strumento a riga di comando utile per gli sviluppatori di runtime CRI per eseguire il debug del runtime senza dover configurare i componenti Kubernetes. Se i nodi Google Kubernetes Engine utilizzano un runtime containerd, puoi estrarre 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 risolvendo i problemi.

  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