Esta página foi traduzida pela API Cloud Translation.

Migrar nós para o containerd 2

Autopilot Standard

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. No entanto, registry.configs.tls já foi removido no containerd 2.0.

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, o GKE vai retomar os upgrades automáticos de versão secundária para a 1.33 se as seguintes condições forem verdadeiras:

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

Para pools de nós de 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
DEPRECATION_CONTAINERD_V2_CONFIG_REGISTRY_CONFIGS: propriedades descontinuadas de CRI registry.configs, incluindo registry.configs.auth e registry.configs.tls

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, você pode usar 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 imagens 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 de substituição, 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 posterior. Para mais detalhes, consulte Identificar clusters afetados.

Ao visualizar insights no console do 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:

A lista de cargas de trabalho a serem verificadas pode conter falsos positivos. Use-o apenas para investigação. Uma carga de trabalho que aparece nessa lista não significa necessariamente que ela está usando a API descontinuada, e a presença de um falso positivo não pausa 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 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. Os upgrades automáticos serão retomados depois que o uso da API descontinuada não for detectado por 14 dias.

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 do 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 chamam a API CRI v1alpha2, implante dois DaemonSets especializados:

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.

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

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 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 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 o 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 o 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 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 estas etapas para pesquisar e atualizar o código do aplicativo:

Para identificar aplicativos Go 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"
```

Atualize o código para usar a v1:

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

Migrar das propriedades de configuração descontinuadas do containerd

As propriedades de configuração do containerd registry.auths, registry.configs e registry.mirrors no plug-in CRI foram descontinuadas e serão removidas no containerd 2.2, 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 as cargas de trabalho que precisam ser migradas.

Usar insights e recomendações

Como uma abordagem inicial, use insights e recomendações para encontrar clusters 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 console Google Cloud , consulte o painel da barra lateral Migre a configuração do containerd do campo descontinuado de autenticações do registro da CRI ou Migre 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, consulte a seção Cargas de trabalho a serem verificadas.

Usar o kubectl

Como alternativa, use kubectl para identificar cargas de trabalho.

Localize cargas de trabalho que modificam a configuração do containerd verificando 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 de ID do processo (PID) do host (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 talvez esse comando não retorne 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 e extrair imagens de contêiner, será necessário migrar as cargas de trabalho que usam essas imagens para o campo imagePullSecrets em vez disso. Para mais informações, consulte Extrair uma imagem de um registro privado.

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

Localizar os detalhes de autenticação do registro

Você pode encontrar os detalhes de autenticação do seu 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 podem ter esta aparência:

  [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 sua configuração.

Atualize sua carga de trabalho para usar o campo `imagePullSecrets`

Crie um secret com os detalhes de autenticação da seção anterior seguindo as instruções para extrair uma imagem de um registro privado.
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"
```
Crie um secret para cada namespace usado por cargas de trabalho com imagens desse domínio de registro.
Atualize suas 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, implemente um MutatingAdmissionWebhook para adicionar o campo imagePullSecrets.

Atualize a configuração do containerd para parar de definir autenticações do 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 que você identificou como modificadoras da configuração, modifique-as para interromper a definição de autenticações de registro.

Teste com um novo pool de nós e migre cargas de trabalho para ele

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

Crie um novo pool de nós.
Programe a carga de trabalho atualizada que modifica a configuração do containerd para nós no novo pool de nós.
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-as para acessar registros particulares com certificados de AC particulares.

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

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

Depois da migração, pare de aplicar mudanças no campo registry.configs para evitar 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:

Se você não encontrar uma solução para seu problema na documentação, consulte Receber suporte para mais ajuda, incluindo conselhos sobre os seguintes tópicos:
- Abrir um caso de suporte entrando em contato com o Cloud Customer Care.
- Receber suporte da comunidade fazendo perguntas no StackOverflow e usando a tag google-kubernetes-engine para pesquisar problemas semelhantes. Você também pode participar do canal do Slack #kubernetes-engine para receber mais suporte da comunidade.
- Abrir bugs ou solicitações de recursos usando o Issue Tracker público.

Migrar nós para o containerd 2 Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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

Impacto da transição para o containerd 2

Upgrades automáticos pausados

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

Identificar os clusters afetados

Requisitos da versão

Receber insights e recomendações

Migrar de recursos descontinuados

Migrar das imagens do esquema 1 do Docker

Encontrar imagens para migrar

Usar insights e recomendações ou o Cloud Logging

Use o comando ctr diretamente em um nó.

Usar a ferramenta de código aberto crane

Preparar cargas de trabalho

Migrar da API CRI v1alpha2

Identificar cargas de trabalho potencialmente afetadas

Usar insights e recomendações

Verificar cargas de trabalho afetadas de terceiros

Usar o kubectl

Usar o rastreamento eBPF para identificar chamadores de API

Atualizar o código do aplicativo

Migrar das propriedades de configuração descontinuadas do containerd

Identificar cargas de trabalho

Usar insights e recomendações

Usar o kubectl

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

Localizar os detalhes de autenticação do registro

Atualize sua carga de trabalho para usar o campo imagePullSecrets

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

Teste com um novo pool de nós e migre cargas de trabalho para ele

Migrar da propriedade configs.tls do registro da CRI

Receber suporte

Migrar nós para o containerd 2

Use o comando `ctr` diretamente em um nó.

Usar a ferramenta de código aberto `crane`

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

Atualize sua carga de trabalho para usar o campo `imagePullSecrets`

Migrar da propriedade `configs.tls` do registro da CRI