Eseguire il push e il pull delle immagini

Questa pagina descrive il push e il pull delle immagini container con Docker. Fornisce anche 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, vedi Eseguire il deployment in Google Cloud. Google Cloud

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

Prima di iniziare

  1. Se il repository di destinazione non esiste, creane uno nuovo.
  2. Devi avere almeno l'accesso come Writer di Artifact Registry al repository.
  3. Per eseguire il push delle immagini con Docker, installa Docker se non è già installato.
  4. Per eseguire il push delle immagini con Podman, installa Podman.
  5. Installa Google Cloud CLI 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.

Autenticarsi 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 autenticarti correttamente. Per istruzioni dettagliate, vedi Configurare l'autenticazione per Docker.

Utilizzare un helper per le credenziali

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

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

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 l'helper 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 l'helper per le credenziali per aggiungerlo. Ad esempio, il comando seguente aggiunge us-west1-docker.pkg.dev.

  • Helper per le credenziali gcloud CLI:

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

  • Helper per le credenziali autonomo

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

Utilizzare 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 autenticarti poco prima di taggare, eseguire il push o il pull delle immagini.

L'esempio seguente genera un token di accesso utilizzando l'assunzione dell'identità account di servizio e poi esegue l'autenticazione in Artifact Registry. Per generare un token in questo modo, devi disporre delle autorizzazioni nel ruolo Service Account Token Creator (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 assumere l'identità di un account di servizio, puoi attivare il account di servizio nella sessione gcloud CLI e poi ottenere un token. Per i dettagli, consulta le istruzioni per configurare l'autenticazione con token di accesso.

Utilizzare una chiave del account di servizio

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

Ad esempio, il comando seguente utilizza la chiave account di servizio con codifica 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 i dettagli, consulta le istruzioni per configurare l'autenticazione con chiave del service account.

Eseguire il push di un'immagine con Docker

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 saperne di più su digest, tag e immutabilità dei tag delle immagini , vedi 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 chunked uploads. 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 di un nome immagine completo è:

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

    Sostituisci i seguenti valori:

    • LOCATION è la località regionale o multi-regionale del repository in cui è archiviata l'immagine.
    • PROJECT-ID è l'ID progetto della Google Cloud console project ID. 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:

    • Località del repository: us-west1
    • Nome del repository: my-repo
    • ID progetto: my-project
    • Nome dell'immagine locale: my-image
    • Nome dell'immagine di destinazione: 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 basati sul dominio, vedi 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 predefinito latest.

    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, 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 a l comando:

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

Eseguire il push dell'immagine con tag 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 tuo file di configurazione di Docker.

  2. Esegui il push dell'immagine con tag 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 e il digest generato automaticamente dell'immagine:

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

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

     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

Eseguire il push di un'immagine con Podman

Puoi eseguire il push di un'immagine container da Podman ad Artifact Registry.

  1. Crea l'immagine con Podman utilizzando il seguente comando: 

     podman build -t IMAGE:latest .

  2. Tagga l'immagine Podman locale per Artifact Registry.

    Utilizza il percorso completo di Artifact Registry per il tag. Il formato è lo stesso di Docker: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE:TAG

    Esegui il comando seguente:

     podman tag IMAGE-NAME LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY_NAME/PODMAN-IMAGE:TAG

  3. Autentica Podman con Artifact Registry. Per utilizzarlo con l'helper per le credenziali, esegui il comando seguente:

     gcloud auth configure-docker LOCATION-docker.pkg.dev

    Se Podman non riesce a ottenere le credenziali automaticamente, puoi anche autenticarti con un token di accesso. Esegui il comando seguente:

     gcloud auth print-access-token | podman login -u oauth2accesstoken --password-stdin LOCATION-docker.pkg.dev

  4. Esegui il push dell'immagine con tag in Artifact Registry:

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

    Assicurati che il tag corrisponda esattamente a quello utilizzato per taggare l'immagine Podman locale.

Eseguire il 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 tuo 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 multi-regionale del repository in cui è archiviata l'immagine.
    • PROJECT è l'ID progetto della Google Cloud console project ID. Se l'ID progetto contiene due punti (:), consulta Progetti basati sul dominio.
    • PROJECT è l'ID progetto della Google Cloud console project ID.
    • 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 Google Cloud console, fai clic sull'immagine specifica per visualizzarne i metadati. Il digest è elencato come Digest immagine.

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

    • Località 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, 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ù 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 sia secondary-repo2 hanno la priorità impostata su 80. Se un'immagine richiesta non è disponibile in main-repo, Artifact Registry cerca questi repository successivamente. Poiché entrambi 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 pubblicherà un artefatto archiviato se nessuno degli altri repository upstream lo ha.

Eseguire il pull 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 di Kubernetes. Se i tuoi nodi 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 Google Cloud console, vai alla pagina Istanze VM.

    Vai a Istanze VM

  2. Esegui SSH nel 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