Migrar do Docker para imagens de nó containerd

Padrão

Nesta página, mostramos como migrar o cluster padrão e os pools de nós do Google Kubernetes Engine (GKE) para imagens de nó que usam o ambiente de execução de contêiner do containerd.

Visão geral

Os nós do Kubernetes usam o ambiente de execução do contêiner para iniciar, gerenciar e interromper contêineres em execução nos pods. O ambiente de execução do containerd é um contêiner padrão do setor compatível com o GKE.

O ambiente de execução do containerd fornece a abstração de camadas que permite a implementação de um conjunto avançado de recursos, como gVisor e streaming de imagem para estender a funcionalidade do GKE. O ambiente de execução do containerd é considerado mais eficiente e seguro do que o ambiente de execução do Docker.

Para migrar o ambiente de execução do contêiner:

Identificar nós que usam o ambiente de execução do Docker
Verificar o impacto da migração
Alterar a imagem do nó

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

Ativar a API Google Kubernetes Engine.

Ativar a API Google Kubernetes Engine

Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando gcloud components update.
Observação: para instalações atuais da CLI gcloud, defina as propriedades compute/region e compute/zone. Ao definir locais padrão, é possível evitar erros na CLI gcloud, como: One of [--zone, --region] must be supplied: Please specify location.

Identificar nós que usam o ambiente de execução do Docker

Verifique quais nós usam imagens de nó baseadas no Docker usando os seguintes métodos:

Use um script para iterar todos os nós em todos os clusters do GKE no projeto do Google Cloud.
Use a CLI do Google Cloud, a kubectl ou o Console do Google Cloud para identificar as imagens de nós.
Use insights e recomendações de descontinuação para identificar clusters e nós em zonas ou regiões específicas de um projeto do Google Cloud.

Recomendamos o uso de um script para identificar rapidamente todos os nós que você precisa migrar.

Usar um script para identificar nós do Docker

O script a seguir faz iterações em cada nó em todos os clusters nos projetos disponíveis e fornece recomendações úteis, como:

Se o provisionamento automático de nós está configurado para imagens do Docker
Equivalentes de imagem de nó do containerd sugeridos para migração
Versões sugeridas de imagem de nó para migração
Comandos sugeridos a serem executados para migrar os nós e as configurações identificados

O script ignora os clusters do GKE Autopilot, que usam o Container-Optimized OS com imagem de nó do containerd por padrão.

Execute o script a seguir:

for project in $(gcloud projects list --format="value(projectId)")
do
  echo "ProjectId: $project"
  for clusters in $( \
    gcloud container clusters list \
      --project $project \
      --format="csv[no-heading](name,location,autopilot.enabled,currentMasterVersion,autoscaling.enableNodeAutoprovisioning,autoscaling.autoprovisioningNodePoolDefaults.imageType)")
  do
    IFS=',' read -r -a clustersArray <<< "$clusters"
    cluster_name="${clustersArray[0]}"
    cluster_zone="${clustersArray[1]}"
    cluster_isAutopilot="${clustersArray[2]}"
    cluster_version="${clustersArray[3]}"
    cluster_minorVersion=${cluster_version:0:4}
    cluster_autoprovisioning="${clustersArray[4]}"
    cluster_autoprovisioningImageType="${clustersArray[5]}"

    if [ "$cluster_isAutopilot" = "True" ]; then
      echo "  Cluster: $cluster_name (autopilot) (zone: $cluster_zone)"
      echo "    Autopilot clusters are running Containerd."
    else
      echo "  Cluster: $cluster_name (zone: $cluster_zone)"

      if [ "$cluster_autoprovisioning" = "True" ]; then
        if [ "$cluster_minorVersion"  \< "1.20" ]; then
          echo "    Node autoprovisioning is enabled, and new node pools will have image type 'COS'."
          echo "    This settings is not configurable on the current version of a cluster."
          echo "    Please upgrade you cluster and configure the default node autoprovisioning image type."
          echo "    "
        else
          if [ "$cluster_autoprovisioningImageType" = "COS" ]; then
            echo "    Node autoprovisioning is configured to create new node pools of type 'COS'."
            echo "    Run the following command to update:"
            echo "    gcloud container clusters update '$cluster_name' --project '$project' --zone '$cluster_zone' --enable-autoprovisioning --autoprovisioning-image-type='COS_CONTAINERD'"
            echo "    "
          fi

          if [ "$cluster_autoprovisioningImageType" = "UBUNTU" ]; then
            echo "    Node autoprovisioning is configured to create new node pools of type 'UBUNTU'."
            echo "    Run the following command to update:"
            echo "    gcloud container clusters update '$cluster_name' --project '$project' --zone '$cluster_zone' --enable-autoprovisioning --autoprovisioning-image-type='UBUNTU_CONTAINERD'"
            echo "    "
          fi
        fi
      fi

      for nodepools in $( \
        gcloud container node-pools list \
          --project $project \
          --cluster $cluster_name \
          --zone $cluster_zone \
          --format="csv[no-heading](name,version,config.imageType)")
      do
        IFS=',' read -r -a nodepoolsArray <<< "$nodepools"
        nodepool_name="${nodepoolsArray[0]}"
        nodepool_version="${nodepoolsArray[1]}"
        nodepool_imageType="${nodepoolsArray[2]}"

        nodepool_minorVersion=${nodepool_version:0:4}

        echo "    Nodepool: $nodepool_name, version: $nodepool_version ($nodepool_minorVersion), image: $nodepool_imageType"

        minorVersionWithRev="${nodepool_version/-gke./.}"
        linuxGkeMinVersion="1.14"
        windowsGkeMinVersion="1.21.1.2200"

        suggestedImageType="COS_CONTAINERD"

        if [ "$nodepool_imageType" = "UBUNTU" ]; then
          suggestedImageType="UBUNTU_CONTAINERD"
        elif [ "$nodepool_imageType" = "WINDOWS_LTSC" ]; then
          suggestedImageType="WINDOWS_LTSC_CONTAINERD"
        elif [ "$nodepool_imageType" = "WINDOWS_SAC" ]; then
          suggestedImageType="WINDOWS_SAC_CONTAINERD"
        fi

        tab=$'\n      ';
        nodepool_message="$tab Please update the nodepool to use Containerd."
        nodepool_message+="$tab Make sure to consult with the list of known issues https://cloud.google.com/kubernetes-engine/docs/concepts/using-containerd#known_issues."
        nodepool_message+="$tab Run the following command to upgrade:"
        nodepool_message+="$tab "
        nodepool_message+="$tab gcloud container clusters upgrade '$cluster_name' --project '$project' --zone '$cluster_zone' --image-type '$suggestedImageType' --node-pool '$nodepool_name'"
        nodepool_message+="$tab "

        # see https://cloud.google.com/kubernetes-engine/docs/concepts/node-images
        if [ "$nodepool_imageType" = "COS_CONTAINERD" ] || [ "$nodepool_imageType" = "UBUNTU_CONTAINERD" ] ||
           [ "$nodepool_imageType" = "WINDOWS_LTSC_CONTAINERD" ] || [ "$nodepool_imageType" = "WINDOWS_SAC_CONTAINERD" ]; then
          nodepool_message="$tab Nodepool is using Containerd already"
        elif ( [ "$nodepool_imageType" = "WINDOWS_LTSC" ] || [ "$nodepool_imageType" = "WINDOWS_SAC" ] ) &&
               [ "$(printf '%s\n' "$windowsGkeMinVersion" "$minorVersionWithRev" | sort -V | head -n1)" != "$windowsGkeMinVersion" ]; then
          nodepool_message="$tab Upgrade nodepool to the version that supports Containerd for Windows"
        elif [ "$(printf '%s\n' "$linuxGkeMinVersion" "$minorVersionWithRev" | sort -V | head -n1)" != "$linuxGkeMinVersion" ]; then
          nodepool_message="$tab Upgrade nodepool to the version that supports Containerd"
        fi
        echo "$nodepool_message"
      done
    fi # not autopilot
  done
done

# Sample output:
#
# ProjectId:  my-project-id
#  Cluster: autopilot-cluster-1 (autopilot) (zone: us-central1)
#    Autopilot clusters are running Containerd.
#  Cluster: cluster-1 (zone: us-central1-c)
#    Nodepool: default-pool, version: 1.18.12-gke.1210 (1.18), image: COS
#
#       Please update the nodepool to use Containerd.
#       Make sure to consult with the list of known issues https://cloud.google.com/kubernetes-engine/docs/concepts/using-containerd#known_issues.
#       Run the following command to upgrade:
#
#       gcloud container clusters upgrade 'cluster-1' --project 'my-project-id' --zone 'us-central1-c' --image-type 'COS_CONTAINERD' --node-pool 'default-pool'
#
#    Nodepool: pool-1, version: 1.18.12-gke.1210 (1.18), image: COS
#
#       Please update the nodepool to use Containerd.
#       Make sure to consult with the list of known issues https://cloud.google.com/kubernetes-engine/docs/concepts/using-containerd#known_issues.
#       Run the following command to upgrade:
#
#       gcloud container clusters upgrade 'cluster-1' --project 'my-project-id' --zone 'us-central1-c' --image-type 'COS_CONTAINERD' --node-pool 'pool-1'
#
#    Nodepool: winpool, version: 1.18.12-gke.1210 (1.18), image: WINDOWS_SAC
#
#       Upgrade nodepool to the version that supports Containerd for Windows
#
#  Cluster: another-test-cluster (zone: us-central1-c)
#    Nodepool: default-pool, version: 1.20.4-gke.400 (1.20), image: COS_CONTAINERD
#
#      Nodepool is using Containerd already
#

Identificar imagens de nós usando o Google Cloud

É possível verificar as imagens de nós usando a CLI do Google Cloud, a kubectl, ou o Console do Google Cloud.

gcloud

Execute este comando:

gcloud container node-pools list \
    --cluster=CLUSTER_NAME \
    --format="table(name,version,config.imageType)"

Substitua CLUSTER_NAME pelo nome do cluster.

A saída será assim:

NAME          NODE_VERSION    IMAGE_TYPE
default-pool  1.19.6-gke.600  UBUNTU

Console

Acesse a página Google Kubernetes Engine no console do Google Cloud.

Acessar o Google Kubernetes Engine
Na lista de clusters, clique no nome do cluster que você quer verificar.
Selecione a guia Nós.
Na seção Pool de nós, veja o valor na coluna Tipo de imagem.

kubectl

Execute este comando:

kubectl get nodes -o wide

A saída será assim:

# For Docker runtime
NAME         STATUS   VERSION             OS-IMAGE                             CONTAINER-RUNTIME
gke-node-1   Ready    v1.16.15-gke.6000   Container-Optimized OS from Google   docker://19.3.1
gke-node-2   Ready    v1.16.15-gke.6000   Container-Optimized OS from Google   docker://19.3.1
gke-node-3   Ready    v1.16.15-gke.6000   Container-Optimized OS from Google   docker://19.3.1

O valor na coluna CONTAINER-RUNTIME mostra o ambiente de execução e a versão.

Identificar clusters usando insights e recomendações de descontinuação

O GKE detecta o uso de alguns recursos e APIs descontinuados, incluindo imagens de nós baseados no Docker. Para saber mais, consulte Descontinuações do GKE.

Como parte da detecção do uso de descontinuações, o GKE gera insights e recomendações que identificam o uso de imagens de nó baseadas no Docker com o subtipo de insight DEPRECATION_K8S_1_24_DOCKERSHIM.

Um insight e um par de recomendações identificam um cluster que tem nós que usam imagens de nó baseadas no Docker. Cada insight e recomendação fornece uma lista dos pools de nós específicos em um cluster que estão usando imagens de nó baseadas no Docker e precisam ser migradas para imagens de nó do containerd.

Para começar, siga as instruções para ver recomendações e insights de descontinuação. Para os comandos da CLI gcloud, use a sinalização a seguir para ver insights sobre essa descontinuação:

--filter="insightSubtype:DEPRECATION_K8S_1_24_DOCKERSHIM"

Depois de identificar quais pools de nós do cluster estão usando imagens de nó baseadas no Docker, siga as instruções para alterar a imagem do nó para uma imagem do nó do containerd.

Verificar o impacto da migração

Antes de migrar clusters de produção e pools de nós para imagens de nó que usam contêineres, recomendamos testar o impacto da migração em um ambiente de preparo para minimizar o risco de problemas.

Recomendamos que, ao migrar os nós, você faça isso independentemente da atualização dos nós, para poder isolar variáveis ao verificar a função das cargas de trabalho com a nova configuração. Além disso, se você fizer upgrade do pool de nós para a versão 1.24 ao mesmo tempo, não será possível reverter a alteração, já que 1.24 não é compatível com nós do Docker e não pode fazer downgrade de versões secundárias.

Alterar a imagem do nó para uma imagem do containerd

Se você usou o script para identificar os nós do Docker, pode usar os comandos sugeridos retornados pelo script para alterar as configurações de provisionamento automático de nós e as imagens de nó para os equivalentes do containerd.

Também é possível migrar nós de um tipo de imagem do Docker para um tipo de imagem do containerd. Basta atualizar o pool de nós e definir uma imagem diferente usando a CLI gcloud ou o console do Google Cloud.

O GKE usa a estratégia de upgrade e a configuração selecionadas de nós para migrar a imagem de um nó. Para essa migração, recomendamos o uso da estratégia de upgrade azul-verde porque, se suas cargas de trabalho apresentarem problemas com a nova imagem de nó durante o upgrade, será possível reverter para o ambiente anterior com a configuração original da imagem do nó.

gcloud

Execute este comando:

gcloud container clusters upgrade CLUSTER_NAME \
    --image-type=NODE_IMAGE \
    --node-pool=POOL_NAME \
    --cluster-version=NODE_VERSION

Substitua:

NODE_IMAGE: a imagem de nó que você quer que os nós usem.
POOL_NAME: o nome do pool de nós a ser migrado.
NODE_VERSION: a versão atual do pool de nós. Recomendamos configurar essa sinalização porque, do contrário, o GKE tenta fazer upgrade da versão do pool de nós para a versão do plano de controle e atualizar a imagem do nó na mesma operação. Se o plano de controle estiver executando 1.24, o comando falhará. Se o plano de controle estiver executando 1.23, o comando será bem-sucedido, o que impedirá que você teste as duas alterações (upgrade de versão e atualização de imagem) isoladamente.

O resultado será assim:

NAME          NODE_VERSION    IMAGE_TYPE
default-pool  1.23.6-gke.600  UBUNTU_CONTAINERD

Console

Acesse a página Google Kubernetes Engine no console do Google Cloud.

Acesse o Google Kubernetes Engine
Na lista de clusters, clique no nome do cluster que você quer verificar.
Clique na guia Nós.
Na seção Pool de nós, clique no nome do pool de nós que você quer modificar.
Na página Detalhes do pool de nós, clique em Editar.
Na seção Nós, em Tipo de imagem, clique em Alterar.
Selecione um dos tipos de imagem do containerd.
Clique em Alterar.

Reverter para as imagens de nó do Docker

Se os nós foram migrados de maneira automática ou manual para os nós do containerd e você perceber um problema com as cargas de trabalho, siga as etapas a seguir para reverter as imagens para nós do Docker:

Escolha a etapa a seguir, dependendo do estado da operação:
- Se a operação ainda estiver em andamento, será possível cancelar e reverter.
- Se a operação estiver concluída, consulte as etapas da seção anterior e selecione a imagem do Docker equivalente.
Configure uma exclusão de manutenção para impedir temporariamente que o GKE tente repetir a migração.
Investigue a causa raiz do problema para migrar do Docker e garantir que o cluster esteja executando uma versão compatível do GKE.
Tente novamente alterar a imagem do nó para uma imagem do containerd. Se você remover a exclusão de manutenção, o GKE acionará a operação novamente.

Atualizar configurações da ferramenta Infrastructure as Code (IaC)

Se você usa ferramentas de IaC, como Terraform, Ansible ou Pulumi, para gerenciar clusters do GKE, atualize as configurações para usar imagens de nó em contêiner para evitar que as ferramentas reconciliem o estado anteriormente desejado com o novo estado real. Por exemplo, o provedor GKE GKE é compatível com tipos de imagens configuráveis.

Atualize as configurações para que a ferramenta não atualize a imagem de nó para uma imagem de nó baseada no Docker depois de migrar para as imagens de nó do containerd.

Alterar a imagem de nó padrão para o provisionamento automático de nós

Se você usar o provisionamento automático de nós no cluster, altere o tipo de imagem padrão para uma imagem de nó do containerd. A alteração do tipo de imagem padrão só se aplica a novos pools de nós provisionados automaticamente. Altere a imagem de nó manualmente para os pools de nós provisionados automaticamente.

É possível alterar o tipo de imagem de provisionamento automático de nós padrão usando a CLI gcloud ou um arquivo de configuração.

gcloud

Execute este comando:

gcloud container clusters update CLUSTER_NAME \
    --enable-autoprovisioning \
    --autoprovisioning-image-type=IMAGE_TYPE

Substitua:

CLUSTER_NAME: o nome do cluster a se fazer upgrade.
IMAGE_TYPE: o tipo de imagem do nó, que pode ser um dos seguintes:
- cos_containerd
- ubuntu_containerd
  
  Observação: para ubuntu_containerd, especifique --autoprovisioning-scopes=https://www.googleapis.com/auth/devstorage.read_only no comando.

Arquivo

É possível usar um arquivo de configuração YAML para alterar o tipo de imagem de nó padrão para o provisionamento automático de nós. Ao usar um arquivo, você também precisa especificar os valores máximos para os recursos de CPU e memória.

Salve o seguinte arquivo YAML:
```
resourceLimits:
  - resourceType: 'cpu'
      minimum: 4
      maximum: 10
  - resourceType: 'memory'
      maximum: 64
autoprovisioningNodePoolDefaults:
  imageType: 'IMAGE_TYPE'
```
Substitua IMAGE_TYPE pelo tipo de imagem do containerd.

Observação: para ubuntu_containerd, adicione scopes: https://www.googleapis.com/auth/devstorage.read_only ao arquivo de configuração.

Aplique a configuração:

gcloud container clusters update CLUSTER_NAME \
    --enable-autoprovisioning \
    --autoprovisioning-config-file=FILE_NAME

Substitua FILE_NAME pelo caminho para o arquivo de configuração.

Solução de problemas

Para solucionar problemas e ver problemas conhecidos com soluções alternativas, consulte Solução de problemas no ambiente de execução do contêiner.

Migrar do Docker para imagens de nó containerd

Visão geral

Antes de começar

Identificar nós que usam o ambiente de execução do Docker

Usar um script para identificar nós do Docker

Identificar imagens de nós usando o Google Cloud

gcloud

Console

kubectl

Identificar clusters usando insights e recomendações de descontinuação

Verificar o impacto da migração

Alterar a imagem do nó para uma imagem do containerd

gcloud

Console

Reverter para as imagens de nó do Docker

Atualizar configurações da ferramenta Infrastructure as Code (IaC)

Alterar a imagem de nó padrão para o provisionamento automático de nós

gcloud

Arquivo

Solução de problemas

A seguir