Questo documento descrive le sintesi delle immagini, spiegando cosa sono le sintesi delle immagini, come trovarle e come applicarne l'utilizzo nei cluster Kubernetes. Questo documento è rivolto agli sviluppatori e agli operatori che creano ed eseguono il deployment di immagini container.
Un digest dell'immagine container identifica in modo univoco e immutabile un'immagine container. Quando esegui il deployment delle immagini tramite digest, eviterai gli svantaggi del deployment tramite tag immagine.
I comandi in questo documento presuppongono che tu abbia accesso a un ambiente shell Linux o macOS con strumenti quali Google Cloud CLI, Docker, cURL, jq
e pack
già installati. In alternativa, puoi utilizzare Cloud Shell, in cui questi strumenti sono preinstallati.
Immagini container e tag immagine
Quando lavori con le immagini container, devi trovare un modo per fare riferimento alle immagini che utilizzi.
I tag immagine sono un modo comune per fare riferimento a diverse revisioni di un'immagine. Un approccio comune è taggare le immagini con un identificatore di versione al momento della build. 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, i tag sono riferimenti mutabili, il che significa che l'immagine a cui fa riferimento un tag può cambiare, come illustrato nel seguente diagramma:
Come mostra il diagramma precedente, se pubblichi una nuova immagine utilizzando lo stesso tag di un'immagine esistente, il tag non punta più all'immagine esistente e inizia a indirizzare alla nuova immagine.
Svantaggi dei tag immagine
I tag sono modificabili, quindi presentano i seguenti svantaggi quando li utilizzi per eseguire il deployment di un'immagine:
In Kubernetes, il deployment per tag può produrre risultati imprevisti. Ad esempio, supponiamo di avere una risorsa Deployment esistente che 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 l'immagine precedente o quella nuova, anche se non modifichi la specifica della risorsa Deployment. Il problema si applica anche ad altre risorse Kubernetes come StatefulSet, DaemonSet, ReplicaSet e Job.Se utilizzi strumenti per la scansione o l'analisi delle immagini, i risultati di questi strumenti sono validi solo per l'immagine scansionata. Per assicurarti di eseguire il deployment dell'immagine analizzata, 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 esattamente l'immagine utilizzata al momento della creazione di un pod.
Quando esegui il deployment delle immagini, puoi utilizzare un digest immagine per evitare gli svantaggi dell'utilizzo dei tag. Se vuoi, puoi comunque aggiungere tag alle immagini, ma non devi farlo.
Struttura di un'immagine
Un'immagine è costituita dai seguenti componenti:
- Un manifest di immagine
- Un oggetto di configurazione
- Un array di uno o più livelli di file system
- Un indice immagine facoltativo
Questi componenti sono illustrati nel seguente diagramma:
L'immagine precedente mostra ulteriori dettagli sui componenti delle immagini:
- Il manifest dell'immagine è un documento JSON che contiene un riferimento all'oggetto di configurazione, ai livelli del file system e ai metadati facoltativi.
- Il file manifest dell'immagine fa riferimento all'oggetto di configurazione e a ciascuno dei livelli del file system utilizzando i relativi attributi
digest
. Il valore di un attributodigest
è un hash crittografico dei contenuti a cui fa riferimento il digest, in genere calcolato utilizzando l'algoritmo SHA-256. - I valori digest vengono utilizzati per creare indirizzi immutabili agli oggetti. Questo processo è chiamato archiviazione con indirizzamento dei contenuti e significa che è possibile recuperare manifest delle immagini, indici delle immagini, oggetti di configurazione e livelli in base alle relative sintesi.
- Il digest dell'immagine è l'hash dell'indice delle immagini o del documento JSON manifest dell'immagine.
- L'oggetto di configurazione è un documento JSON che definisce le proprietà dell'immagine, come l'architettura della CPU, il punto di ingresso, le porte esposte e le variabili di ambiente.
- L'array a livello del file system definisce l'ordine utilizzato dal runtime del container
per sovrapporre i livelli. I livelli sono distribuiti come file tar, in genere compressi utilizzando l'utilità
gzip
. - L'indice delle immagini facoltativo, a volte indicato come elenco manifest, fa riferimento a uno o più manifest delle immagini. Il riferimento è il digest del
manifest dell'immagine. Un indice di immagini è utile quando produci più immagini correlate per diverse piattaforme, come le architetture
amd64
earm64
.
Per ulteriori informazioni, consulta la sezione Esplorazione di manifest, sintesi e tag delle immagini.
Ricerca di sintesi delle immagini
Per usare i digest delle immagini per il deployment, devi prima trovare il digest. Quindi, puoi utilizzare il digest con il comando di deployment o includerlo nei manifest Kubernetes.
Puoi ottenere il digest di un'immagine in diversi modi, a seconda della tua situazione attuale. Le seguenti sezioni contengono esempi di diversi prodotti e strumenti.
Nelle sezioni seguenti, esegui i comandi in Cloud Shell o in un ambiente shell con strumenti già installati gcloud CLI, Docker, cURL e jq
.
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 località a livello di una o più regioni del tuo repositoryPROJECT
: il tuo ID progetto Google CloudREPOSITORY
: il nome del repositoryIMAGE
: il nome della tua immagineTAG
: il tuo 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 specificando il nome e un tag. Utilizza il flag--format
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 immagine utilizzando il
comando gcloud builds describe
con il flag --format
. Questo approccio funziona indipendentemente dal
registro usato per pubblicare l'immagine.
Per una build già completata:
Ottieni un elenco di build per il tuo progetto:
gcloud builds list
Prendi nota di un
BUILD_ID
.Ottieni la sintesi dell'immagine:
gcloud builds describe BUILD_ID \ --format 'value(results.images[0].digest)'
Sostituisci
BUILD_ID
con l'ID univoco assegnato da Cloud Build alla tua build.
Ottieni il nome e il digest dell'immagine più recente da Cloud Build per il tuo progetto attuale:
gcloud builds describe \ $(gcloud builds list --limit 1 --format 'value(id)') \ --format 'value[separator="@"](results.images[0].name,results.images[0].digest)'
Se la build 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 il 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 usi Buildpacks Cloud Native e Google Cloud Builder per creare e pubblicare immagini, puoi acquisire il nome e il 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 località a livello di una o più regioni del tuo repositoryPROJECT_ID
: il tuo ID progetto Google CloudREPOSITORY
: il nome del repositoryIMAGE
: il nome della tua 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 sottocomando
manifest
del client a riga di comandodocker
può recuperare i manifest delle immagini e gli elenchi di manifest dai registri di immagini container.Ottieni il digest dall'elenco manifest dell'immagine
registry.k8s.io/pause:3.9
, per l'architettura della CPUamd64
e il 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 daemon Docker locale e di cui è stato eseguito il pull o il push a un registro di immagini, puoi utilizzare lo strumento a riga di comando Docker per ottenere il digest delle immagini:
Esegui il pull dell'immagine nel daemon Docker locale:
docker pull docker.io/library/debian:bookworm
Ottieni la sintesi 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 le sintesi nel tuo 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 estratte da un registro di immagini o se ne ha eseguito il push a un registro di immagini.
crane
e gcrane
Puoi utilizzare gli strumenti a riga di comando open source crane
e gcrane
per ottenere il digest di un'immagine senza eseguirne il pull su un daemon Docker locale.
Scarica
crane
egcrane
nella tua directory attuale: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
Ottieni sintesi delle immagini:
./gcrane digest gcr.io/distroless/static-debian11:nonroot
crane
egcrane
dispongono di altre funzionalità che non rientrano nell'ambito di questo documento. Per saperne di più, consulta la documentazione dicrane
egcrane
.
Applicazione dell'uso dei digest delle immagini nei deployment Kubernetes
Se vuoi applicare in modo forzato l'uso dei digest per le immagini di cui esegui il deployment nei cluster Kubernetes, puoi utilizzare Policy Controller o Open Policy Agent (OPA) Gatekeeper. Policy Controller è basato sul progetto open source OPA Gatekeeper.
Policy Controller e OPA Gatekeeper si basano entrambi sul motore dei criteri OPA. Policy Controller e OPA Gatekeeper forniscono un Kubernetes webhook di convalida di ammissione per applicare i criteri e definizioni di risorse personalizzate (CRD) per modelli di vincolo e vincoli.
I modelli di vincolo contengono logica dei criteri espressa utilizzando un linguaggio dichiarativo di alto livello chiamato Rego. Di seguito è riportato un modello di vincolo che convalida l'utilizzo di immagini con digest nei container, init container e container temporanei in una specifica delle risorse Kubernetes:
Il criterio precedente contiene un'espressione regolare come input per la funzione re_match
.
Questa espressione regolare corrisponde al digest dell'immagine container e si basa sul formato digest nella specifica dell'immagine della Open Container Initiative.
I vincoli applicano il criterio alle risorse Kubernetes trovando corrispondenze con attributi come kind
e namespace
. Il vincolo di esempio seguente applica il criterio del modello di vincolo a tutte le risorse Pod
nello spazio dei nomi default
.
Dopo aver creato il modello e il vincolo, tutti i nuovi pod nello spazio dei nomi default
devono utilizzare digest delle immagini per fare riferimento alle immagini container.
Per l'esempio completo, consulta il criterio imagedigests
nella libreria dei criteri di Gatekeeper.
Informazioni su manifest, sintesi e tag delle immagini
In questa sezione imparerai a esplorare le immagini esistenti nei registri utilizzando strumenti a riga di comando come curl
e docker
. Esegui i comandi in Cloud Shell o in un ambiente shell con strumenti come gcloud CLI, Docker, cURL e jq
già installati. I comandi seguenti utilizzano immagini pubbliche in Artifact Registry.
Ottieni il manifest dell'immagine
gcr.io/google-containers/pause-amd64:3.2
utilizzando cURL e l'URL 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. Analogamente, ogni livello ha un attributodigest
che puoi utilizzare per recuperare il file tar per quel livello.Se l'immagine include l'indice facoltativo delle immagini, una richiesta
GET
HTTP all'URL del file manifest utilizzando un tag restituisce l'indice dell'immagine anziché il manifest dell'immagine.Ottieni l'indice 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 vuoi. Ottieni il digest del file manifest dell'immagine per l'architettura della CPU
amd64
e 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, ad esempio containerd, selezionano l'immagine corrispondente alla piattaforma di destinazione dall'indice delle immagini.
L'output è simile al seguente:
sha256:4a1c4b21597c1b4415bdbecb28a3296c6b5e23ca4f9feeb599860a1dac6a0108
Il digest immagine è il risultato dell'applicazione di un hash resistente alle collisioni all'indice o al manifest delle immagini, in genere l'algoritmo SHA-256.
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
Con il concetto di archiviazione con indirizzamento dei contenuti, puoi ottenere il manifest dell'immagine utilizzando il digest come riferimento:
curl -s https://gcr.io/v2/google-containers/pause-amd64/manifests/sha256:4a1c4b21597c1b4415bdbecb28a3296c6b5e23ca4f9feeb599860a1dac6a0108
Molti registri di immagini container restituiscono il digest di manifest, indici di immagini, oggetti di configurazione e livelli di file system nell'intestazione
Docker-Content-Digest
in risposta alle richieste HTTPHEAD
. Ottieni il digest dell'indice 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 della Open Container Initiative, quindi questo approccio potrebbe non funzionare con tutti i registri di immagini container. Puoi utilizzarlo con Artifact Registry e Container Registry.Per recuperare un oggetto di configurazione dell'immagine utilizzando il valore del digest dal file manifest dell'immagine, segui questi passaggi:
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 della configurazione per recuperare l'oggetto di configurazione e usa
jq
per formattare l'output al fine di 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" ] } }
Per recuperare i livelli del file system utilizzando i valori digest dal file manifest dell'immagine:
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 l'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" ]
Per ottenere il manifest di un'immagine da un repository di immagini container Artifact Registry utilizzando cURL, includi un 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 località a livello di una o più regioni del tuo repositoryPROJECT_ID
: il tuo ID progetto Google CloudREPOSITORY
: il nome del repositoryIMAGE
: il nome della tua immagineDIGEST
: il digest dell'immagine nel formatosha256:DIGEST_VALUE
Passaggi successivi
- Scopri le best practice per la creazione di container.
- Scopri le best practice per l'utilizzo dei container.
- Per scoprire di più sulle immagini, consulta le specifiche per Formato immagine e Distribuzione di Open Container Initiative.