Utilizzo dei digest delle immagini container nei manifest di Kubernetes

Utilizzo di Skaffold

Skaffold è uno strumento a riga di comando per lo sviluppo e il deployment continui di applicazioni nei cluster Kubernetes.

Utilizza Skaffold per creare un'immagine, eseguirne il push su Artifact Registry e sostituire il valore segnaposto image in un modello di manifest Kubernetes con il nome, il tag e il digest dell'immagine di cui è stato eseguito il push:

1. In Cloud Shell, crea una directory e vai a una directory per archiviare i file che crei in questa sezione:

   mkdir -p ~/container-image-digests-tutorial/skaffold
   cd ~/container-image-digests-tutorial/skaffold
   

2. Clona il repository Git di Skaffold:

   git clone https://github.com/GoogleContainerTools/skaffold.git
   

3. Vai alla directory dell'esempio getting-started:

   cd skaffold/examples/getting-started
   

4. Estrai il tag Git corrispondente alla tua versione di Skaffold:

   git checkout $(skaffold version)
   

5. Visualizza il file di configurazione skaffold.yaml:

   cat skaffold.yaml
   

   Il file è simile al seguente:

   apiVersion: skaffold/v4beta6
   kind: Config
   build:
     artifacts:
     - image: skaffold-example
   manifests:
     rawYaml:
     - k8s-pod.yaml

   La sezione build.artifacts contiene il nome di un'immagine segnaposto. Skaffold cerca questo segnaposto nei file manifest di input.

   La sezione manifests indica a Skaffold di leggere un manifest di input dalla directory corrente con il nome k8s-pod.yaml.

   Per una panoramica di tutte le opzioni disponibili, consulta la documentazione di riferimento skaffold.yaml.

6. Visualizza il modello di manifest Kubernetes:

   cat k8s-pod.yaml
   

   Il file è il seguente:

   apiVersion: v1
   kind: Pod
   metadata:
     name: getting-started
   spec:
     containers:
     - name: getting-started
       image: skaffold-example

   Il valore segnaposto skaffold-example nel campo image corrisponde al valore del campo image nel file skaffold.yaml. Skaffold sostituisce questo valore segnaposto con il nome completo dell'immagine e il digest nell'output di rendering.

7. Crea l'immagine ed eseguine il push in Artifact Registry:

   skaffold build \
       --default-repo=LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY \
       --file-output=artifacts.json \
       --interactive=false \
       --push=true \
       --update-check=false
   

   Questo comando utilizza i seguenti flag:

   • Il flag --file-output specifica il file in cui Skaffold salva le informazioni sull'immagine creata, incluso il valore digest.
   • Il flag --push indica a Skaffold di eseguire il push dell'immagine creata nel registro delle immagini container specificato dal flag --default-repo.
   • I flag --interactive e --update-check sono entrambi impostati su false. Imposta questi flag su false in ambienti non interattivi, come pipeline di build, ma lasciali con i valori predefiniti (true per entrambi i flag) per lo sviluppo locale.

   Se utilizzi Cloud Deploy per il deployment in GKE, utilizza il file del flag --file-output come valore del flag --build-artifacts quando crei una release.

8. Esegui il rendering del manifest Kubernetes espanso con il nome, il tag e il digest dell'immagine container del passaggio precedente:

   skaffold render \
       --build-artifacts=artifacts.json \
       --digest-source=none \
       --interactive=false \
       --offline=true \
       --output=rendered.yaml \
       --update-check=false
   

   Questo comando utilizza i seguenti flag:

   • Il flag --build-artifacts fa riferimento al file di output del comando skaffold build nel passaggio precedente.
   • Il flag --digest-source=none indica che Skaffold utilizza il valore digest dal file fornito nel flag --build-artifacts, anziché risolvere il digest dal registro delle immagini container.
   • Il flag --offline=true indica che puoi eseguire il comando senza richiedere l'accesso a un cluster Kubernetes.
   • Il flag --output specifica il file di output per il manifest sottoposto a rendering.

9. Visualizza il manifest sottoposto a rendering:

   cat rendered.yaml
   

   L'output è simile al seguente:

   apiVersion: v1
   kind: Pod
   metadata:
     name: getting-started
   spec:
     containers:
     - image: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/skaffold-example:TAG@sha256:DIGEST
       name: getting-started

   In questo output, vengono visualizzati i seguenti valori:

   • TAG: il tag assegnato da Skaffold all'immagine.
   • DIGEST: il valore del digest dell'immagine

Utilizzo del digester

Digester aggiunge i digest alle immagini container e init container nelle specifiche del pod e del modello di pod di Kubernetes. Il digest sostituisce i riferimenti alle immagini container che utilizzano tag:

spec:
  containers:
  - image: gcr.io/google-containers/echoserver:1.10

Con riferimenti che utilizzano il digest dell'immagine:

spec:
  containers:
  - image: gcr.io/google-containers/echoserver:1.10@sha256:cb5c1bddd1b5665e1867a7fa1b5fa843a47ee433bbb75d4293888b71def53229

Digester può essere eseguito come webhook di ammissione con mutazione in un cluster Kubernetes o come funzione KRM lato client con gli strumenti a riga di comando kpt o kustomize.

Utilizzare la funzione KRM del digester

1. In Cloud Shell, crea una directory e vai a una directory per archiviare i file che crei in questa sezione:

   mkdir -p ~/container-image-digests-tutorial/digester-fn
   cd ~/container-image-digests-tutorial/digester-fn
   

2. Scarica il programma binario del digester:

   mkdir -p ${HOME}/bin
   export PATH=${HOME}/bin:${PATH}
   DIGESTER_VERSION=$(curl -sL https://api.github.com/repos/google/k8s-digester/releases/latest | jq -r .tag_name)
   curl -L "https://github.com/google/k8s-digester/releases/download/${DIGESTER_VERSION}/digester_$(uname -s)_$(uname -m)" --output ${HOME}/bin/digester
   chmod +x ${HOME}/bin/digester
   

3. Crea un manifest del pod Kubernetes che fa riferimento all'immagine gcr.io/google-containers/echoserver utilizzando il tag 1.10:

   cat << EOF > pod.yaml
   apiVersion: v1
   kind: Pod
   metadata:
     name: echo
   spec:
     containers:
     - name: echoserver
       image: gcr.io/google-containers/echoserver:1.10
       ports:
       - containerPort: 8080
   EOF
   

4. Esegui la funzione KRM digester utilizzando kpt con i manifest nel directory corrente (.):

   kpt fn eval . --exec digester
   

   Quando esegui questo comando, kpt esegue un aggiornamento sul posto dei manifest nella directory corrente. Se vuoi che kpt mostri il manifest aggiornato nella console e lasci invariato il file manifest, aggiungi il flag --output unwrap.

5. Visualizza il manifest aggiornato:

   cat pod.yaml
   

   Il file è il seguente:

   apiVersion: v1
   kind: Pod
   metadata:
     name: echo
   spec:
     containers:
       - name: echoserver
         image: gcr.io/google-containers/echoserver:1.10@sha256:cb5c1bddd1b5665e1867a7fa1b5fa843a47ee433bbb75d4293888b71def53229
         ports:
           - containerPort: 8080

Utilizzo del webhook di ammissione del digester

1. In Cloud Shell, crea una directory e vai a una directory per archiviare i file che crei in questa sezione:

   mkdir -p ~/container-image-digests-tutorial/digester-webhook
   cd ~/container-image-digests-tutorial/digester-webhook
   

2. Crea un cluster Kubernetes locale utilizzando kind:

   kind create cluster
   

   kind è uno strumento a riga di comando per eseguire cluster Kubernetes locali utilizzando Docker.

3. Esegui il deployment del webhook digester:

   DIGESTER_VERSION=$(curl -sL https://api.github.com/repos/google/k8s-digester/releases/latest | jq -r .tag_name)
   kustomize build "https://github.com/google/k8s-digester.git/manifests?ref=${DIGESTER_VERSION}" | kubectl apply -f -
   

4. Crea uno spazio dei nomi Kubernetes denominato digester-demo nel cluster kind:

   kubectl create namespace digester-demo
   

5. Aggiungi l'etichetta digest-resolution: enabled allo spazio dei nomi digester-demo:

   kubectl label namespace digester-demo digest-resolution=enabled
   

   Il webhook digester aggiunge i digest ai pod negli spazi dei nomi con questa etichetta.

6. Crea un manifest di deployment Kubernetes che faccia riferimento all'immagine gcr.io/google-containers/echoserver utilizzando il tag 1.10:

   cat << EOF > deployment.yaml
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: echo-deployment
   spec:
     selector:
       matchLabels:
         app: echo
     template:
       metadata:
         labels:
           app: echo
       spec:
         containers:
         - name: echoserver
           image: gcr.io/google-containers/echoserver:1.10
           ports:
           - containerPort: 8080
   EOF
   

7. Applica il manifest nello spazio dei nomi digester-demo:

   kubectl apply --filename deployment.yaml --namespace digester-demo \
       --output jsonpath='{.spec.template.spec.containers[].image}{"\n"}'
   

   Il flag --output indica a kubectl di restituire il nome dell'immagine alla console, seguito da un carattere di nuova riga. L'output è il seguente:

   gcr.io/google-containers/echoserver:1.10@sha256:cb5c1bddd1b5665e1867a7fa1b5fa843a47ee433bbb75d4293888b71def53229

   Questo output mostra che il webhook del digester ha aggiunto il digest dell'immagine alla specifica del modello di pod nella risorsa Deployment.

8. Elimina il cluster kind per liberare risorse nella sessione Cloud Shell:

   kind delete cluster
   

Utilizzo dei setter kpt

kpt è uno strumento a riga di comando per gestire, manipolare, personalizzare e applicare i manifest delle risorse Kubernetes.

Puoi utilizzare le funzioni KRM create-setters e apply-setters del catalogo delle funzioni kpt per aggiornare i digest delle immagini nei manifest Kubernetes quando crei nuove immagini.

1. In Cloud Shell, crea una directory e vai a una directory per archiviare i file che crei in questa sezione:

   mkdir -p ~/container-image-digests-tutorial/kpt
   cd ~/container-image-digests-tutorial/kpt
   

2. Crea un pacchetto kpt nella directory corrente:

   kpt pkg init --description "Container image digest tutorial"
   

3. Crea un manifest del pod Kubernetes che fa riferimento all'immagine gcr.io/google-containers/echoserver utilizzando il tag 1.10:

   cat << EOF > pod.yaml
   apiVersion: v1
   kind: Pod
   metadata:
     name: echo
   spec:
     containers:
     - name: echoserver
       image: gcr.io/google-containers/echoserver:1.10
       ports:
       - containerPort: 8080
   EOF
   

4. Utilizza kpt per creare un setter denominato echoimage per il campo manifest, dove il valore esistente è gcr.io/google-containers/echoserver:1.10:

   kpt fn eval . \
       --image gcr.io/kpt-fn/create-setters@sha256:0220cc87f29ff9abfa3a3b5643aa50f18d355d5e9dc9e1f518119633ddc4895c \
       -- "echoimage=gcr.io/google-containers/echoserver:1.10"
   

5. Visualizza il manifest:

   cat pod.yaml
   

   Il file è il seguente:

   apiVersion: v1
   kind: Pod
   metadata:
     name: echo
   spec:
     containers:
     - name: echoserver
       image: gcr.io/google-containers/echoserver:1.10 # kpt-set: ${echoimage}
       ports:
       - containerPort: 8080

6. Ottieni il valore digest dell'immagine container:

   DIGEST=$(gcloud container images describe \
       gcr.io/google-containers/echoserver:1.10 \
       --format='value(image_summary.digest)')
   

7. Imposta il nuovo valore del campo:

   kpt fn eval . \
       --image gcr.io/kpt-fn/apply-setters@sha256:4d4295727183396f0c3c6a75d2560254c2f9041a39e95dc1e5beffeb49cc1a12 \
       -- "echoimage=gcr.io/google-containers/echoserver:1.10@$DIGEST"
   

   Quando esegui questo comando, kpt esegue una sostituzione sul posto del valore del campo image nel manifest.

8. Visualizza il manifest aggiornato:

   cat pod.yaml
   

   Il file è il seguente:

   apiVersion: v1
   kind: Pod
   metadata:
     name: echo
   spec:
     containers:
     - name: echoserver
       image: gcr.io/google-containers/echoserver:1.10@sha256:cb5c1bddd1b5665e1867a7fa1b5fa843a47ee433bbb75d4293888b71def53229 # kpt-set: ${echoimage}
       ports:
       - containerPort: 8080

Utilizzo di trasformatori di immagini kustomize

kustomize è uno strumento a riga di comando che consente di personalizzare i manifest Kubernetes utilizzando overlay, patch e trasformatori.

Puoi utilizzare lo strumento di trasformazione delle immagini kustomize per aggiornare il nome, il tag e il digest dell'immagine nel manifest esistente.

Il seguente snippet kustomization.yaml mostra come configurare il trasformatore di immagini in modo che utilizzi il valore del trasformatore digest per le immagini in cui il valore della specifica del pod image corrisponde al valore del trasformatore name:

images:
- name: gcr.io/google-containers/echoserver
  digest: sha256:cb5c1bddd1b5665e1867a7fa1b5fa843a47ee433bbb75d4293888b71def53229

Per utilizzare un trasformatore di immagini kustomize con un digest dell'immagine, segui questi passaggi:

1. In Cloud Shell, crea una directory e vai a una directory per archiviare i file che crei in questa sezione:

   mkdir -p ~/container-image-digests-tutorial/kustomize
   cd ~/container-image-digests-tutorial/kustomize
   

2. Crea un file kustomization.yaml:

   kustomize init
   

3. Crea un manifest Kubernetes con una specifica del pod che fa riferimento all'immagine gcr.io/google-containers/echoserver utilizzando il tag 1.10:

   cat << EOF > pod.yaml
   apiVersion: v1
   kind: Pod
   metadata:
     name: echo
   spec:
     containers:
     - name: echoserver
       image: gcr.io/google-containers/echoserver:1.10
       ports:
       - containerPort: 8080
   EOF
   

4. Aggiungi il manifest come risorsa nel file kustomization.yaml:

   kustomize edit add resource pod.yaml
   

5. Utilizza un transformer di immagini per aggiornare il digest dell'immagine:

   kustomize edit set image \
       gcr.io/google-containers/echoserver@sha256:cb5c1bddd1b5665e1867a7fa1b5fa843a47ee433bbb75d4293888b71def53229
   

6. Visualizza il transformer di immagini nel file kustomization.yaml:

   cat kustomization.yaml
   

   Il file è il seguente:

   apiVersion: kustomize.config.k8s.io/v1beta1
   kind: Kustomization
   resources:
   - pod.yaml
   images:
   - digest: sha256:cb5c1bddd1b5665e1867a7fa1b5fa843a47ee433bbb75d4293888b71def53229
     name: gcr.io/google-containers/echoserver

7. Visualizza il manifest risultante:

   kustomize build .
   

   L'output è il seguente:

   apiVersion: v1
   kind: Pod
   metadata:
     name: echo
   spec:
     containers:
     - image: gcr.io/google-containers/echoserver@sha256:cb5c1bddd1b5665e1867a7fa1b5fa843a47ee433bbb75d4293888b71def53229
       name: echoserver
       ports:
       - containerPort: 8080

8. Per eseguire il trasformatore kustomize e applicare il manifest risultante a un cluster Kubernetes in un unico passaggio, puoi utilizzare il comando kubectl apply con il flag --kustomize:

   kubectl apply --kustomize .
   

   Se vuoi applicare l'output in un secondo momento, puoi reindirizzare l'output del comando kustomize build a un file.

Uso: gke-deploy

gke-deploy è uno strumento a riga di comando che utilizzi con Google Kubernetes Engine (GKE). gke-deploy esegue il wrapping dello strumento a riga di comando kubectl e può modificare le risorse che crei seguendo le pratiche consigliate di Google.

Se utilizzi i sottocomandi gke-deploy prepare o run, gke-deploy risolve i tag immagine in digest e salva i manifest espansi con i digest delle immagini nel file output/expanded/aggregated-resources.yaml per impostazione predefinita.

Puoi utilizzare gke-deploy run sia per sostituire il tag immagine con un digest sia per applicare il manifest espanso al tuo cluster GKE. Sebbene questo comando sia pratico, ha uno svantaggio: il tag immagine viene sostituito al momento del deployment. L'immagine associata al tag potrebbe essere cambiata nel periodo di tempo tra la decisione di eseguire il deployment e l'esecuzione del deployment, con conseguente deployment di un'immagine imprevista. Per i deployment in produzione, consigliamo passaggi separati per generare e applicare i manifest.

Per sostituire un tag immagine in un manifest di deployment Kubernetes con il digest dell'immagine:

1. In Cloud Shell, crea una directory e vai a una directory per archiviare i file che crei in questa sezione:

   mkdir -p ~/container-image-digests-tutorial/gke-deploy
   cd ~/container-image-digests-tutorial/gke-deploy
   

2. Installa gke-deploy:

   go install github.com/GoogleCloudPlatform/cloud-builders/gke-deploy@latest
   

3. Crea un manifest di deployment Kubernetes che faccia riferimento all'immagine gcr.io/google-containers/echoserver utilizzando il tag 1.10:

   cat << EOF > deployment.yaml
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: echo-deployment
   spec:
     selector:
       matchLabels:
         app: echo
     template:
       metadata:
         labels:
           app: echo
       spec:
         containers:
         - name: echoserver
           image: gcr.io/google-containers/echoserver:1.10
           ports:
           - containerPort: 8080
   EOF
   

4. Genera un manifest espanso basato sul manifest deployment.yaml:

   gke-deploy prepare \
       --filename deployment.yaml \
       --image gcr.io/google-containers/echoserver:1.10 \
       --version 1.10
   

5. Visualizza il manifest espanso:

   cat output/expanded/aggregated-resources.yaml
   

   L'output è il seguente:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     labels:
       app.kubernetes.io/managed-by: gcp-cloud-build-deploy
       app.kubernetes.io/version: "1.10"
     name: echo-deployment
     namespace: default
   spec:
     selector:
       matchLabels:
         app: echo
     template:
       metadata:
         labels:
           app: echo
           app.kubernetes.io/managed-by: gcp-cloud-build-deploy
           app.kubernetes.io/version: "1.10"
       spec:
         containers:
         - image: gcr.io/google-containers/echoserver@sha256:cb5c1bddd1b5665e1867a7fa1b5fa843a47ee433bbb75d4293888b71def53229
           name: echoserver
           ports:
           - containerPort: 8080

   Nel manifest espanso, il tag immagine viene sostituito dal digest.

   L'argomento --version che hai utilizzato con il comando gke-deploy imposta il valore dell'etichetta app.kubernetes.io/version nei metadati del deployment e del modello di pod del manifest espanso.

   Per scoprire come utilizzare gke-deploy con Cloud Build, consulta la documentazione di Cloud Build per gke-deploy.

Uso: ko

ko è uno strumento a riga di comando e una libreria per la creazione di immagini container Go e il loro deployment nei cluster Kubernetes. ko crea immagini senza utilizzare il daemon Docker, quindi puoi utilizzarlo in ambienti in cui non puoi installare Docker.

Il comando secondario ko build crea immagini e le pubblica in un registro di immagini container o le carica nel daemon Docker locale.

Il comando secondario ko resolve esegue le seguenti operazioni:

• Identifica le immagini da creare trovando i segnaposto nei campi image dei manifest Kubernetes che fornisci utilizzando l'argomento --filename.
• Crea e pubblica le immagini.
• Sostituisce i segnaposto dei valori image con i nomi e i digest delle immagini create.
• Stampa i manifest espansi.

I sottocomandi ko apply, create e run eseguono gli stessi passaggi di resolve, quindi eseguono kubectl apply, create o run con i manifest espansi.

Per creare un'immagine dal codice sorgente Go e aggiungere il digest dell'immagine a un manifest di deployment Kubernetes, procedi nel seguente modo:

1. In Cloud Shell, crea una directory e vai a una directory per archiviare i file che crei in questa sezione:

   mkdir -p ~/container-image-digests-tutorial/ko
   cd ~/container-image-digests-tutorial/ko
   

2. Scarica ko e aggiungilo al tuo PATH:

   mkdir -p ${HOME}/bin
   export PATH=${HOME}/bin:${PATH}
   KO_VERSION=$(curl -sL https://api.github.com/repos/ko-build/ko/releases/latest | jq -r .tag_name | cut -c2-)
   curl -L "https://github.com/ko-build/ko/releases/download/v${KO_VERSION}/ko_${KO_VERSION}_$(uname -s)_$(uname -m).tar.gz" | tar -zxC ${HOME}/bin ko
   

3. Crea un'app Go con il nome del modulo example.com/hello-world in una nuova directory denominata app:

   mkdir -p app/cmd/ko-example
   
   cd app
   
   go mod init example.com/hello-world
   
   cat << EOF > cmd/ko-example/main.go
   package main
   
   import "fmt"
   
   func main() {
       fmt.Println("hello world")
   }
   EOF
   

4. Definisci il repository di immagini che ko utilizza per pubblicare le immagini:

   export KO_DOCKER_REPO=LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY
   

   Questo esempio utilizza Artifact Registry, ma puoi utilizzare ko con un registro di immagini container diverso.

5. Per creare e pubblicare un'immagine per la tua app, esegui uno dei seguenti passaggi:

   • Crea e pubblica un'immagine per la tua app fornendo il percorso al pacchetto principale di Go:

     ko build --base-import-paths ./cmd/ko-example
     

     L'argomento facoltativo --base-import-paths indica che ko utilizza il nome breve della directory del pacchetto principale come nome dell'immagine.

     ko stampa il nome e il digest dell'immagine in stdout nel seguente formato:

     LOCATION-docker.pkg.dev/PROJECT_ID/ko-example@sha256:DIGEST

     In questo output, DIGEST è il valore del digest dell'immagine.

   • Utilizza ko per sostituire un segnaposto del manifest con il nome e il digest dell'immagine che crea e pubblica:

     1. Crea un manifest del pod Kubernetes. Il manifest utilizza il segnaposto ko://IMPORT_PATH_OF_YOUR_MAIN_PACKAGE come valore del campo image:

        cat << EOF > ko-pod.yaml
        apiVersion: v1
        kind: Pod
        metadata:
          name: ko-example
        spec:
          containers:
          - name: hello-world
            image: ko://example.com/hello-world/cmd/ko-example
        EOF
        

     2. Crea e pubblica un'immagine per la tua app e sostituisci il segnaposto del manifest con il nome e il digest dell'immagine:

        ko resolve --base-import-paths --filename ko-pod.yaml
        

        ko stampa il manifest con il nome e il digest dell'immagine in stdout:

        apiVersion: v1
        kind: Pod
        metadata:
          name: ko-example
        spec:
          containers:
          - name: hello-world
            image: LOCATION-docker.pkg.dev/PROJECT_ID/ko-example@sha256:DIGEST

        In questo output, DIGEST è il valore del digest dell'immagine.