Migrar nós para o containerd 2

Os clusters do Google Kubernetes Engine (GKE) usam imagens de nó do containerd node images 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 no sistema operacional e na versão secundária do GKE:

  • Nós do Container-Optimized OS e do Ubuntu (Linux):
    • Os nós do Linux 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 do Linux que executam o GKE 1.33 usam o containerd 2.0.
  • Nós do Windows Server:
    • Os nós do Windows Server que executam o GKE 1.34 ou versões anteriores, com imagens de nó do containerd, usam o containerd 1.7 ou versões anteriores.
    • Os nós do Windows Server que executam o GKE 1.35 usam o containerd 2.0.

Quando os nós do GKE são atualizados para a respectiva versão secundária do GKE, eles migram 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 conforme o 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:

  • Para nós do Linux com 1.32 e nós do Windows Server com 1.34, o GKE usa o containerd 1.7. O containerd 1.7 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.
  • Para nós do Linux com 1.33 e nós do Windows Server com 1.35, 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 da CRI foram descontinuadas e serão removidas no containerd 2.4 ou mais recente, com uma versão do GKE ainda a ser anunciada: registry.auths, registry.configs, registry.mirrors. No entanto, registry.configs.tls já foi removido no containerd 2.0.

Para saber o tempo aproximado de upgrades automáticos para versões secundárias mais recentes, 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 das seguintes maneiras, dependendo da versão secundária atual do cluster e se os nós no cluster são do Linux ou do Windows Server.

Upgrades automáticos pausados para nós do Linux

O GKE pausa os upgrades automáticos para a versão 1.33 em clusters com nós do Linux quando detecta que o cluster usa os recursos descontinuados. No entanto, se os nós do cluster usarem esses recursos, nós recomendamos criar uma exclusão de manutenção para evitar upgrades de cluster. A exclusão de manutenção garante que o cluster não seja atualizado se o GKE não detectar o uso.

Depois de migrar do uso desses recursos, o GKE retoma os upgrades secundários automáticos para a versão 1.33 se as seguintes condições forem verdadeiras:

  • O GKE não detectou o uso de recursos descontinuados em 14 dias ou 3 dias para propriedades registry.configs da CRI descontinuadas.
  • A versão 1.33 é um destino de upgrade automático para o cluster.
  • Não há outros fatores de bloqueio. Para mais informações, consulte O tempo de upgrades automáticos.

Também é possível fazer upgrade do cluster manualmente.

Upgrades automáticos pausados para nós do Windows Server

O GKE pausa os upgrades automáticos para a versão 1.35 em todos os clusters com nós do Windows Server, independentemente de o cluster usar os recursos descontinuados. O GKE não consegue detectar se os nós do Windows Server estão usando os recursos descontinuados.

Para fazer upgrade do cluster com nós do Windows Server para a versão 1.35, siga as instruções em Migrar de recursos descontinuados. Depois de seguir estas instruções, você poderá fazer upgrade do cluster para a versão 1.35 manualmente.

Fim do suporte e o impacto de não se preparar para a migração

O GKE pausa os upgrades automáticos até o fim do suporte padrão suporte. 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 no fim do suporte, consulte Upgrades automáticos no fim do suporte.

Se você não migrar desses recursos, quando a versão 1.32 (para nós do Linux) ou 1.34 (para nós do Windows Server) atingir o fim do suporte e os nós do cluster forem atualizados automaticamente para a versão 1.33 ou 1.35, você 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 os clusters e usa o serviço Recommender para fornecer orientações por meio de insights e recomendações para identificar nós do Linux no cluster que usam esses recursos descontinuados. O GKE não detecta o uso de nós do Windows Server.

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 Google Cloud console. 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
  • DEPRECATION_CONTAINERD_V2_CONFIG_REGISTRY_CONFIGS: propriedades da CRI descontinuadas, incluindo registry.configs.auth e registry.configs.tlsregistry.configs

Migrar de recursos descontinuados

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

Migrar de imagens do esquema 1 do Docker

Identifique as cargas de trabalho que usam imagens que precisam ser migradas e, em seguida, migre essas cargas de trabalho.

Uma imagem fornecida pelo Google afetada por esse problema é gcr.io/google-containers/startup-script.

  • gcr.io/google-containers/startup-script:v1: usa o formato do esquema 1 descontinuado e não pode ser extraído no GKE 1.33 e mais recentes para nós do Linux.
  • gcr.io/google-containers/startup-script:v2: usa o formato do esquema 2 com suporte e pode ser extraído com sucesso.

Se você estiver usando gcr.io/google-containers/startup-script:v1 em alguma das cargas de trabalho (como DaemonSets ou implantações), atualize a referência da imagem para gcr.io/google-containers/startup-script:v2.

Encontrar imagens a serem migradas

É possível 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 com nós do Linux que usam imagens do esquema 1 do Docker se o cluster estiver executando uma versão mínima ou mais recente. Além disso, é possível usar a consulta a seguir no Cloud Logging para verificar os registros do containerd e encontrar imagens do esquema 1 do Docker no cluster:

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

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

Usar o comando ctr diretamente em um nó

Para consultar um nó específico para retornar todas as imagens não excluídas que foram extraídas como esquema 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 solucionando problemas em um nó específico e não vir 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

Também é possível 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 de trabalho para imagens do esquema 2 do Docker ou imagens da Open Container Initiative (OCI). Considere as seguintes opções para migração:

  • Encontrar uma imagem de substituição:talvez seja possível encontrar uma imagem de código aberto ou fornecida pelo fornecedor disponível publicamente.
  • Converter a imagem atual:se você não encontrar uma imagem de substituição, 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 podem precisar 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 com nós do Linux 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 Google Cloud console, consulte o painel da barra lateral Migrar 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 hostPath volumes contendo o caminho do soquete do containerd (por exemplo, /var/run/containerd/containerd.sock ou /run/containerd/containerd.sock).

É importante entender o seguinte:

  • A lista de cargas de trabalho a serem verificadas pode conter falsos positivos. Use-a apenas para investigação. Uma carga de trabalho que aparece nessa lista não significa definitivamente que ela está usando a API descontinuada, e a presença de um falso positivo não vai pausar os upgrades automáticos. A pausa é baseada apenas no uso realmente observado da API descontinuada.
  • Essa lista pode estar vazia ou incompleta. Uma lista vazia ou incompleta pode acontecer 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 realizar 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ó no cluster. Os upgrades automáticos são retomados depois que o uso da API descontinuada não é detectado por 14 dias.

Portanto, recomendamos mais investigações usando os métodos a seguir para confirmar o uso real da API.

Verificar cargas de trabalho de terceiros afetadas

Para softwares de terceiros implantados nos clusters, verifique se essas cargas de trabalho não usam a API CRI v1alpha2. Talvez seja necessário entrar em contato com os respectivos 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. Ele usa uma lógica semelhante àquela usada para a tabela Cargas de trabalho a serem verificadas na recomendação do Google Cloud console. Ele retorna cargas de trabalho não gerenciadas pelo GKE que têm volumes hostPath incluindo o caminho do soquete. 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 uma maneira mais definitiva de identificar quais cargas de trabalho em execução em nós do Linux chamam a API CRI v1alpha2, implante dois DaemonSets especializados:

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

Essas ferramentas usam o Filtro de Pacote Berkeley Estendido (eBPF) para rastrear conexões com o containerd soquete e correlacionar as conexões com chamadas de API descontinuadas reais.

Não é possível implantar esses DaemonSets em nós do Windows Server.

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 de confiança maior do que verificar apenas volumes hostPath, porque observa conexões de soquete reais e uso da API.

Para instruções detalhadas sobre como implantar e usar essas ferramentas e como interpretar os registros delas, consulte Rastreamento de 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 permanecer 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 o código do aplicativo

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

Por exemplo, consulte o código golang a seguir, 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 os 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 as etapas abaixo para pesquisar e atualizar o código do aplicativo:

  1. Identifique aplicativos golang problemáticos executando 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 arquivo.

    Por exemplo, substitua o seguinte código do 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"

Migrar de propriedades de configuração do containerd descontinuadas

As propriedades de configuração do containerd registry.auths, registry.configs e registry.mirrors no plug-in da CRI foram descontinuadas e serão removidas no containerd 2.4 ou mais recente, com uma versão do GKE ainda a ser anunciada. No entanto, registry.configs.tls já foi removido no containerd 2.0.

Identificar cargas de trabalho

É possível usar diferentes técnicas para identificar cargas de trabalho que precisam ser migradas.

Usar insights e recomendações

Como uma abordagem inicial, é possível usar insights e recomendações para encontrar clusters com nós do Linux que usam as propriedades de configuração do containerd descontinuadas. Isso requer uma versão mínima do GKE. Para mais informações sobre essa abordagem, consulte Identificar clusters afetados.

Ao visualizar insights no Google Cloud console, consulte o painel da barra lateral Migrar a configuração do containerd do campo descontinuado de autenticações do registro da CRI ou Migrar a configuração do containerd do campo descontinuado de espelhamentos do registro da CRI . Para encontrar cargas de trabalho que possam acessar a configuração do containerd, confira a seção Cargas de trabalho a serem verificadas.

Usar o kubectl

Como alternativa, é possível usar o kubectl para identificar cargas de trabalho.

Localize as cargas de trabalho que modificam a configuração do containerd verificando as cargas de trabalho com os seguintes atributos:

  • Cargas de trabalho que contêm um volume hostPath que inclui a configuração do containerd
  • Cargas de trabalho que têm um contêiner com acesso privilegiado (spec.containers.securityContext.privileged: true) e usam o namespace do ID do processo do host (PID) (spec.hostPID: true)

Esse comando pode retornar falsos positivos porque a carga de trabalho pode acessar outros arquivos nesses diretórios que não são a configuração do containerd. Ou, esse comando pode não retornar cargas de trabalho que acessam o arquivo de configuração do containerd de outras maneiras menos comuns.

Execute o seguinte comando para verificar os DaemonSets:

kubectl get daemonsets --all-namespaces -o json | \
jq -r '
  [
    "/", "/etc", "/etc/",
    "/etc/containerd", "/etc/containerd/",
    "/etc/containerd/config.toml"
  ] as $host_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(
    ([.metadata.namespace] | inside($excluded_namespaces) | not)
    and
    (
      (any(.spec.template.spec.volumes[]?.hostPath.path; IN($host_paths[])))
      or
      (
        .spec.template.spec.hostPID == true and
        any(.spec.template.spec.containers[]; .securityContext?.privileged == true)
      )
    )
  ) |
  .metadata.namespace + "/" + .metadata.name
'

Migrar das propriedades auths ou configs.auth do registro da CRI

Se as cargas de trabalho usarem as propriedades auths ou configs.auth na configuração do containerd para autenticar em um registro particular para extrair imagens de contêiner, migre as cargas de trabalho que usam essas imagens para o campo imagePullSecrets. Para mais informações, consulte Extrair uma imagem de um registro particular.

Para identificar e migrar cargas de trabalho que usam as propriedades auths ou configs.auth descontinuadas, revise as instruções a seguir.

Localizar os detalhes de autenticação do registro

É possível localizar os detalhes de autenticação do registro de uma das seguintes maneiras:

  • Revise as seções auths e configs.auth do registro da CRI no arquivo /etc/containerd/config.toml conectando-se a um nó do GKE.
  • Encontre a carga de trabalho que modifica o arquivo de configuração do containerd e confira quais detalhes de autenticação estão incluídos usando os métodos descritos anteriormente para identificar cargas de trabalho. O GKE não usa essas configurações para as cargas de trabalho do sistema.

Se você usar a propriedade registry.configs.auth, os detalhes de autenticação poderão ser semelhantes aos seguintes:

  [plugins."io.containerd.grpc.v1.cri".registry.configs."$REGISTRY_DOMAIN".auth]
    username = "example-user"
    password = "example-password"

Colete esses detalhes de autenticação para cada domínio de registro especificado na configuração.

Atualizar a carga de trabalho para usar o campo imagePullSecrets
  1. Crie um secret com os detalhes de autenticação da seção anterior seguindo as instruções para extrair uma imagem de um registro particular Registry.

  2. Identifique quais cargas de trabalho precisam ser migradas para o campo imagePullSecrets executando o seguinte comando:

    kubectl get pods -A -o json |
jq -r ".items[] |
  select(.spec.containers[] |
        .image | startswith(\"$REGISTRY_DOMAIN\")) |
  .metadata.namespace + \"/\" + .metadata.name"

    É necessário criar um secret para cada namespace usado por cargas de trabalho com imagens desse domínio de registro.

  3. Atualize as cargas de trabalho para usar o campo imagePullSecrets com os secrets criados na etapa anterior.

    Como alternativa, se você precisar migrar um grande número de cargas de trabalho, pode implementar um MutatingAdmissionWebhook para adicionar o campo imagePullSecrets.

Atualizar a configuração do containerd para parar de definir autenticações de registro

Depois de migrar as cargas de trabalho para usar o campo imagePullSecrets, atualize as cargas de trabalho que modificam a configuração do containerd para parar de definir autenticações de registro. Para todas as cargas de trabalho identificadas como modificadoras da configuração, modifique as cargas de trabalho para parar de definir autenticações de registro.

Testar com um novo pool de nós e migrar cargas de trabalho para o novo pool de nós

Para reduzir o risco de causar problemas com as cargas de trabalho, faça o seguinte:

  1. Crie um novo pool de nós.
  2. Programe a carga de trabalho atualizada que modifica a configuração do containerd para nós no novo pool de nós.
  3. Migre as cargas de trabalho restantes para o novo pool de nós seguindo as instruções para migrar cargas de trabalho entre pools de nós.

Migrar da propriedade configs.tls do registro da CRI

Se as cargas de trabalho usarem a propriedade registry.configs.tls, migre essas cargas de trabalho para acessar registros particulares com certificados de CA particulares.

Siga as instruções para migrar dos DaemonSets de configuração. Esse processo é feito com as seguintes etapas:

  1. Atualize as cargas de trabalho que modificam a configuração do containerd para parar de definir detalhes de TLS.
  2. Armazene os certificados no Secret Manager.
  3. Crie um arquivo de configuração do ambiente de execução que aponte para os certificados.
  4. Crie um novo pool de nós e teste se as cargas de trabalho que usam imagens hospedadas no registro particular funcionam conforme o esperado.
  5. Aplique a configuração a um novo cluster e comece a executar as cargas de trabalho nesse cluster ou aplique a configuração ao cluster atual. A aplicação da configuração ao cluster atual pode interromper outras cargas de trabalho atuais. Para mais informações sobre essas duas abordagens, consulte Criar um arquivo de configuração do ambiente de execução.

Depois de migrar, pare de aplicar mudanças ao campo registry.configs ou você poderá ter problemas com o containerd.

Receber suporte

Se você ainda não conseguir determinar a origem das chamadas de API descontinuadas e as recomendações permanecerem ativas, considere a próxima etapa: