Questa pagina descrive i digest delle immagini, inclusi che cosa sono, come trovarli e come imporne l'utilizzo nei cluster Kubernetes. Questa pagina è rivolta a sviluppatori e operatori che creano ed eseguono il deployment di immagini contenitore.
Un digest dell'immagine del container identifica un'immagine del container in modo univoco e immutabile. Quando esegui il deployment delle immagini tramite digest, eviti i lati negativi del deployment tramite tag immagine.
I comandi in questa pagina presuppongono che tu abbia accesso a un sistema operativo Linux o macOS
dell'ambiente shell con strumenti come
Google Cloud CLI
Docker, cURL
jq
,
e
pack
è già installata. In alternativa, puoi utilizzare Cloud Shell, in cui questi strumenti sono preinstallati.
Immagini container e tag immagine
Quando lavori con le immagini container, devi fare riferimento alle immagini che
che usi.
I tag immagine
sono un modo comune per fare riferimento a revisioni diverse di un'immagine. Un approccio comune è taggare le immagini con un identificatore di versione in fase di compilazione. Ad esempio:
v1.0.1
potrebbe fare riferimento a una versione che chiami 1.0.1
.
I tag semplificano la ricerca delle revisioni delle immagini grazie a stringhe leggibili da una persona. Tuttavia, sono riferimenti mutabili, il che significa che l'immagine a cui fa riferimento un tag può come illustrato nel diagramma seguente:
Come mostrato nel diagramma precedente, se pubblichi una nuova immagine utilizzando lo stesso tag di un'immagine esistente, il tag smette di puntare all'immagine esistente e inizia a puntare alla nuova immagine.
Svantaggi dei tag immagine
Poiché i tag sono mutabili, presentano i seguenti svantaggi se li utilizzi per eseguire il deployment di un'immagine:
In Kubernetes, il deployment per tag può comportare risultati imprevisti. Per Ad esempio, supponiamo di avere una risorsa Deployment esistente fa riferimento a un'immagine container tramite il tag
v1.0.1
. Per correggere un bug o apportare una piccola modifica, il processo di compilazione crea una nuova immagine con lo stesso tagv1.0.1
. I nuovi pod creati dalla tua risorsa Deployment possono finire per utilizzare o la nuova immagine, anche se non modifichi il deployment le specifiche delle risorse. Il problema riguarda anche altri prodotti Kubernetes di risorse come StatefulSet, DaemonSet, ReplicaSet e Job.Se utilizzi strumenti per scansionare o analizzare le immagini, i risultati di questi strumenti sono validi solo per l'immagine scansionata. Per assicurarti di eseguire il deployment dell'immagine sottoposta a scansione, non puoi fare affidamento sul tag perché l'immagine a cui fa riferimento il tag potrebbe essere cambiata.
Se utilizzi Autorizzazione binaria con Google Kubernetes Engine (GKE), il deployment basato su tag non è consentito perché è impossibile determinare l'immagine esatta utilizzata quando viene creato un pod.
Quando esegui il deployment delle immagini, puoi utilizzare un digest di immagini per evitare svantaggi dell'uso dei tag. Se vuoi, puoi comunque aggiungere tag alle immagini, ma non è obbligatorio.
Struttura di un'immagine
Un'immagine è costituita dai seguenti componenti:
- Un manifesto delle immagini
- Un oggetto di configurazione
- Un array di uno o più livelli del file system
- Un'etichetta facoltativa indice immagine
Questi componenti sono illustrati nel seguente diagramma:
L'immagine precedente mostra ulteriori dettagli sui componenti dell'immagine:
- Il file manifest immagine è un documento JSON che contiene un riferimento di configurazione, i livelli del file system e i metadati facoltativi.
- Il manifest dell'immagine fa riferimento all'oggetto di configurazione e a ciascuno dei livelli del sistema di file utilizzando i relativi attributi
digest
. Il valore di un L'attributodigest
è un hash crittografico dei contenuti che il digest e viene calcolata in genere utilizzando SHA-256 dell'algoritmo. - I valori digest vengono utilizzati per creare indirizzi immutabili al di oggetti strutturati. Questo processo è chiamato archiviazione con indirizzamento dei contenuti, e che puoi recuperare manifest di immagini, indici di immagini di configurazione e strati in base alle relative sintesi.
- Il digest immagine è l'hash dell'indice delle immagini o del file JSON manifest dell'immagine documento.
- L'oggetto di configurazione è un documento JSON che definisce le proprietà dell'immagine, come l'architettura della CPU, il punto di contatto, le porte esposte e le variabili di ambiente.
- L'array a livello di file system definisce l'ordine di runtime del container
per sovrapporre gli strati. I livelli vengono distribuiti come
file tar, tipicamente compressi utilizzando l'utilità
gzip
. - L'indice facoltativo delle immagini, a volte indicato come
elenco manifest,
fa riferimento a uno o più manifest dell'immagine. Il riferimento è il digest
manifest dell'immagine. Un indice di immagini è utile quando produci più
immagini per diversi
piattaforme,
come le architetture
amd64
earm64
.
Per ulteriori informazioni, consulta la sezione Esplorazione di manifest, digest e tag delle immagini.
Trovare i digest di immagini
Per usare i digest delle immagini per il deployment, devi prima trovare il digest. Poi puoi utilizzare il digest con il comando di deployment o includerlo nel tuo e i file manifest.
Puoi ottenere il digest di un'immagine in diversi modi, a seconda della situazione attuale. Le seguenti sezioni contengono esempi di diversi prodotti e i nostri strumenti.
Nelle sezioni seguenti, esegui i comandi in Cloud Shell o in un
dell'ambiente shell con strumenti come gcloud CLI, Docker, cURL,
e jq
già installati.
Artifact Registry
Per le immagini archiviate in Artifact Registry, puoi utilizzare il comando
gcloud artifacts docker images describe
.gcloud artifacts docker images describe \ LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG \ --format 'value(image_summary.digest)'
Sostituisci quanto segue:
LOCATION
: la posizione regionale o multiregionale del tuo repositoryPROJECT
: il tuo ID progetto Google CloudREPOSITORY
: il nome del repositoryIMAGE
: il nome della tua immagineTAG
: il tag immagine
Container Registry
Per le immagini archiviate in Container Registry, puoi utilizzare il comando
gcloud container images describe
per ottenere il digest di un'immagine specificandone il nome e un tag. Utilizza la--format
flag per visualizzare solo il digest:gcloud container images describe \ gcr.io/google-containers/pause-amd64:3.2 \ --format 'value(image_summary.digest)'
L'output è simile al seguente, anche se il valore del digest potrebbe essere diverso:
sha256:4a1c4b21597c1b4415bdbecb28a3296c6b5e23ca4f9feeb599860a1dac6a0108
Cloud Build
Per le immagini create con
Cloud Build
puoi ottenere il digest dell'immagine utilizzando
Comando gcloud builds describe
con il flag --format
. Questo approccio funziona indipendentemente dal registry
utilizzato per pubblicare l'immagine.
Per una compilazione già completata:
Visualizza un elenco di build per il tuo progetto:
gcloud builds list
Prendi nota di un
BUILD_ID
.Ottieni il digest dell'immagine:
gcloud builds describe BUILD_ID \ --format 'value(results.images[0].digest)'
Sostituisci
BUILD_ID
con l'ID univoco che Cloud Build assegnato alla tua build.
Ottieni il nome e il digest dell'immagine per l'ultima compilazione da Cloud Build per il tuo progetto corrente:
gcloud builds describe \ $(gcloud builds list --limit 1 --format 'value(id)') \ --format 'value[separator="@"](results.images[0].name,results.images[0].digest)'
Se la compilazione ha prodotto più immagini, filtra l'output e ottieni il digest di una delle immagini:
gcloud builds describe BUILD_ID --format json \ | jq -r '.results.images[] | select(.name=="YOUR_IMAGE_NAME") | .digest'
Sostituisci
YOUR_IMAGE_NAME
con il nome di una delle immagini del tuo filecloudbuild.yaml
.Se invii una build a Cloud Build utilizzando Comando
gcloud builds submit
, puoi acquisire il digest dell'immagine dall'output in una variabile di ambiente:IMAGE_DIGEST=$(gcloud builds submit \ --format 'value(results.images[0].digest)' | tail -n1)
Buildpack cloud-native
Se utilizzi Cloud Native Buildpacks e il builder Google Cloud per creare e pubblicare immagini, puoi acquisizione del nome e del digest dell'immagine utilizzando il flag
--quiet
con il comandopack
:pack build --builder gcr.io/buildpacks/builder:v1 --publish --quiet \ LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE \ > image-with-digest.txt
Sostituisci quanto segue:
LOCATION
: la posizione regionale o multiregionale del tuo repositoryPROJECT_ID
: il tuo ID progetto Google CloudREPOSITORY
: il nome del tuo repositoryIMAGE
: il nome dell'immagine
Il file
image-with-digest.txt
contiene il nome e il digest dell'immagine.Utilizza il flag
--tag
se vuoi aggiungere tag all'immagine.
Client Docker
Il comando secondario
manifest
del client a riga di comandodocker
può recuperare manifest e liste di manifest delle immagini dai registry delle immagini dei container.Ottieni il digest dall'elenco manifest dell'immagine
registry.k8s.io/pause:3.9
, per l'architettura della CPUamd64
e Sistema operativolinux
:docker manifest inspect --verbose registry.k8s.io/pause:3.9 | \ jq -r 'if type=="object" then .Descriptor.digest else .[] | select(.Descriptor.platform.architecture=="amd64" and .Descriptor.platform.os=="linux") | .Descriptor.digest end'
L'output è simile al seguente:
sha256:8d4106c88ec0bd28001e34c975d65175d994072d65341f62a8ab0754b0fafe10
Per le immagini archiviate nel tuo Daemon Docker e che sono stati estratti o inviati a un registro di immagini, puoi utilizzare lo strumento a riga di comando Docker per ottenere il digest dell'immagine:
Esegui il pull dell'immagine nel daemon Docker locale:
docker pull docker.io/library/debian:bookworm
Ottieni il digest dell'immagine:
docker inspect docker.io/library/debian:bookworm \ | jq -r '.[0].RepoDigests[0]' \ | cut -d'@' -f2
L'output è simile al seguente, anche se il valore del digest può essere diverso:
sha256:3d868b5eb908155f3784317b3dda2941df87bbbbaa4608f84881de66d9bb297b
Elenca tutte le immagini e i digest nel daemon Docker locale:
docker images --digests
L'output mostra i digest per le immagini che hanno un valore digest. Le immagini hanno un valore digest solo se sono state esportate da un registry delle immagini o importate in un registry delle immagini.
crane
e gcrane
Puoi utilizzare gli strumenti a riga di comando open source
crane
e
gcrane
per recuperare il digest di un'immagine senza estrarla in un demone Docker locale.
Scarica
crane
egcrane
nella directory corrente:VERSION=$(curl -sL https://api.github.com/repos/google/go-containerregistry/releases/latest | jq -r .tag_name) curl -L "https://github.com/google/go-containerregistry/releases/download/${VERSION}/go-containerregistry_$(uname -s)_$(uname -m).tar.gz" | tar -zxf - crane gcrane
Visualizzare i digest delle immagini:
./gcrane digest gcr.io/distroless/static-debian11:nonroot
crane
egcrane
hanno altre funzionalità che non rientrano nell'ambito di questa pagina. Per ulteriori informazioni, consulta la documentazione relativa acrane
egcrane
.
Applicazione dell'uso dei digest delle immagini nei deployment Kubernetes
Se vuoi applicare l'utilizzo dei digest per le immagini di cui esegui il deployment nei tuoi cluster Kubernetes, puoi utilizzare Policy Controller o Open Policy Agent (OPA) Gatekeeper. Policy Controller è creato dal progetto open source OPA Gatekeeper.
Policy Controller e OPA Gatekeeper si basano entrambi sul motore dei criteri OPA. Policy Controller e OPA Gatekeeper offrono Convalida del webhook di ammissione da parte di Kubernetes per applicare i criteri definizioni di risorse personalizzate (CRD) della modelli di vincoli e vincoli.
I modelli di vincolo contengono una logica dei criteri espressa utilizzando una logica di criteri di alto livello un linguaggio dichiarativo chiamato Rego. Di seguito è riportato un modello di vincolo che convalida i container, container init, e container temporanei in una specifica delle risorse Kubernetes, usa immagini con digest:
Il criterio precedente contiene un'espressione regolare come input per il
Funzione re_match
.
Questa espressione regolare corrisponde al digest dell'immagine container e si basa su
il
formato digest nella specifica delle immagini di Open Container Initiative.
I vincoli applicano il criterio alle risorse Kubernetes trovando corrispondenze con
come kind
e namespace
. Il vincolo di esempio riportato di seguito applica il criterio del modello di vincolo a tutte le risorse Pod
nello spazio dei nomi default
.
Dopo aver creato il modello di vincolo e il vincolo, tutti i nuovi pod nel
nome spazio default
devono utilizzare i digest delle immagini per fare riferimento alle immagini container.
Per l'esempio completo, consulta il
criterio imagedigests
nella raccolta di criteri di Gatekeeper.
Informazioni su manifest, digest e tag delle immagini
In questa sezione imparerai a esplorare le immagini esistenti nei registry utilizzando strumenti della riga di comando come curl
e docker
. Esegui i comandi in Cloud Shell o
in un ambiente shell con strumenti come l'interfaccia a riga di comando gcloud, Docker,
cURL e jq
già installati. I comandi seguenti utilizzano immagini pubbliche in
Artifact Registry.
Recupera il manifest dell'immagine
gcr.io/google-containers/pause-amd64:3.2
utilizzando cURL e l'URL del manifest:curl -s https://gcr.io/v2/google-containers/pause-amd64/manifests/3.2
L'output è simile al seguente:
{ "schemaVersion": 2, "mediaType": "application/vnd.docker.distribution.manifest.v2+json", "config": { "mediaType": "application/vnd.docker.container.image.v1+json", "size": 759, "digest": "sha256:80d28bedfe5dec59da9ebf8e6260224ac9008ab5c11dbbe16ee3ba3e4439ac2c" }, "layers": [ { "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip", "size": 296534, "digest": "sha256:c74f8866df097496217c9f15efe8f8d3db05d19d678a02d01cc7eaed520bb136" } ] }
La sezione
config
ha un attributo digest e puoi utilizzare questo valore per recuperare l'oggetto di configurazione. Allo stesso modo, ogni livello ha undigest
che puoi utilizzare per recuperare il file tar per quel livello.Se l'immagine include l'indice immagine facoltativo, una richiesta HTTP
GET
all'URL manifest che utilizza un tag restituisce l'indice immagine anziché il manifest dell'immagine.Recupera l'indice immagine dell'immagine
gcr.io/google-containers/pause:3.2
:curl -s https://gcr.io/v2/google-containers/pause/manifests/3.2
L'output è simile al seguente:
{ "schemaVersion": 2, "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json", "manifests": [ { "mediaType": "application/vnd.docker.distribution.manifest.v2+json", "size": 526, "digest": "sha256:4a1c4b21597c1b4415bdbecb28a3296c6b5e23ca4f9feeb599860a1dac6a0108", "platform": { "architecture": "amd64", "os": "linux" } }, { "mediaType": "application/vnd.docker.distribution.manifest.v2+json", "size": 526, "digest": "sha256:bbb7780ca6592cfc98e601f2a5e94bbf748a232f9116518643905aa30fc01642", "platform": { "architecture": "arm", "os": "linux", "variant": "v7" } }, { "mediaType": "application/vnd.docker.distribution.manifest.v2+json", "size": 526, "digest": "sha256:31d3efd12022ffeffb3146bc10ae8beb890c80ed2f07363515580add7ed47636", "platform": { "architecture": "arm64", "os": "linux" } }, { "mediaType": "application/vnd.docker.distribution.manifest.v2+json", "size": 526, "digest": "sha256:7f82fecd72730a6aeb70713476fb6f7545ed1bbf32cadd7414a77d25e235aaca", "platform": { "architecture": "ppc64le", "os": "linux" } }, { "mediaType": "application/vnd.docker.distribution.manifest.v2+json", "size": 526, "digest": "sha256:1175fd4d728641115e2802be80abab108b8d9306442ce35425a4e8707ca60521", "platform": { "architecture": "s390x", "os": "linux" } } ] }
Filtra il risultato per estrarre il digest dell'immagine per la piattaforma che preferisci. Ottieni il digest del manifest dell'immagine per l'architettura della CPU
amd64
e per il sistema operativolinux
:curl -s https://gcr.io/v2/google-containers/pause/manifests/3.2 | \ jq -r '.manifests[] | select(.platform.architecture=="amd64" and .platform.os=="linux") | .digest'
Il filtro in questo comando imita il modo in cui i runtime dei container, come containerd, scelgono l'immagine corrispondente alla piattaforma di destinazione dall'indice delle immagini.
L'output è simile al seguente:
sha256:4a1c4b21597c1b4415bdbecb28a3296c6b5e23ca4f9feeb599860a1dac6a0108
La digest immagine è il risultato dell'applicazione hash resistente alle collisioni all'indice delle immagini o al manifest dell'immagine, in genere SHA-256 dell'algoritmo.
Ottieni il digest dell'immagine
gcr.io/google-containers/pause-amd64:3.2
:curl -s https://gcr.io/v2/google-containers/pause-amd64/manifests/3.2 \ | shasum -a 256 \ | cut -d' ' -f1
L'output è simile al seguente:
4a1c4b21597c1b4415bdbecb28a3296c6b5e23ca4f9feeb599860a1dac6a0108
Puoi fare riferimento a questa immagine utilizzando il valore digest immagine come segue:
gcr.io/google-containers/pause-amd64@sha256:4a1c4b21597c1b4415bdbecb28a3296c6b5e23ca4f9feeb599860a1dac6a0108
L'utilizzo del archiviazione con indirizzamento dei contenuti , ottieni il manifest dell'immagine utilizzando il digest come riferimento:
curl -s https://gcr.io/v2/google-containers/pause-amd64/manifests/sha256:4a1c4b21597c1b4415bdbecb28a3296c6b5e23ca4f9feeb599860a1dac6a0108
Molti registry di immagini container restituiscono il digest di manifest, indici di immagini, oggetti di configurazione e livelli del file system nell'intestazione
Docker-Content-Digest
in risposta alle richieste HTTPHEAD
. Recupera il digest dell'indice immagine dell'immaginegcr.io/google-containers/pause-amd64:3.2
:curl -s --head https://gcr.io/v2/google-containers/pause/manifests/3.2 \ | grep -i Docker-Content-Digest \ | cut -d' ' -f2
L'output è simile al seguente:
sha256:927d98197ec1141a368550822d18fa1c60bdae27b78b0c004f705f548c07814f
L'intestazione
Docker-Content-Digest
è non obbligatoria dalle specifiche di distribuzione di Open Container Initiative, quindi questo approccio potrebbe non funzionare con tutti i registri di immagini container. Tu puoi usarlo con Artifact Registry e Container Registry.Per recuperare un oggetto di configurazione dell'immagine utilizzando il valore digest da del file manifest dell'immagine:
Ottieni la sintesi della configurazione:
CONFIG_DIGEST=$(curl -s https://gcr.io/v2/google-containers/pause-amd64/manifests/3.2 \ | jq -r '.config.digest')
Utilizza il digest di configurazione per recuperare l'oggetto di configurazione e
jq
per formattare l'output in modo da facilitarne la lettura:curl -sL https://gcr.io/v2/google-containers/pause-amd64/blobs/$CONFIG_DIGEST \ | jq
L'output è simile al seguente:
{ "architecture": "amd64", "config": { "Env": [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ], "Entrypoint": [ "/pause" ], "WorkingDir": "/", "OnBuild": null }, "created": "2020-02-14T10:51:50.60182885-08:00", "history": [ { "created": "2020-02-14T10:51:50.60182885-08:00", "created_by": "ARG ARCH", "comment": "buildkit.dockerfile.v0", "empty_layer": true }, { "created": "2020-02-14T10:51:50.60182885-08:00", "created_by": "ADD bin/pause-amd64 /pause # buildkit", "comment": "buildkit.dockerfile.v0" }, { "created": "2020-02-14T10:51:50.60182885-08:00", "created_by": "ENTRYPOINT [\"/pause\"]", "comment": "buildkit.dockerfile.v0", "empty_layer": true } ], "os": "linux", "rootfs": { "type": "layers", "diff_ids": [ "sha256:ba0dae6243cc9fa2890df40a625721fdbea5c94ca6da897acdd814d710149770" ] } }
a recuperare i livelli del file system utilizzando i valori digest dell'immagine. manifest, procedi nel seguente modo:
Recupera il digest del livello che vuoi recuperare:
LAYER_DIGEST=$(curl -s https://gcr.io/v2/google-containers/pause-amd64/manifests/3.2 \ | jq -r '.layers[0].digest')
Utilizza il digest del livello per recuperare il file tar del livello ed elencare i contenuti:
curl -sL https://gcr.io/v2/google-containers/pause-amd64/blobs/$LAYER_DIGEST \ | tar --list
Questo livello ha un solo file, chiamato
pause
.
Per cercare i tag associati a un digest immagine:
Definisci il digest che vuoi cercare:
IMAGE_DIGEST=$(curl -s https://gcr.io/v2/google-containers/pause-amd64/manifests/3.2 \ | shasum -a 256 \ | cut -d' ' -f1)
La variabile di ambiente
IMAGE_DIGEST
contiene il digest dell'immagine a cui fa riferimento il tag3.2
.Utilizza la endpoint dell'elenco dei tag immagine,
/tags/list
, per elencare le informazioni dei tag ed estrarre i tag per il valore del digest:curl -s "https://gcr.io/v2/google-containers/pause-amd64/tags/list?n=1" \ | jq ".manifest.\"sha256:$IMAGE_DIGEST\".tag"
L'output è simile al seguente:
[ "3.2" ]
ottenere il manifest di un'immagine da un'immagine container Artifact Registry. repository utilizzando cURL, includi token di accesso nell'intestazione della richiesta
Authorization
:curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \ https://LOCATION-docker.pkg.dev/v2/PROJECT_ID/REPOSITORY/IMAGE/manifests/DIGEST
Sostituisci quanto segue:
LOCATION
: la posizione regionale o multiregionale del tuo repositoryPROJECT_ID
: il tuo ID progetto Google CloudREPOSITORY
: il nome del repositoryIMAGE
: il nome dell'immagineDIGEST
: il digest dell'immagine nel formatosha256:DIGEST_VALUE
Passaggi successivi
- Per scoprire di più sulle immagini, consulta Open Container Initiative Formato immagine e Distribuzione specifiche.