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

Last reviewed 2023-07-21 UTC

Autopilot Padrão

Neste tutorial, mostramos aos desenvolvedores e operadores que implantam contêineres no Kubernetes como usar resumos de imagens de contêiner para identificar imagens de contêiner. Um resumo de imagem de contêiner identifica uma imagem de contêiner de maneira exclusiva e imutável.

A implantação de imagens de contêiner usando o resumo por imagem oferece vários benefícios em comparação com o uso de tags de imagem. Para mais informações sobre resumos de imagem, consulte o documento complementar sobre como usar resumos de imagem de contêiner antes de continuar este tutorial.

O argumento image para contêineres em uma especificação de pod do Kubernetes aceita imagens com resumos. Esse argumento se aplica a todos os lugares em que você usa uma especificação de pod, como na seção template dos recursos Deployment, StatefulSet, DaemonSet, ReplicaSet, CronJob e Job.

Para implantar uma imagem usando o resumo, use o nome da imagem, seguido por @sha256: e o valor do resumo. Veja a seguir um exemplo de recurso de implantação que usa uma imagem com um resumo:

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@sha256:cb5c1bddd1b5665e1867a7fa1b5fa843a47ee433bbb75d4293888b71def53229
        ports:
        - containerPort: 8080

Uma desvantagem de usar resumos de imagens é que você só sabe o valor dele depois de publicar a imagem em um registro. À medida que você cria novas imagens, o valor de resumo muda, e é necessário ter uma maneira de atualizar os manifestos do Kubernetes a cada implantação.

Neste tutorial, mostramos como você pode usar ferramentas, como Skaffold, kpt, digester, kustomize, gke-deploy e ko, para usar resumos de imagens nos seus manifestos.

recomendações

Neste documento, apresentamos várias maneiras de usar resumos de imagens em implantações do Kubernetes. As ferramentas descritas neste documento são complementares. Por exemplo, use o resultado de uma função kpt com kustomize para criar variantes para ambientes diferentes. O Skaffold pode criar imagens usando ko (em inglês) e implantá-las nos clusters do Kubernetes usando kubectl ou kpt.

As ferramentas são complementares porque executam edições estruturadas com base no modelo de recursos do Kubernetes (KRM, na sigla em inglês). Esse modelo torna as ferramentas conectáveis e é possível evoluir o uso das ferramentas para criar processos e pipelines que ajudam a implantar seus aplicativos e serviços.

Para começar, recomendamos a abordagem que funcione melhor com as ferramentas e os processos atuais:

O Skaffold pode adicionar resumos a referências de imagem. Você ativa essa função com uma pequena alteração na configuração. A adoção do Skaffold oferece benefícios adicionais, como abstrair a forma como diferentes ferramentas criam e implantam imagens de contêiner.
Ao usar a ferramenta de resumo como um webhook de admissão mutante nos clusters do Kubernetes, é possível adicionar resumos a todas as implantações com impacto mínimo nos processos atuais de criação e implantação de imagens de contêiner. O webhook do resumo também simplifica a adoção da autorização binária, porque requer apenas que um rótulo seja adicionado a um namespace.
kpt é uma ótima opção se você precisa de uma ferramenta flexível para manipular manifestos do Kubernetes. A ferramenta de resumo pode ser usada como uma função KRM do lado do cliente em um pipeline kpt.
Se você já usa o kustomize para gerenciar manifestos do Kubernetes em ambientes, recomendamos aproveitar os transformadores de imagem para implantar imagens por resumo.
ko é uma ótima maneira de criar e publicar imagens para aplicativos Go e é usado por projetos de código aberto, como o Knative, Tekton e sigstore.

Se você não usar nenhuma das ferramentas descritas neste documento, recomendamos começar com o Skaffold e o webhook do resumo. O Skaffold é uma ferramenta comum usada por desenvolvedores e equipes de lançamento e tem integração com as outras ferramentas descritas neste tutorial. É possível aproveitar essas opções de integração de acordo com a evolução dos seus requisitos. O webhook do resumo do Kubernetes complementa o Skaffold ativando implantações baseadas em resumo para uma cluster inteiro.

Objetivos

Use o Skaffold para criar e enviar uma imagem e para inserir o nome e o resumo da imagem em um manifesto do Kubernetes.
Use a função de resumo do cliente do resumo e a mutação de admissão para adicionar resumos a imagens em pods do Kubernetes e modelos de pod.
Use setters kpt para substituir uma tag de imagem em um manifesto do Kubernetes por um resumo de imagem.
Use o kustomize para gerar um manifesto do Kubernetes com um resumo da imagem.
Use gke-deploy para resolver uma tag de imagem para um resumo em um manifesto do Kubernetes.
Use ko para criar e enviar uma imagem e inserir o nome e o resumo da imagem em um manifesto do Kubernetes.

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

Artifact Registry

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.

Antes de começar

No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

Acessar o seletor de projetos
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
Ative a API Artifact Registry.
Ative a API
No Console do Google Cloud, ative o Cloud Shell.

Ativar o Cloud Shell
No Cloud Shell, defina o projeto padrão da CLI do Google Cloud:
```
gcloud config set project PROJECT_ID
```
Substitua PROJECT_ID pelo [ID do projeto].
Crie um repositório de imagens de contêiner no Artifact Registry:
```
gcloud artifacts repositories create REPOSITORY \
    --location=LOCATION \
    --repository-format=docker
```
Substitua:
- REPOSITORY: o nome que você quer usar para o repositório, por exemplo, digest-tutorial.
- LOCATION: um local do Artifact Registry, por exemplo, us-central1.
Configure a autenticação no local do Artifact Registry para as ferramentas da CLI usadas neste tutorial:
```
gcloud auth configure-docker LOCATION-docker.pkg.dev
```

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:

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

Clone o repositório do Skaffold Git:

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

Acesse o diretório do exemplo getting-started:
```
cd skaffold/examples/getting-started
```
Confira a tag do Git que corresponde à sua versão do Skaffold:
```
git checkout $(skaffold version)
```
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.
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.
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.
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.

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 resumo 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 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

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

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

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

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.

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

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

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.

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 -

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

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

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.
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.

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
```

Crie um pacote kpt no diretório atual:

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

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

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"

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

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)')

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.

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:

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

Crie um arquivo kustomization.yaml:
```
kustomize init
```

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

Adicione o manifesto como um recurso no arquivo kustomization.yaml:
```
kustomize edit add resource pod.yaml
```

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

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

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

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

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:

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

Instale gke-deploy:

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

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

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

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:

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
```

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

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

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.
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.
  Observação: todas as outras saídasko vão para stderr. Se você quiser capturar o nome e o resumo da imagem, poderá capturar stdout em uma variável de ambiente:
```
IMAGE_AND_DIGEST=$(ko build --base-import-paths ./cmd/ko-example)
```
- 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.

Limpeza

A maneira mais fácil de eliminar o faturamento é excluir o projeto do Google Cloud que você criou para o tutorial. A outra opção é excluir os recursos individuais.

Excluir o projeto

No Console do Google Cloud, acesse a página Gerenciar recursos.
Acessar "Gerenciar recursos"
Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

Excluir os recursos

Se você quiser manter o projeto do Google Cloud usado neste tutorial, exclua os recursos individuais:

No Cloud Shell, exclua os arquivos criados neste tutorial:
```
cd
rm -rf ~/container-image-digests-tutorial
```

Exclua o repositório de imagens do contêiner no Artifact Registry:

gcloud artifacts repositories delete REPOSITORY \
    --location=LOCATION --async --quiet

A seguir

Saiba mais sobre os resumos de imagem de contêiner.
Saiba mais sobre a função KRM do lado do cliente digester e o webhook de mutação do Kubernetes.
Veja Entrega contínua no estilo GitOps com o Cloud Build.
Conheça as práticas recomendadas para a criação de contêineres.
Conheça as práticas recomendadas para operar contêineres.

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

recomendações

Objetivos

Custos

Antes de começar

Como usar o Skaffold

Como usar o resumo

Como usar a função KRM do resumo

Como usar o webhook de admissão do resumo

Como usar setters kpt

Como usar transformadores de imagem do Kustomize

Como usar o gke-deploy

Como usar o ko

Limpeza

Excluir o projeto

Excluir os recursos

A seguir

Como usar o `gke-deploy`

Como usar o `ko`