Migrar nós para o containerd 2

Os clusters do Google Kubernetes Engine (GKE) usam imagens de nó do containerd com todos os nós de trabalho que executam a versão 1.24 e mais recentes. Os nós de trabalho usam uma versão específica do containerd, com base na versão do GKE:

  • Os nós que executam o GKE 1.32 ou versões anteriores, com imagens de nó do containerd, usam o containerd 1.7 ou versões anteriores.
  • Os nós que executam o GKE 1.33 usam o containerd 2.0.

Quando os nós do GKE são atualizados da versão 1.32 para a 1.33, eles migram do uso do containerd 1.7 para a nova versão principal, o containerd 2.0. Não é possível mudar a versão do containerd usada por uma versão do GKE.

Você pode pular a leitura desta página se souber que suas cargas de trabalho são executadas como esperado no containerd 2.

Como o GKE está fazendo a transição para o containerd 2

Confira a linha do tempo a seguir para entender como o GKE está fazendo a transição dos clusters atuais para usar o containerd 2:

  • Com a versão secundária 1.32, o GKE usa o containerd 1.7, que descontinuou as imagens do esquema 1 do Docker e a API Container Runtime Interface (CRI) v1alpha2. Para saber mais sobre outros recursos descontinuados em versões anteriores, consulte Propriedades de configuração descontinuadas.
  • Com a versão secundária 1.33, o GKE usa o containerd 2.0, que remove o suporte para imagens do esquema 1 do Docker e a API CRI v1alpha2.
  • As seguintes propriedades de configuração do containerd no plug-in CRI estão descontinuadas e serão removidas no containerd 2.2, com uma versão do GKE ainda a ser anunciada: registry.auths, registry.configs, registry.mirrors.

Para saber o tempo aproximado dos upgrades automáticos para versões secundárias mais recentes, como 1.33, consulte a Programação estimada para canais de lançamento.

Impacto da transição para o containerd 2

Leia a seção a seguir para entender o impacto dessa transição para o containerd 2.

Upgrades automáticos pausados

O GKE pausa os upgrades automáticos para a versão 1.33 quando detecta que um cluster usa os recursos descontinuados. No entanto, se os nós do cluster usarem esses recursos, recomendamos criar uma exclusão de manutenção para impedir upgrades de nós. A exclusão de manutenção garante que os nós não sejam atualizados se o GKE não detectar o uso.

Depois que você migrar do uso desses recursos, se a versão 1.33 for um destino de upgrade automático para os nós do cluster e não houver outros fatores bloqueando os upgrades automáticos, o GKE vai retomar os upgrades automáticos secundários para a versão 1.33. Para pools de nós do cluster Standard, também é possível fazer upgrade manual do pool de nós.

Fim do suporte e impacto da falta de preparação para a migração

O GKE pausa os upgrades automáticos até o fim do suporte padrão. Se o cluster estiver inscrito no canal estendido, os nós poderão permanecer em uma versão até o fim do suporte estendido. Para mais detalhes sobre upgrades automáticos de nós após o fim do suporte, consulte Upgrades automáticos após o fim do suporte.

Se você não migrar desses recursos, quando a versão 1.32 chegar ao fim do suporte e os nós do cluster forem atualizados automaticamente para a versão 1.33, poderá ter os seguintes problemas com os clusters:

  • As cargas de trabalho que usam imagens do esquema 1 do Docker falham.
  • Os aplicativos que chamam a API CRI v1alpha2 apresentam falhas ao chamar a API.

Identificar os clusters afetados

O GKE monitora seus clusters e usa o serviço do Recomendador para fornecer orientação por meio de insights e recomendações para identificar nós de cluster que usam esses recursos descontinuados.

Requisitos da versão

Os clusters recebem esses insights e recomendações se estiverem executando as seguintes versões ou mais recentes:

  • 1.28.15-gke.1159000
  • 1.29.9-gke.1541000
  • 1.30.5-gke.1355000
  • 1.31.1-gke.1621000

Receber insights e recomendações

Siga as instruções para ver insights e recomendações. É possível receber insights usando o console Google Cloud . Também é possível usar a Google Cloud CLI ou a API Recommender, filtrando com os seguintes subtipos:

  • DEPRECATION_CONTAINERD_V1_SCHEMA_IMAGES: Imagens do esquema 1 do Docker
  • DEPRECATION_CONTAINERD_V1ALPHA2_CRI_API: API CRI v1alpha2

Migrar de recursos descontinuados

Consulte o conteúdo a seguir para entender como migrar de recursos descontinuados com o containerd 2.

Migrar das imagens do esquema 1 do Docker

Identifique as cargas de trabalho que usam imagens que precisam ser migradas e faça a migração.

Encontrar imagens para migrar

Você pode usar diferentes ferramentas para encontrar imagens que precisam ser migradas.

Usar insights e recomendações ou o Cloud Logging

Conforme explicado na seção Identificar clusters afetados, é possível usar insights e recomendações para encontrar clusters que usam imagens do Docker Schema 1 se o cluster estiver executando uma versão mínima ou mais recente. Além disso, use a seguinte consulta no Cloud Logging para verificar os registros do containerd e encontrar imagens do Docker Schema 1 no cluster:

jsonPayload.SYSLOG_IDENTIFIER="containerd"
"conversion from schema 1 images is deprecated"

Se já tiverem passado mais de 30 dias desde que a imagem foi extraída, talvez você não veja os registros dela.

Use o comando ctr diretamente em um nó.

Para consultar um nó específico e retornar todas as imagens não excluídas que foram extraídas como Schema 1, execute o seguinte comando em um nó:

  ctr --namespace k8s.io images list 'labels."io.containerd.image/converted-docker-schema1"'

Esse comando pode ser útil se, por exemplo, você estiver resolvendo problemas em um nó específico e não encontrar entradas de registro no Cloud Logging porque já se passaram mais de 30 dias desde que a imagem foi extraída.

Usar a ferramenta de código aberto crane

Você também pode usar ferramentas de código aberto, como o crane, para verificar imagens.

Execute o seguinte comando crane para verificar a versão do esquema de uma imagem:

crane manifest $tagged_image | jq .schemaVersion

Preparar cargas de trabalho

Para preparar cargas de trabalho que executam imagens do esquema 1 do Docker, migre essas cargas para imagens do esquema 2 do Docker ou da Open Container Initiative (OCI). Considere as seguintes opções de migração:

  • Encontre uma imagem substituta:talvez seja possível encontrar uma imagem de código aberto ou fornecida por um fornecedor disponível publicamente.
  • Converter a imagem atual:se não for possível encontrar uma imagem substituta, você poderá converter as imagens do esquema 1 do Docker em imagens OCI seguindo estas etapas:
    1. Extraia a imagem do Docker para o containerd, que a converte automaticamente em uma imagem OCI.
    2. Envie a nova imagem OCI para o registro.

Migrar da API CRI v1alpha2

A API CRI v1alpha2 foi removida no Kubernetes 1.26. Identifique as cargas de trabalho que acessam o soquete do containerd e atualize esses aplicativos para usar a API v1.

Identificar cargas de trabalho potencialmente afetadas

É possível usar diferentes técnicas para identificar cargas de trabalho que talvez precisem ser migradas. Essas técnicas podem gerar falsos positivos, que você precisa investigar mais para determinar que nenhuma ação é necessária.

Usar insights e recomendações

É possível usar insights e recomendações para encontrar clusters que usam a API v1alpha2 se o cluster estiver executando uma versão mínima ou mais recente. Para mais detalhes, consulte Identificar clusters afetados.

Ao visualizar insights no console Google Cloud , consulte o painel da barra lateral Migre suas cargas de trabalho da API CRI v1alpha2 descontinuada. A tabela Cargas de trabalho a serem verificadas neste painel lista as cargas de trabalho que podem ser afetadas. Essa lista inclui todas as cargas de trabalho não gerenciadas pelo GKE que têm volumes hostPath contendo o caminho do soquete do containerd (por exemplo, /var/run/containerd/containerd.sock ou /run/containerd/containerd.sock).

É importante entender o seguinte:

  • Essa lista pode conter falsos positivos. Uma carga de trabalho que aparece nessa lista não significa necessariamente que ela está usando a API descontinuada. Ele indica apenas que a carga de trabalho faz referência a um volume hostPath que inclui o soquete do containerd. Por exemplo, um agente de monitoramento pode incluir o sistema de arquivos raiz do nó (/) para coletar métricas. Incluir o sistema de arquivos raiz do nó tecnicamente inclui o caminho do soquete, mas o agente de métricas pode não chamar a API CRI v1alpha2.
  • Essa lista pode estar vazia ou incompleta. Uma lista vazia ou incompleta pode ocorrer se as cargas de trabalho que usam a API descontinuada forem de curta duração e não estiverem em execução quando o GKE fez a verificação periódica. A presença da recomendação significa que o uso da API CRI v1alpha2 foi detectado em pelo menos um nó do cluster.

Portanto, recomendamos uma investigação mais aprofundada usando os seguintes métodos para confirmar o uso real da API.

Verificar cargas de trabalho afetadas de terceiros

Para software de terceiros implantado nos clusters, verifique se essas cargas de trabalho não usam a API CRI v1alpha2. Talvez seja necessário entrar em contato com os fornecedores para verificar quais versões do software são compatíveis.

Usar o kubectl

O comando a seguir ajuda a encontrar cargas de trabalho potencialmente afetadas procurando aquelas que acessam o soquete do containerd. Ela usa uma lógica semelhante à usada na tabela Cargas de trabalho a serem verificadas na recomendação do console Google Cloud . Ele retorna cargas de trabalho não gerenciadas pelo GKE que têm volumes hostPath, incluindo o caminho do soquete. Assim como a recomendação, essa consulta pode retornar falsos positivos ou perder cargas de trabalho de curta duração.

Execute este comando:

kubectl get pods --all-namespaces -o json | \
jq -r '
  [
    "/", "/var", "/var/","/var/run", "/var/run/",
    "/var/run/containerd", "/var/run/containerd/", "/var/run/containerd/containerd.sock",
    "/run", "/run/", "/run/containerd", "/run/containerd/",
    "/run/containerd/containerd.sock"
  ] as $socket_paths |
  [
    "kube-system", "kube-node-lease", "istio-system", "asm-system",
    "gatekeeper-system", "config-management-system", "config-management-monitoring",
    "cnrm-system", "hnc-system", "gke-managed-system", "gke-gmp-system",
    "gmp-system", "gke-managed-cim"
  ] as $excluded_namespaces |
  .items[] |
  select(
    (.spec.volumes[]?.hostPath.path as $p | $socket_paths | index($p))
    and
    ([.metadata.namespace] | inside($excluded_namespaces) | not)
  ) |
  .metadata.namespace + "/" + .metadata.name
'
Usar o rastreamento eBPF para identificar chamadores de API

Para identificar de forma mais definitiva quais cargas de trabalho estão chamando a API CRI v1alpha2, implante dois DaemonSets especializados: containerd-socket-tracer e cri-v1alpha2-api-deprecation-reporter. Essas ferramentas usam o Extended Berkeley Packet Filter (eBPF) para rastrear conexões com o soquete containerd e correlacionar as conexões com chamadas de API descontinuadas:

  • O containerd-socket-tracer registra qualquer processo que abra uma conexão com o soquete containerd, além dos detalhes do pod e do contêiner.
  • O cri-v1alpha2-api-deprecation-reporter registra a última vez que a API CRI v1alpha2 foi chamada.

Ao correlacionar os carimbos de data/hora dessas duas ferramentas, é possível identificar a carga de trabalho exata que está fazendo a chamada de API descontinuada. Esse método oferece um grau maior de confiança do que verificar apenas os volumes de hostPath, porque observa as conexões de soquete reais e o uso da API.

Para instruções detalhadas sobre como implantar e usar essas ferramentas e como interpretar os registros delas, consulte Como rastrear conexões de soquete do containerd.

Se, depois de usar essas ferramentas, você ainda não conseguir identificar a origem das chamadas de API descontinuadas, mas a recomendação continuar ativa, consulte Receber suporte.

Depois de identificar uma carga de trabalho que está usando a API CRI v1alpha2, pelos métodos anteriores ou inspecionando a base de código, atualize o código dela para usar a API v1.

Atualizar código do aplicativo

Para atualizar o aplicativo, remova o local em que ele importa a biblioteca de cliente k8s.io/cri-api/pkg/apis/runtime/v1alpha2 e modifique o código para usar a versão v1 da API. Esta etapa envolve mudar o caminho de importação e atualizar como seu código chama a API.

Por exemplo, confira o seguinte código em Go, que usa a biblioteca descontinuada:

  package main

  import (
    ...

    runtimeapi "k8s.io/cri-api/pkg/apis/runtime/v1alpha2"
  )

  func foo() {
    ...

    client := runtimeapi.NewRuntimeServiceClient(conn)
    version, err := client.Version(ctx, &runtimeapi.VersionRequest{})

    ...
  }

Aqui, o aplicativo importa a biblioteca v1alpha2 e a usa para emitir RPCs. Se as RPCs usarem a conexão com o soquete do containerd, esse aplicativo fará com que o GKE pause os upgrades automáticos do cluster.

Siga estas etapas para pesquisar e atualizar o código do aplicativo:

  1. Para identificar aplicativos golang problemáticos, execute o seguinte comando para pesquisar o caminho de importação v1alpha2:

      grep -r "k8s.io/cri-api/pkg/apis/runtime/v1alpha2"

    Se a saída desse comando mostrar que a biblioteca v1alpha2 é usada no arquivo, atualize-o.

    Por exemplo, substitua o seguinte código de aplicativo:

      runtimeapi "k8s.io/cri-api/pkg/apis/runtime/v1alpha2"

  2. Atualize o código para usar a v1:

      runtimeapi "k8s.io/cri-api/pkg/apis/runtime/v1"

Receber suporte

Se você seguiu as instruções para usar o rastreamento eBPF para identificar chamadores de API, mas ainda não consegue determinar a origem das chamadas de API descontinuadas e as recomendações permanecem ativas, considere a próxima etapa: