Migrar nodos a containerd 2

Los clústeres de Google Kubernetes Engine (GKE) usan imágenes de nodo de containerd con todos los nodos de trabajador que ejecutan la versión 1.24 y posteriores. Los nodos de trabajador usan una versión específica de containerd, basada en la versión de GKE:

  • Los nodos que ejecutan GKE 1.32 o versiones anteriores con imágenes de nodo de containerd usan containerd 1.7 o versiones anteriores.
  • Los nodos que ejecutan GKE 1.33 usan containerd 2.0.

Cuando los nodos de GKE se actualizan de la versión 1.32 a la 1.33, migran de containerd 1.7 a la nueva versión principal, containerd 2.0. No puedes cambiar la versión de containerd que usa una versión de GKE.

Puedes saltarte esta página si sabes que tus cargas de trabajo se ejecutan correctamente en containerd 2.

Cómo se está llevando a cabo la transición de GKE a containerd 2

Consulta la siguiente cronología para saber cómo está migrando GKE los clústeres a containerd 2:

  • En la versión secundaria 1.32, GKE usa containerd 1.7. containerd 1.7 ha retirado las imágenes de Docker Schema 1 y la API Container Runtime Interface (CRI) v1alpha2. Para obtener información sobre otras funciones obsoletas en versiones anteriores, consulta Propiedades de configuración obsoletas.
  • Con la versión secundaria 1.33, GKE usa containerd 2.0, que elimina la compatibilidad con las imágenes de Docker Schema 1 y la API CRI v1alpha2.
  • Las siguientes propiedades de configuración de containerd del complemento CRI están obsoletas y se eliminarán en containerd 2.2. Aún no se ha anunciado la versión de GKE: registry.auths, registry.configs y registry.mirrors. Sin embargo, registry.configs.tls ya se había retirado en containerd 2.0.

Para ver las fechas aproximadas de las actualizaciones automáticas a versiones secundarias posteriores, como la 1.33, consulta la programación estimada de los canales de lanzamiento.

Impacto de la transición a containerd 2

Lee la siguiente sección para saber cómo afecta esta transición a containerd 2.

Actualizaciones automáticas pausadas

GKE pausa las actualizaciones automáticas a la versión 1.33 cuando detecta que un clúster usa las funciones obsoletas. Sin embargo, si los nodos de tu clúster usan estas funciones, te recomendamos que crees una exclusión de mantenimiento para evitar que se actualicen los nodos. La exclusión de mantenimiento asegura que tus nodos no se actualicen si GKE no detecta uso.

Después de migrar de estas funciones, GKE reanudará las actualizaciones secundarias automáticas a la versión 1.33 si se cumplen las siguientes condiciones:

  • GKE no ha detectado el uso de funciones obsoletas en los últimos 14 días o en los últimos 3 días en el caso de las propiedades de CRI registry.configs obsoletas.
  • 1.33 es el destino de actualización automática de los nodos de tu clúster.
  • No hay otros factores que lo impidan. Para obtener más información, consulta Cuándo se realizan las actualizaciones automáticas.

En el caso de los grupos de nodos de clústeres estándar, también puedes actualizar manualmente el grupo de nodos.

Fin de la asistencia y consecuencias de no prepararse para la migración

GKE pausa las actualizaciones automáticas hasta el final del periodo de asistencia estándar. Si tu clúster está registrado en el canal ampliado, tus nodos pueden permanecer en una versión hasta el final del periodo de asistencia ampliado. Para obtener más información sobre las actualizaciones automáticas de nodos al final del periodo de asistencia, consulta Actualizaciones automáticas al final del periodo de asistencia.

Si no migras de estas funciones, cuando la versión 1.32 llegue al final de su ciclo de vida y los nodos de tu clúster se actualicen automáticamente a la versión 1.33, podrías tener los siguientes problemas con tus clústeres:

  • Las cargas de trabajo que usan imágenes de Docker Schema 1 fallan.
  • Las aplicaciones que llaman a la API CRI v1alpha2 experimentan fallos al llamar a la API.

Identifica los clústeres afectados

GKE monitoriza tus clústeres y usa el servicio Recommender para ofrecerte orientación mediante estadísticas y recomendaciones que te ayuden a identificar los nodos de clúster que usan estas funciones obsoletas.

Requisitos de la versión

Los clústeres reciben estas estadísticas y recomendaciones si ejecutan las siguientes versiones o posteriores:

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

Obtener estadísticas y recomendaciones

Sigue las instrucciones para ver estadísticas y recomendaciones. Puedes obtener estadísticas con la Google Cloud consola. También puedes usar Google Cloud CLI o la API Recommender filtrando por los siguientes subtipos:

  • DEPRECATION_CONTAINERD_V1_SCHEMA_IMAGES: Imágenes de Docker Schema 1
  • DEPRECATION_CONTAINERD_V1ALPHA2_CRI_API: API CRI v1alpha2
  • DEPRECATION_CONTAINERD_V2_CONFIG_REGISTRY_CONFIGS: propiedades de CRI registry.configs obsoletas, incluidas registry.configs.auth y registry.configs.tls

Migrar desde funciones obsoletas

Consulta el siguiente contenido para saber cómo migrar desde las funciones obsoletas con containerd 2.

Migrar de imágenes de Docker Schema 1

Identifica las cargas de trabajo que usan imágenes que deben migrarse y, a continuación, migra esas cargas de trabajo.

Buscar imágenes que se van a migrar

Puedes usar diferentes herramientas para encontrar las imágenes que debes migrar.

Usar estadísticas y recomendaciones o Cloud Logging

Como se explica en la sección Identificar clústeres afectados, puedes usar estadísticas y recomendaciones para encontrar clústeres que usen imágenes de Docker Schema 1 si tu clúster ejecuta una versión mínima o posterior. Además, puedes usar la siguiente consulta en Cloud Logging para comprobar los registros de containerd y encontrar imágenes de Docker Schema 1 en tu clúster:

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

Si han transcurrido más de 30 días desde que se extrajo la imagen, es posible que no vea los registros de la imagen.

Usar el comando ctr directamente en un nodo

Para consultar un nodo específico y devolver todas las imágenes no eliminadas que se extrajeron como Schema 1, ejecuta el siguiente comando en un nodo:

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

Este comando puede ser útil si, por ejemplo, estás solucionando un problema de un nodo específico y no ves entradas de registro en Cloud Logging porque han pasado más de 30 días desde que se extrajo la imagen.

Usar la herramienta de código abierto crane

También puedes usar herramientas de código abierto como crane para buscar imágenes.

Ejecuta el siguiente comando crane para comprobar la versión del esquema de una imagen:

crane manifest $tagged_image | jq .schemaVersion

Preparar cargas de trabajo

Para preparar las cargas de trabajo que ejecutan imágenes de Docker Schema 1, debes migrar esas cargas de trabajo a imágenes de Docker Schema 2 o a imágenes de Open Container Initiative (OCI). Para migrar, tienes las siguientes opciones:

  • Buscar una imagen de sustitución: es posible que encuentres una imagen de código abierto o proporcionada por el proveedor que esté disponible públicamente.
  • Convertir la imagen: si no encuentra una imagen de sustitución, puede convertir las imágenes de Docker Schema 1 en imágenes OCI siguiendo estos pasos:
    1. Extrae la imagen Docker en containerd, que la convierte automáticamente en una imagen OCI.
    2. Envía la nueva imagen OCI a tu registro.

Migrar de la API CRI v1alpha2

La API CRI v1alpha2 se retiró en Kubernetes 1.26. Debe identificar las cargas de trabajo que acceden al socket de containerd y actualizar estas aplicaciones para que usen la API v1.

Identificar las cargas de trabajo que pueden verse afectadas

Puedes usar diferentes técnicas para identificar las cargas de trabajo que podrían necesitar migrarse. Estas técnicas pueden generar falsos positivos que debes investigar más a fondo para determinar si no es necesario tomar ninguna medida.

Usar estadísticas y recomendaciones

Puedes usar las estadísticas y las recomendaciones para encontrar clústeres que usen la API v1alpha2 si tu clúster ejecuta una versión mínima o posterior. Para obtener más información, consulta Identificar los clústeres afectados.

Cuando consultes las estadísticas en la Google Cloud consola, ve al panel de la barra lateral Migra tus cargas de trabajo de la API CRI v1alpha2 obsoleta. La tabla Cargas de trabajo que se van a verificar de este panel muestra las cargas de trabajo que podrían verse afectadas. Esta lista incluye las cargas de trabajo que no gestiona GKE y que tienen volúmenes hostPath que contienen la ruta del socket de containerd (por ejemplo, /var/run/containerd/containerd.sock o /run/containerd/containerd.sock).

Es importante que tengas en cuenta lo siguiente:

  • La lista de cargas de trabajo que se van a verificar puede contener falsos positivos. Úsala solo para investigar. Que una carga de trabajo aparezca en esta lista no significa que esté usando la API obsoleta, y la presencia de un falso positivo no pausará las actualizaciones automáticas. La pausa se basa únicamente en el uso observado de la API obsoleta.
  • Esta lista puede estar vacía o incompleta. Una lista vacía o incompleta puede ocurrir si las cargas de trabajo que usan la API obsoleta han tenido una duración breve y no se estaban ejecutando cuando GKE ha realizado su comprobación periódica. La presencia de la recomendación significa que se ha detectado el uso de la API CRI v1alpha2 en al menos un nodo de tu clúster. Las actualizaciones automáticas se reanudarán si no se detecta el uso de la API obsoleta durante 14 días.

Por lo tanto, te recomendamos que investigues más a fondo el asunto con los siguientes métodos para confirmar el uso real de la API.

Comprobar las cargas de trabajo de terceros afectadas

En el caso del software de terceros implementado en tus clústeres, verifica que estas cargas de trabajo no usen la API CRI v1alpha2. Es posible que tengas que ponerte en contacto con los proveedores correspondientes para verificar qué versiones de su software son compatibles.

Usar kubectl

El siguiente comando te ayuda a encontrar cargas de trabajo que puedan verse afectadas buscando las que acceden al socket de containerd. Usa una lógica similar a la que se utiliza en la tabla Cargas de trabajo que verificar de la recomendación de la consola Google Cloud . Devuelve las cargas de trabajo no gestionadas por GKE que tienen volúmenes hostPath, incluida la ruta del socket. Al igual que la recomendación, esta consulta puede devolver falsos positivos o no detectar cargas de trabajo de corta duración.

Ejecuta el siguiente 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 el rastreo eBPF para identificar a los llamantes de la API

Para identificar de forma más definitiva qué cargas de trabajo llaman a la API CRI v1alpha2, puedes desplegar dos DaemonSets especializados:

  • containerd-socket-tracer registra cualquier proceso que abra una conexión al socket containerd, junto con los detalles del pod y del contenedor.
  • El cri-v1alpha2-api-deprecation-reporter registra la última vez que se llamó a la API CRI v1alpha2.

Estas herramientas usan Extended Berkeley Packet Filter (eBPF) para monitorizar las conexiones al socket containerd y correlacionar las conexiones con llamadas a APIs obsoletas.

Al correlacionar las marcas de tiempo de estas dos herramientas, puedes identificar la carga de trabajo exacta que hace la llamada a la API obsoleta. Este método ofrece un mayor grado de confianza que comprobar solo los volúmenes de hostPath, ya que observa las conexiones de sockets y el uso de APIs reales.

Para obtener instrucciones detalladas sobre cómo implementar y usar estas herramientas, y cómo interpretar sus registros, consulta Monitorizar las conexiones de sockets de containerd.

Si, después de usar estas herramientas, sigues sin poder identificar la fuente de las llamadas a la API obsoletas, pero la recomendación sigue activa, consulta Obtener asistencia.

Una vez que hayas identificado una carga de trabajo que utilice la API CRI v1alpha2, ya sea con los métodos anteriores o inspeccionando tu base de código, debes actualizar su código para que use la API v1.

Actualizar el código de la aplicación

Para actualizar tu aplicación, elimina la parte en la que la aplicación importa la biblioteca de cliente k8s.io/cri-api/pkg/apis/runtime/v1alpha2 y modifica el código para usar la versión v1 de la API. En este paso, se cambia la ruta de importación y se actualiza la forma en que el código llama a la API.

Por ejemplo, consulta el siguiente código de Go, que usa la biblioteca obsoleta:

  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{})

    ...
  }

En este caso, la aplicación importa la biblioteca v1alpha2 y la usa para emitir RPCs. Si las llamadas RPC usan la conexión al socket de containerd, esta aplicación está provocando que GKE pause las actualizaciones automáticas del clúster.

Sigue estos pasos para buscar y actualizar el código de tu aplicación:

  1. Para identificar las aplicaciones de Go que tienen problemas, ejecuta el siguiente comando para buscar la ruta de importación v1alpha2:

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

    Si la salida de este comando muestra que se usa la biblioteca v1alpha2 en el archivo, debes actualizarlo.

    Por ejemplo, sustituye el siguiente código de aplicación:

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

  2. Actualiza el código para usar la versión 1:

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

Migrar desde propiedades de configuración de containerd obsoletas

Las propiedades de configuración de registry.auths, registry.configs y registry.mirrors containerd del complemento CRI están obsoletas y se eliminarán en containerd 2.2. Aún no se ha anunciado la versión de GKE. Sin embargo, registry.configs.tls ya se había retirado en containerd 2.0.

Identificar cargas de trabajo

Puedes usar diferentes técnicas para identificar las cargas de trabajo que se deben migrar.

Usar estadísticas y recomendaciones

Como primer paso, puedes usar las estadísticas y las recomendaciones para encontrar clústeres que usen las propiedades de configuración de containerd obsoletas. Para ello, se necesita una versión mínima de GKE. Para obtener más información sobre este enfoque, consulta Identificar clústeres afectados.

Cuando veas las estadísticas en la consola Google Cloud , consulta el panel de la barra lateral Migra la configuración de containerd de las autenticaciones de registro de CRI obsoletas o Migra la configuración de containerd de los espejos de registro de CRI obsoletos. Para encontrar cargas de trabajo que puedan acceder a la configuración de containerd, consulta la sección Cargas de trabajo que verificar.

Usar kubectl

También puedes usar kubectl para identificar las cargas de trabajo.

Busca las cargas de trabajo que modifican la configuración de containerd comprobando las cargas de trabajo con los siguientes atributos:

  • Cargas de trabajo que contienen un volumen hostPath que incluye la configuración de containerd
  • Cargas de trabajo que tienen un contenedor con acceso privilegiado (spec.containers.securityContext.privileged: true) y usan el espacio de nombres del ID de proceso (PID) del host (spec.hostPID: true)

Este comando puede devolver falsos positivos porque la carga de trabajo puede acceder a otros archivos de estos directorios que no sean la configuración de containerd. O bien, es posible que este comando no devuelva cargas de trabajo que accedan al archivo de configuración de containerd de otras formas menos habituales.

Ejecuta el siguiente comando para comprobar los 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 desde las propiedades del registro de CRI auths o configs.auth

Si tus cargas de trabajo usan las propiedades auths o configs.auth en la configuración de containerd para autenticarse en un registro privado y extraer imágenes de contenedor, debes migrar las cargas de trabajo que usen esas imágenes al campo imagePullSecrets. Para obtener más información, consulta Extraer una imagen de un registro privado.

Para identificar y migrar las cargas de trabajo que usan las propiedades auths o configs.auth obsoletas, consulta las siguientes instrucciones.

Busca los detalles de autenticación de tu registro

Puede encontrar los detalles de autenticación de su registro de una de las siguientes formas:

  • Revisa las secciones del registro de CRI auths y configs.auth en el archivo /etc/containerd/config.toml conectándote a un nodo de GKE.
  • Busca la carga de trabajo que modifica tu archivo de configuración de containerd y consulta qué detalles de autenticación se incluyen mediante los métodos descritos anteriormente para identificar cargas de trabajo. GKE no usa estos ajustes en sus cargas de trabajo del sistema.

Si usas la propiedad registry.configs.auth, los detalles de autenticación pueden ser los siguientes:

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

Recoge estos detalles de autenticación de cada dominio de registro especificado en tu configuración.

Actualiza tu carga de trabajo para usar el campo imagePullSecrets
  1. Crea un secreto con los detalles de autenticación de la sección anterior siguiendo las instrucciones para extraer una imagen de un registro privado.

  2. Identifica las cargas de trabajo que deben migrarse al campo imagePullSecrets ejecutando el siguiente comando:

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

    Debes crear un secreto para cada espacio de nombres que usen las cargas de trabajo con imágenes de este dominio de registro.

  3. Actualiza tus cargas de trabajo para que usen el campo imagePullSecrets con los secretos que has creado en el paso anterior.

    Si necesitas migrar un gran número de cargas de trabajo, puedes implementar un MutatingAdmissionWebhook para añadir el campo imagePullSecrets.

Actualiza la configuración de containerd para dejar de definir las autenticaciones de registro

Una vez que hayas migrado tus cargas de trabajo para usar el campo imagePullSecrets, debes actualizar las cargas de trabajo que modifican tu configuración de containerd para que dejen de definir las autenticaciones del registro. En el caso de las cargas de trabajo que haya identificado como modificadoras de la configuración, modifíquelas para que dejen de definir autenticaciones de registro.

Hacer pruebas con un nuevo grupo de nodos y migrar cargas de trabajo a él

Para reducir el riesgo de que se produzcan problemas con tus cargas de trabajo, haz lo siguiente:

  1. Crea un grupo de nodos.
  2. Programa la carga de trabajo actualizada que modifica la configuración de containerd en los nodos del nuevo grupo de nodos.
  3. Migra las cargas de trabajo restantes al nuevo grupo de nodos siguiendo las instrucciones para migrar cargas de trabajo entre grupos de nodos.

Migrar desde la propiedad del registro de CRI configs.tls

Si tus cargas de trabajo usan la propiedad registry.configs.tls, debes migrar esas cargas de trabajo para acceder a registros privados con certificados de AC privada.

Sigue las instrucciones para migrar desde DaemonSets de configuración. Este proceso se lleva a cabo siguiendo estos pasos:

  1. Actualiza las cargas de trabajo que modifican la configuración de containerd para que dejen de definir los detalles de TLS.
  2. Almacena los certificados en Secret Manager.
  3. Crea un archivo de configuración de tiempo de ejecución que apunte a tus certificados.
  4. Crea un nuevo grupo de nodos y comprueba que las cargas de trabajo que usan imágenes alojadas en el registro privado funcionan correctamente.
  5. Aplica la configuración a un clúster nuevo y empieza a ejecutar las cargas de trabajo en ese clúster, o aplica la configuración al clúster actual. Aplicar la configuración al clúster actual podría interrumpir otras cargas de trabajo. Para obtener más información sobre estos dos enfoques, consulta el artículo Crear un archivo de configuración de tiempo de ejecución.

Después de la migración, asegúrate de dejar de aplicar cambios en el campo registry.configs o es posible que tengas problemas con containerd.

Obtener asistencia

Si sigues sin poder determinar la fuente de las llamadas a APIs obsoletas y las recomendaciones siguen activas, considera el siguiente paso: