Como usar resumos de imagem de contêiner em manifestos do Kubernetes

Como usar o Skaffold

O Skaffold é uma ferramenta de linha de comando para desenvolvimento contínuo e implantação de aplicativos nos clusters do Kubernetes.

Use o Skaffold para criar uma imagem, enviar a imagem para o Artifact Registry e substituir o valor do marcador image em um modelo de manifesto do Kubernetes pelo nome, tag e resumo da imagem enviada:

1. No Cloud Shell, crie e acesse um diretório para armazenar os arquivos criados nesta seção:

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

2. Clone o repositório do Skaffold Git:

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

3. Acesse o diretório do exemplo getting-started:

   cd skaffold/examples/getting-started
   

4. Confira a tag do Git que corresponde à sua versão do Skaffold:

   git checkout $(skaffold version)
   

5. Visualize o arquivo de configuração skaffold.yaml:

   cat skaffold.yaml
   

   O arquivo é semelhante a este:

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

   A seção build.artifacts contém um nome de imagem de marcador de posição. O Skaffold procura esse marcador nos arquivos de manifesto de entrada.

   A seção manifests instrui o Skaffold a ler um manifesto de entrada do diretório atual com o nome k8s-pod.yaml.

   Para uma visão geral de todas as opções disponíveis, consulte a documentação de referência do skaffold.yaml.

6. Veja o modelo de manifesto do Kubernetes:

   cat k8s-pod.yaml
   

   O arquivo é o seguinte:

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

   O valor do marcador skaffold-example no campo image corresponde ao valor do campo image no arquivo skaffold.yaml. O Skaffold substitui esse valor de marcador pelo nome completo da imagem e pelo resumo na saída renderizada.

7. Crie e envie a imagem para o Artifact Registry:

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

   Esse comando usa as seguintes sinalizações:

   • A sinalização --file-output especifica o arquivo em que o Skaffold salva informações sobre a imagem criada, incluindo o valor de resumo.
   • A sinalização --push instrui o Skaffold a enviar a imagem criada ao registro de imagem do contêiner especificado pela sinalização --default-repo.
   • As sinalizações --interactive e --update-check estão definidas como false. Defina essas sinalizações como false em ambientes não interativos, como pipelines de compilação, mas as deixe com os valores padrão (true para as duas sinalizações) para desenvolvimento local.

   Se você usar o Cloud Deploy para implantar no GKE, use o arquivo a partir da sinalização --file-output como o valor da sinalização --build-artifacts ao criar uma versão.

8. Renderize o manifesto expandido do Kubernetes com o nome, a tag e o resumo da imagem do contêiner da etapa anterior:

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

   Esse comando usa as seguintes sinalizações:

   • A sinalização --build-artifacts faz referência ao arquivo de saída do comando skaffold build na etapa anterior.
   • A sinalização --digest-source=none significa que o Skaffold usa o valor de resumo do arquivo fornecido na sinalização --build-artifacts em vez de resolver o resumo do registro de imagem de contêiner.
   • A sinalização --offline=true significa que é possível executar o comando sem exigir o acesso a um cluster do Kubernetes.
   • A sinalização --output especifica o arquivo de saída para o manifesto renderizado.

9. Veja o manifesto renderizado:

   cat rendered.yaml
   

   A saída será assim:

   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
   

   Nesta saída, os seguintes valores são exibidos:

   • TAG: a tag que o Skaffold atribuiu à imagem.
   • DIGEST: o valor do resumo da imagem

Como usar o resumo

O Digester adiciona resumos às imagens de contêiner e inicialização do contêiner nas especificações de modelo de pod e pod do Kubernetes. O resumo substitui as referências da imagem do contêiner que usam tags:

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

Com referências que usam o resumo de imagens:

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

O resumo pode ser executado como um webhook de admissão mutante em um cluster do Kubernetes ou como uma função KRM do lado do cliente com as ferramentas de linha de comando kpt ou kustomize.

Como usar a função KRM do resumo

1. No Cloud Shell, crie e acesse um diretório para armazenar os arquivos criados nesta seção:

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

2. Faça o download do binário do resumo:

   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. Crie um manifesto de pod do Kubernetes que faça referência à imagem gcr.io/google-containers/echoserver usando a 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. Execute a função KRM do resumo usando o kpt com os manifestos no diretório atual (.):

   kpt fn eval . --exec digester
   

   Quando você executa esse comando, o kpt executa uma atualização no local dos manifestos no diretório atual. Se você quiser que o kpt mostre o manifesto atualizado no console e deixe o arquivo de manifesto inalterado, adicione a sinalização --output unwrap.

5. Veja o manifesto atualizado:

   cat pod.yaml
   

   O arquivo é o seguinte:

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

Como usar o webhook de admissão do resumo

1. No Cloud Shell, crie e acesse um diretório para armazenar os arquivos criados nesta seção:

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

2. Crie um cluster local do Kubernetes usando kind:

   kind create cluster
   

   O Kind é uma ferramenta de linha de comando para executar clusters locais do Kubernetes usando o Docker.

3. Implante o webhook do resumo:

   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. Crie um namespace do Kubernetes chamado digester-demo no cluster de tipo:

   kubectl create namespace digester-demo
   

5. Adicione o rótulo digest-resolution: enabled ao namespace digester-demo:

   kubectl label namespace digester-demo digest-resolution=enabled
   

   O webhook do resumo adiciona resumos aos pods nos namespaces com esse rótulo.

6. Crie um manifesto de implantação do Kubernetes que faça referência à imagem gcr.io/google-containers/echoserver usando a 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. Aplique o manifesto no namespace digester-demo:

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

   A sinalização --output instrui kubectl a enviar o nome da imagem para o console, seguido por um caractere de nova linha. A saída é esta:

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

   Esta saída mostra que o webhook do resumo adicionou o resumo da imagem à especificação do modelo do pod no recurso de implantação.

8. Exclua o cluster de tipo para liberar recursos na sessão do Cloud Shell:

   kind delete cluster
   

Como usar setters kpt

O kpt é uma ferramenta de linha de comando para gerenciar, manipular, personalizar e aplicar manifestos de recursos do Kubernetes.

É possível usar as funções KRM create-setters e apply-setters do Catálogo de funções kpt para atualizar os resumos de imagem nos manifestos do Kubernetes ao criar novas imagens.

1. No Cloud Shell, crie e acesse um diretório para armazenar os arquivos criados nesta seção:

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

2. Crie um pacote kpt no diretório atual:

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

3. Crie um manifesto de pod do Kubernetes que faça referência à imagem gcr.io/google-containers/echoserver usando a 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. Use o kpt para criar um setter chamado echoimage para o campo do manifesto, em que o valor atual é 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. Veja o manifesto:

   cat pod.yaml
   

   O arquivo é o seguinte:

   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. Para receber o valor de resumo da imagem do contêiner:

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

7. Defina o novo valor do campo:

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

   Ao executar esse comando, o kpt realiza uma substituição no local do valor do campo image no manifesto.

8. Veja o manifesto atualizado:

   cat pod.yaml
   

   O arquivo é o seguinte:

   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
   

Como usar transformadores de imagem do Kustomize

O kustomize é uma ferramenta de linha de comando que permite personalizar manifestos do Kubernetes usando sobreposições, patches e transformadores.

Use o transformador de imagens do kustomize para atualizar o nome, a tag e o resumo da imagem no manifesto atual.

O snippet kustomization.yaml a seguir mostra como configurar o transformador de imagem para usar o valor digest do transformador para imagens em que o valor image da especificação do pod corresponde ao valor name do transformador:

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

Para usar um transformador de imagem do kustomize com um resumo de imagem, faça o seguinte:

1. No Cloud Shell, crie e acesse um diretório para armazenar os arquivos criados nesta seção:

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

2. Crie um arquivo kustomization.yaml:

   kustomize init
   

3. Crie um manifesto do Kubernetes com uma especificação de pod que referencie a imagem gcr.io/google-containers/echoserver usando a 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. Adicione o manifesto como um recurso no arquivo kustomization.yaml:

   kustomize edit add resource pod.yaml
   

5. Use um transformador de imagem para atualizar o resumo da imagem:

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

6. Visualize o transformador de imagens no arquivo kustomization.yaml:

   cat kustomization.yaml
   

   O arquivo é o seguinte:

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

7. Visualize o manifesto resultante:

   kustomize build .
   

   A saída é esta:

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

8. Para executar o transformador kustomize e aplicar o manifesto resultante a um cluster do Kubernetes em uma única etapa, use o comando kubectl apply com a sinalização --kustomize:

   kubectl apply --kustomize .
   

   Se você quiser aplicar a saída posteriormente, poderá redirecionar a saída do comando kustomize build para um arquivo.

Como usar o gke-deploy

gke-deploy é uma ferramenta de linha de comando que você usa com o Google Kubernetes Engine (GKE). O gke-deploy encapsula a ferramenta de linha de comando kubectl e pode modificar os recursos criados seguindo as práticas recomendadas do Google.

Se você usa os subcomandos gke-deploy prepare ou run, gke-deploy resolve suas tags de imagem para resumir e salva os manifestos expandidos com os resumos de imagem no arquivo output/expanded/aggregated-resources.yaml por padrão.

Use gke-deploy run para substituir a tag de imagem por um resumo e aplicar o manifesto expandido ao cluster do GKE. Esse comando é conveniente, mas há uma desvantagem: a tag de imagem é substituída no momento da implantação. A imagem associada à tag pode ter sido alterada entre o momento em que você decidiu implantá-la e quando foi implantada, resultando na implantação de uma imagem inesperada. Para implantações de produção, recomendamos etapas separadas para gerar e aplicar manifestos.

Para substituir uma tag de imagem em um manifesto de implantação do Kubernetes pelo resumo da imagem, faça o seguinte:

1. No Cloud Shell, crie e acesse um diretório para armazenar os arquivos criados nesta seção:

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

2. Instale gke-deploy:

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

3. Crie um manifesto de implantação do Kubernetes que faça referência à imagem gcr.io/google-containers/echoserver usando a 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. Gere um manifesto expandido com base no manifesto deployment.yaml:

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

5. Veja o manifesto expandido:

   cat output/expanded/aggregated-resources.yaml
   

   A saída é esta:

   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
   

   No manifesto expandido, a tag de imagem é substituída pelo resumo.

   O argumento --version usado com o comando gke-deploy define o valor do rótulo app.kubernetes.io/version na implantação e nos metadados do modelo de pod do manifesto expandido.

   Para saber como usar gke-deploy com o Cloud Build, consulte a documentação do Cloud Build para gke-deploy.

Como usar o ko

ko é uma ferramenta de linha de comando e biblioteca para criar imagens de contêiner Go e implantá-las em clusters do Kubernetes. ko cria imagens sem usar o daemon do Docker para que seja possível usá-lo em ambientes em que não é possível instalar o Docker.

O subcomando ko build cria imagens e as publica em um registro de imagem de contêiner ou as carrega no seu daemon do Docker local.

O subcomando ko resolve faz o seguinte:

• Identifica as imagens a serem criadas encontrando marcadores nos campos image dos manifestos do Kubernetes fornecidos usando o argumento --filename.
• Cria e publica imagens.
• Substitui os marcadores de valor image pelos nomes e resumos das imagens criadas.
• Imprime os manifestos expandidos.

Os subcomandos ko apply, create e run executam as mesmas etapas que resolve e, em seguida, executam kubectl apply, create ou run com os manifestos expandidos.

Para criar uma imagem a partir do código-fonte Go e adicionar o resumo da imagem a um manifesto de implantação do Kubernetes, faça o seguinte:

1. No Cloud Shell, crie e acesse um diretório para armazenar os arquivos criados nesta seção:

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

2. Faça o download de ko e adicione-o ao seu 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. Crie um aplicativo Go com o nome do módulo example.com/hello-world em um novo diretório chamado 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. Defina o repositório de imagens que o ko usa para publicar imagens:

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

   Neste exemplo, usamos o Artifact Registry, mas é possível usar o ko com um registro de imagens de contêiner diferente.

5. Para criar e publicar uma imagem para o aplicativo, siga um destes procedimentos:

   • Crie e publique uma imagem para o aplicativo fornecendo o caminho para seu pacote principal do Go:

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

     O argumento opcional --base-import-paths significa que ko usa o nome abreviado do diretório do pacote principal como o nome da imagem.

     ko imprime o nome da imagem e o resumo para stdout no seguinte formato:

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

     Nessa saída, DIGEST é o valor de resumo da imagem.

   • Use ko para substituir um marcador de manifesto pelo nome e resumo da imagem que ela cria e publica:

     1. Crie um manifesto de pod do Kubernetes. O manifesto usa o marcador ko://IMPORT_PATH_OF_YOUR_MAIN_PACKAGE como valor do 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. Crie e publique uma imagem para o aplicativo e substitua o marcador de posição do manifesto pelo nome e resumo da imagem:

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

        ko imprime o manifesto com o nome da imagem e um resumo para 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
        

        Nessa saída, DIGEST é o valor de resumo da imagem.