Migre nós para o containerd 2

Os clusters do Google Kubernetes Engine (GKE) usam imagens de nós com todos os nós de trabalho que executam a versão 1.24 e posterior. 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 anterior, com imagens de nós 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, os nós são migrados da utilização do containerd 1.7 para a nova versão principal, o containerd 2.0. Não pode alterar a versão do containerd que uma versão do GKE usa.

Pode ignorar a leitura desta página se souber que as suas cargas de trabalho são executadas conforme esperado no containerd 2.

Como o GKE está a transitar para o containerd 2

Reveja a seguinte cronologia para compreender como o GKE está a fazer a transição dos clusters existentes para usar o containerd 2:

  • Com a versão secundária 1.32, o GKE usa o containerd 1.7. O containerd 1.7 descontinuou as imagens do esquema 1 do Docker e a API v1alpha2 da interface de tempo de execução de contentores (CRI). Para saber mais sobre outras funcionalidades descontinuadas em versões anteriores, consulte o artigo 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 vão ser removidas no containerd 2.2, com uma versão do GKE ainda por anunciar: registry.auths, registry.configs e registry.mirrors. No entanto, o registry.configs.tls já foi removido no containerd 2.0.

Para ver o momento aproximado das atualizações automáticas para versões secundárias posteriores, como a 1.33, consulte o Calendário estimado para canais de lançamento.

Impacto da transição para o containerd 2

Leia a secção seguinte para compreender o impacto desta transição para o containerd 2.

Atualizações automáticas pausadas

O GKE pausa as atualizações automáticas para a versão 1.33 quando deteta que um cluster usa as funcionalidades descontinuadas. No entanto, se os nós do cluster usarem estas funcionalidades, recomendamos que crie uma exclusão de manutenção para impedir as atualizações de nós. A exclusão de manutenção garante que os seus nós não são atualizados se o GKE não detetar utilização.

Depois de migrar da utilização destas funcionalidades, o GKE retoma as atualizações secundárias automáticas para a versão 1.33 se as seguintes condições forem verdadeiras:

  • O GKE não detetou a utilização de funcionalidades descontinuadas em 14 dias ou 3 dias para propriedades CRI registry.configs descontinuadas.
  • 1.33 é um destino de atualização automática para os nós do cluster.
  • Não existem outros fatores de bloqueio. Para mais informações, consulte O momento das atualizações automáticas.

Para node pools de clusters padrão, também pode atualizar manualmente o node pool.

Fim do apoio técnico e impacto da não preparação para a migração

O GKE pausa as atualizações automáticas até ao fim do apoio técnico padrão. Se o seu cluster estiver inscrito no canal Extended, os seus nós podem permanecer numa versão até ao fim do apoio técnico alargado. Para mais detalhes sobre os upgrades automáticos de nós no fim do suporte, consulte o artigo Upgrades automáticos no fim do suporte.

Se não migrar destas funcionalidades, quando a versão 1.32 atingir o fim do suporte técnico e os nós do cluster forem atualizados automaticamente para a versão 1.33, pode ter os seguintes problemas com os seus clusters:

  • As cargas de trabalho que usam imagens do esquema 1 do Docker falham.
  • As aplicações que chamam a API CRI v1alpha2 têm falhas na experiência ao chamar a API.

Identifique os clusters afetados

O GKE monitoriza os seus clusters e usa o serviço Recommender para fornecer orientações através de estatísticas e recomendações para identificar nós de cluster que usam estas funcionalidades descontinuadas.

Requisitos da versão

Os clusters recebem estas estatísticas e recomendações se estiverem a executar as seguintes versões ou posteriores:

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

Obtenha estatísticas e recomendações

Siga as instruções para ver estatísticas e recomendações. Pode aceder a estatísticas através da Trusted Cloud consola. Também pode usar a CLI do Google Cloud 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 CRI registry.configs descontinuadas, incluindo registry.configs.auth e registry.configs.tls

Migre de funcionalidades descontinuadas

Reveja o seguinte conteúdo para compreender como migrar das funcionalidades descontinuadas com o containerd 2.

Migre de imagens do esquema 1 do Docker

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

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

  • gcr.io/google-containers/startup-script:v1: usa o formato de esquema 1 descontinuado e não pode ser extraído no GKE 1.33 e posterior.
  • gcr.io/google-containers/startup-script:v2: usa o formato de esquema 2 suportado e pode ser extraído com êxito.

Se estiver a usar gcr.io/google-containers/startup-script:v1 em qualquer uma das suas cargas de trabalho (como DaemonSets ou implementações), tem de atualizar a referência da imagem para gcr.io/google-containers/startup-script:v2.

Encontre imagens a migrar

Pode usar diferentes ferramentas para encontrar imagens que têm de ser migradas.

Use estatísticas e recomendações ou o Cloud Logging

Conforme explicado na secção Identifique clusters afetados, pode usar estatísticas e recomendações para encontrar clusters que usam imagens do esquema Docker 1 se o seu cluster estiver a executar uma versão mínima ou posterior. Além disso, pode usar a seguinte consulta no Cloud Logging para verificar os registos do containerd e encontrar imagens do esquema 1 do Docker no seu cluster:

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

Se tiverem passado mais de 30 dias desde que a imagem foi extraída, pode não ver registos de uma imagem.

Use o comando ctr diretamente num nó

Para consultar um nó específico para devolver todas as imagens não eliminadas que foram extraídas como Schema 1, execute o seguinte comando num nó:

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

Este comando pode ser útil se, por exemplo, estiver a resolver problemas de um nó específico e não vir entradas de registo no Cloud Logging porque passaram mais de 30 dias desde que a imagem foi extraída.

Use a crane ferramenta de código aberto

Também pode usar ferramentas de código aberto, como o crane para verificar se existem imagens.

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

crane manifest $tagged_image | jq .schemaVersion

Prepare cargas de trabalho

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

  • Encontre uma imagem de substituição: pode conseguir encontrar uma imagem de código aberto ou fornecida pelo fornecedor disponível publicamente.
  • Converter a imagem existente: se não conseguir encontrar uma imagem de substituição, pode converter as imagens do esquema 1 do Docker existentes em imagens OCI com os seguintes passos:
    1. Extraia a imagem do Docker para o containerd, que a converte automaticamente numa imagem OCI.
    2. Envie a nova imagem OCI para o seu registo.

Migre da API CRI v1alpha2

A API CRI v1alpha2 foi removida no Kubernetes 1.26. Tem de identificar as cargas de trabalho que acedem à tomada do containerd e atualizar estas aplicações para usar a API v1.

Identifique cargas de trabalho potencialmente afetadas

Pode usar diferentes técnicas para identificar cargas de trabalho que podem ter de ser migradas. Estas técnicas podem gerar falsos positivos que tem de investigar mais a fundo para determinar que não é necessária nenhuma ação.

Use estatísticas e recomendações

Pode usar estatísticas e recomendações para encontrar clusters que usam a API v1alpha2 se o seu cluster estiver a executar uma versão mínima ou posterior. Para mais detalhes, consulte o artigo Identifique clusters afetados.

Quando vir as estatísticas na Trusted Cloud consola, consulte o painel da barra lateral Migre as suas cargas de trabalho da API CRI v1alpha2 descontinuada. A tabela Workloads to Verify neste painel apresenta as cargas de trabalho que podem ser afetadas. Esta lista inclui todas as cargas de trabalho que não são geridas pelo GKE e que têm volumes que contêm o caminho do soquete do containerd (por exemplo, /var/run/containerd/containerd.sock ou /run/containerd/containerd.sock).hostPath

É importante compreender o seguinte:

  • A lista de cargas de trabalho a validar pode conter falsos positivos. Use-o apenas para investigação. Uma carga de trabalho apresentada nesta lista não significa definitivamente que está a usar a API descontinuada, e a presença de um falso positivo não pausa as atualizações automáticas. A pausa baseia-se apenas na utilização efetivamente observada da API descontinuada.
  • Esta lista pode estar vazia ou incompleta. Uma lista vazia ou incompleta pode ocorrer se as cargas de trabalho que usam a API descontinuada tiverem sido de curta duração e não estiverem em execução quando o GKE realizou a respetiva verificação periódica. A presença da recomendação em si significa que foi detetada a utilização da API CRI v1alpha2 em, pelo menos, um nó no seu cluster. As atualizações automáticas são retomadas após não ter sido detetada a utilização da API descontinuada durante 14 dias.

Por conseguinte, recomendamos uma investigação mais detalhada através dos seguintes métodos para confirmar a utilização real da API.

Verifique se existem cargas de trabalho de terceiros afetadas

Para software de terceiros implementado nos seus clusters, verifique se estas cargas de trabalho não usam a API CRI v1alpha2. Pode ter de contactar os fornecedores respetivos para verificar que versões do respetivo software são compatíveis.

Use o kubectl

O comando seguinte ajuda a encontrar cargas de trabalho potencialmente afetadas procurando aquelas que acedem ao soquete do containerd. Usa uma lógica semelhante à usada para a tabela Workloads to Verify na recomendação da Trusted Cloud consola. Devolve cargas de trabalho não geridas pelo GKE que têm hostPath volumes, incluindo o caminho do soquete. Tal como a recomendação, esta consulta pode devolver falsos positivos ou perder cargas de trabalho de curta duração.

Execute o seguinte 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
'
Use a monitorização de eBPF para identificar autores de chamadas de API

Para identificar de forma mais definitiva que cargas de trabalho chamam a API CRI v1alpha2, pode implementar dois DaemonSets especializados:

  • O registo containerd-socket-tracer regista qualquer processo que abra uma ligação ao soquete containerd, juntamente com os detalhes do pod e do contentor.
  • O cri-v1alpha2-api-deprecation-reporter regista a última vez que a API CRIv1alpha2 foi chamada.

Estas ferramentas usam o Extended Berkeley Packet Filter (eBPF) para rastrear ligações ao socket containerd e correlacionar as ligações com chamadas de API descontinuadas reais.

Ao correlacionar as datas/horas destas duas ferramentas, pode identificar a carga de trabalho exata que está a fazer a chamada API descontinuada. Este método oferece um grau de confiança mais elevado do que verificar apenas os volumes de hostPath, porque observa as ligações de sockets reais e a utilização da API.

Para ver instruções detalhadas sobre como implementar e usar estas ferramentas, e como interpretar os respetivos registos, consulte o artigo Monitorizar ligações de sockets do containerd.

Se, depois de usar estas ferramentas, continuar a não conseguir identificar a origem das chamadas API descontinuadas, mas a recomendação permanecer ativa, consulte a secção Receber apoio técnico.

Depois de identificar uma carga de trabalho que esteja a usar a API CRI v1alpha2, através dos métodos anteriores ou inspecionando a sua base de código, tem de atualizar o respetivo código para usar a API v1.

Atualize o código da aplicação

Para atualizar a sua aplicação, remova o local onde a aplicação importa a biblioteca cliente k8s.io/cri-api/pkg/apis/runtime/v1alpha2 e modifique o código para usar a versão v1 da API. Este passo envolve alterar o caminho de importação e atualizar a forma como o seu código chama a API.

Por exemplo, veja o seguinte código golang, 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, a aplicação importa a biblioteca v1alpha2 e usa-a para emitir RPCs. Se os RPCs usarem a ligação ao soquete do containerd, esta aplicação está a fazer com que o GKE pause as atualizações automáticas do cluster.

Siga estes passos para pesquisar e atualizar o código da aplicação:

  1. Identifique aplicações golang problemáticas executando o seguinte comando para pesquisar o caminho de importação v1alpha2:

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

    Se o resultado deste comando mostrar que a biblioteca v1alpha2 é usada no ficheiro, tem de atualizar o ficheiro.

    Por exemplo, substitua o seguinte código da aplicação:

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

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

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

Migre a partir de propriedades de configuração do containerd descontinuadas

As propriedades de configuração registry.auths, registry.configs e registry.mirrors do containerd no plug-in CRI estão descontinuadas e vão ser removidas no containerd 2.2, com uma versão do GKE ainda por anunciar. No entanto, o registry.configs.tls já foi removido no containerd 2.0.

Identifique cargas de trabalho

Pode usar diferentes técnicas para identificar cargas de trabalho que têm de ser migradas.

Use estatísticas e recomendações

Como abordagem inicial, pode usar estatísticas e recomendações para encontrar clusters que usam as propriedades de configuração do containerd descontinuadas. Isto requer uma versão mínima do GKE. Para mais informações sobre esta abordagem, consulte o artigo Identifique clusters afetados.

Quando vir as estatísticas na Trusted Cloud consola, consulte o painel da barra lateral Migre a configuração do containerd das autorizações do registo da CRI descontinuadas ou Migre a configuração do containerd dos espelhos do registo da CRI descontinuados . Para encontrar cargas de trabalho que possam aceder à configuração do containerd, consulte a secção Cargas de trabalho a validar.

Use o kubectl

Em alternativa, pode usar o kubectl para identificar cargas de trabalho.

Localize cargas de trabalho que modificam a configuração do containerd verificando se existem 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 contentor com acesso privilegiado (spec.containers.securityContext.privileged: true) e usam o espaço de nomes do ID do processo (PID) do anfitrião (spec.hostPID: true)

Este comando pode devolver falsos positivos porque a carga de trabalho pode aceder a outros ficheiros nestes diretórios que não são a configuração do containerd. Em alternativa, este comando pode não devolver cargas de trabalho que acedam ao ficheiro de configuração do containerd de outras formas 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
'

Migre das propriedades do registo de CRI auths ou configs.auth

Se as suas cargas de trabalho usarem as propriedades auths ou configs.auth na configuração do containerd para autenticar num registo privado para obter imagens de contentores, tem de migrar as cargas de trabalho que usam essas imagens para o campo imagePullSecrets. Para mais informações, consulte o artigo Extraia uma imagem de um registo privado.

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

Encontre os detalhes de autenticação do seu registo

Pode localizar os detalhes de autenticação do seu registo de uma das seguintes formas:

  • Reveja as secções do registo CRI auths e configs.auth no ficheiro /etc/containerd/config.toml associando-se a um nó do GKE.
  • Encontre a carga de trabalho que modifica o ficheiro de configuração do containerd e veja que detalhes de autenticação estão incluídos através dos métodos descritos anteriormente para identificar cargas de trabalho. O GKE não usa estas definições para as respetivas cargas de trabalho do sistema.

Se usar a propriedade registry.configs.auth, os detalhes de autenticação podem ter o seguinte aspeto:

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

Recolha estes detalhes de autenticação para cada domínio de registo especificado na sua configuração.

Atualize a sua carga de trabalho para usar o campo imagePullSecrets
  1. Crie um Secret com os detalhes de autenticação da secção anterior seguindo as instruções para extrair uma imagem de um registo privado.

  2. Identifique que cargas de trabalho têm de 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"

    Tem de criar um segredo para cada espaço de nomes usado por cargas de trabalho com imagens deste domínio de registo.

  3. Atualize as suas cargas de trabalho para usar o campo imagePullSecrets com os segredos que criou no passo anterior.

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

Atualize a configuração do containerd para parar de definir autorizações de registo

Depois de migrar as cargas de trabalho para usar o campo imagePullSecrets, tem de atualizar as cargas de trabalho que modificam a configuração do containerd para parar de definir autorizações do registo. Para todas as cargas de trabalho que identificou como modificadoras da configuração, modifique as cargas de trabalho para parar de definir autorizações de registo.

Teste com um novo conjunto de nós e migre as cargas de trabalho para o novo conjunto de nós

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

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

Migre a propriedade do registo do CRI configs.tls

Se as suas cargas de trabalho usarem a propriedade registry.configs.tls, tem de migrar essas cargas de trabalho para aceder a registos privados com certificados de AC privada.

Siga as instruções para migrar de DaemonSets de configuração. Este processo é realizado através dos seguintes passos:

  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 ficheiro de configuração de tempo de execução que aponte para os seus certificados.
  4. Crie um novo conjunto de nós e teste se as suas cargas de trabalho que usam imagens alojadas no registo privado funcionam como 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 existente. A aplicação da configuração ao cluster existente pode potencialmente interromper outras cargas de trabalho existentes. Para mais informações sobre estas duas abordagens, consulte o artigo Crie um ficheiro de configuração de tempo de execução.

Após a migração, certifique-se de que deixa de aplicar alterações ao campo registry.configs. Caso contrário, pode ter problemas com o containerd.

Obter apoio técnico

Se ainda não conseguir determinar a origem das chamadas da API descontinuadas e as recomendações permanecerem ativas, considere o seguinte passo seguinte: