Migra nodos a containerd 2

Los clústeres de Google Kubernetes Engine (GKE) usan imágenes de nodos de containerd con todos los nodos trabajadores que ejecutan la versión 1.24 y versiones posteriores. Los nodos trabajadores usan una versión específica de containerd, según 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 del uso 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 omitir la lectura de esta página si sabes que tus cargas de trabajo se ejecutan según lo esperado en containerd 2.

Cómo GKE realiza la transición a containerd 2

Revisa la siguiente cronología para comprender cómo GKE realiza la transición de los clústeres existentes para usar containerd 2:

  • Con la versión secundaria 1.32, GKE usa containerd 1.7. containerd 1.7 dejó de admitir las imágenes de Docker Schema 1 y la API de v1alpha2 de Container Runtime Interface (CRI). Para obtener información sobre otras funciones que se dejaron de usar en versiones anteriores, consulta Propiedades de configuración obsoletas.
  • Con la versión secundaria 1.33, GKE usa containerd 2.0, que quita la compatibilidad con las imágenes de Docker Schema 1 y la API de CRI v1alpha2.
  • Las siguientes propiedades de configuración de containerd en el complemento de CRI están obsoletas y se quitarán en containerd 2.2, con una versión de GKE aún por anunciar: registry.auths, registry.configs, registry.mirrors. Sin embargo, registry.configs.tls ya se quitó en containerd 2.0.

Para conocer los tiempos aproximados de las actualizaciones automáticas a versiones secundarias posteriores, como la 1.33, consulta el Programa estimado para los canales de versiones.

Impacto de la transición a containerd 2

Lee la siguiente sección para comprender el impacto de esta transición a containerd 2.

Se pausaron las actualizaciones automáticas

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 las actualizaciones de nodos. La exclusión de mantenimiento garantiza que tus nodos no se actualicen si GKE no detecta uso.

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

  • GKE no detectó el uso de funciones obsoletas en los últimos 14 días, o 3 días en el caso de las propiedades de CRI registry.configs obsoletas.
  • La versión 1.33 es un destino de actualización automática para los nodos de tu clúster.
  • No hay otros factores de bloqueo. Para obtener más información, consulta El momento de las actualizaciones automáticas.

Para los grupos de nodos de clústeres estándar, también puedes actualizar el grupo de nodos de forma manual.

Fin de la asistencia y el impacto de no prepararse para la migración

GKE pausa las actualizaciones automáticas hasta el final de la asistencia estándar. Si tu clúster está inscrito en el canal extendido, tus nodos pueden permanecer en una versión hasta el final de la asistencia extendida. Para obtener más detalles sobre las actualizaciones automáticas de nodos al final de la asistencia, consulta Actualizaciones automáticas al final de la asistencia.

Si no migras desde estas funciones, cuando la versión 1.32 llegue al final de la asistencia y los nodos de tu clúster se actualicen automáticamente a la versión 1.33, es posible que experimentes los siguientes problemas con tus clústeres:

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

Identifica los clústeres afectados

GKE supervisa tus clústeres y usa el servicio de recomendación para proporcionar orientación a través de estadísticas y recomendaciones para identificar 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 versiones posteriores:

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

Obtén estadísticas y recomendaciones

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

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

Migra desde funciones obsoletas

Revisa el siguiente contenido para comprender cómo migrar desde las funciones que se dejaron de usar con containerd 2.

Migra las imágenes de Docker de esquema 1

Identifica las cargas de trabajo que usan imágenes que se deben migrar y, luego, migra esas cargas de trabajo.

Cómo encontrar las imágenes que se migrarán

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

Usa estadísticas y recomendaciones, o Cloud Logging

Como se explica en la sección Cómo identificar los 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 verificar 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 transcurrieron más de 30 días desde que se extrajo la imagen, es posible que no veas registros de ella.

Usa el comando ctr directamente en un nodo

Para consultar un nodo específico y devolver todas las imágenes no borradas que se extrajeron como esquema 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 problemas de un nodo específico y no ves entradas de registro en Cloud Logging porque pasaron más de 30 días desde que se extrajo la imagen.

Usa 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 verificar la versión del esquema de una imagen:

crane manifest $tagged_image | jq .schemaVersion

Prepara las cargas de trabajo

Para preparar las cargas de trabajo que ejecutan imágenes de Docker de esquema 1, debes migrarlas a imágenes de Docker de esquema 2 o imágenes de Open Container Initiative (OCI). Considera las siguientes opciones para la migración:

  • Busca una imagen de reemplazo: Es posible que encuentres una imagen de código abierto o proporcionada por el proveedor que esté disponible públicamente.
  • Convierte la imagen existente: Si no encuentras una imagen de reemplazo, puedes convertir las imágenes existentes de Docker Schema 1 en imágenes de OCI con los siguientes pasos:
    1. Extrae la imagen de Docker en Containerd, que la convierte automáticamente en una imagen de OCI.
    2. Envía la nueva imagen OCI a tu registro.

Migra de la API de CRI v1alpha2

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

Identifica las cargas de trabajo que podrían verse afectadas

Puedes usar diferentes técnicas para identificar las cargas de trabajo que podrían necesitar migración. Estas técnicas pueden generar falsos positivos que debes investigar más a fondo para determinar que no se necesita ninguna acción.

Usa las estadísticas y las recomendaciones

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

Cuando veas estadísticas en la consola de Google Cloud , consulta el panel de la barra lateralMigra tus cargas de trabajo de la API de CRI v1alpha2 obsoleta. En la tabla Cargas de trabajo para verificar de este panel, se enumeran las cargas de trabajo que podrían verse afectadas. Esta lista incluye cualquier carga de trabajo que no administre GKE y que tenga volúmenes hostPath que contengan la ruta de acceso del socket de containerd (por ejemplo, /var/run/containerd/containerd.sock o /run/containerd/containerd.sock).

Es importante que comprendas lo siguiente:

  • La lista de cargas de trabajo que se deben verificar puede contener falsos positivos. Úsala solo para investigar. El hecho de que una carga de trabajo aparezca en esta lista no significa de manera definitiva que esté usando la API obsoleta, y la presencia de un falso positivo no pausará las actualizaciones automáticas. La pausa se basa solo en el uso observado realmente de la API obsoleta.
  • Es posible que esta lista esté vacía o incompleta. Es posible que la lista esté vacía o incompleta si las cargas de trabajo que usan la API obsoleta fueron de corta duración y no se estaban ejecutando cuando GKE realizó su verificación periódica. La presencia de la recomendación en sí significa que se detectó el uso de la API de CRI v1alpha2 en al menos un nodo del clúster. Las actualizaciones automáticas se reanudan después de que no se detecta el uso de la API obsoleta durante 14 días.

Por lo tanto, recomendamos que realices una investigación más exhaustiva con los siguientes métodos para confirmar el uso real de la API.

Verifica si hay 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 de CRI v1alpha2. Es posible que debas comunicarte con los proveedores respectivos para verificar qué versiones de su software son compatibles.

Usa kubectl

El siguiente comando te ayuda a encontrar cargas de trabajo potencialmente afectadas buscando aquellas que acceden al socket de containerd. Utiliza una lógica similar a la que se usa para la tabla Cargas de trabajo para verificar en la recomendación de la consola de Google Cloud . Devuelve las cargas de trabajo que no administra GKE y que tienen volúmenes hostPath, incluida la ruta de acceso del socket. Al igual que la recomendación, esta búsqueda 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
'
Usa el registro de eBPF para identificar a los llamadores de la API

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

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

Estas herramientas usan el filtro de paquetes Berkeley extendido (eBPF) para hacer un seguimiento de las conexiones al socket containerd y correlacionar las conexiones con las llamadas a la API obsoleta reales.

Al correlacionar las marcas de tiempo de estas dos herramientas, puedes identificar la carga de trabajo exacta que realiza la llamada a la API en desuso. Este método proporciona un mayor grado de confianza que la verificación de los volúmenes de hostPath por sí solos, ya que observa las conexiones de sockets reales y el uso de la API.

Para obtener instrucciones detalladas sobre cómo implementar y usar estas herramientas, y cómo interpretar sus registros, consulta Cómo rastrear 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 obsoleta, pero la recomendación permanece activa, consulta Cómo obtener asistencia.

Después de identificar una carga de trabajo que usa la API de CRI v1alpha2, ya sea a través de los métodos anteriores o inspeccionando tu base de código, debes actualizar su código para que use la API de v1.

Código de la aplicación de actualización

Para actualizar tu aplicación, quita el lugar donde la aplicación importa la biblioteca cliente de k8s.io/cri-api/pkg/apis/runtime/v1alpha2 y modifica el código para usar la versión v1 de la API. Este paso implica cambiar la ruta de importación y actualizar la forma en que tu 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{})

    ...
  }

Aquí, la aplicación importa la biblioteca v1alpha2 y la usa para emitir RPC. Si los RPC usan la conexión al socket de containerd, esta aplicación está haciendo que GKE detenga 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 Golang problemáticas, ejecuta el siguiente comando para buscar la ruta de importación v1alpha2:

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

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

    Por ejemplo, reemplaza el siguiente código de la 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"

Migra desde las propiedades de configuración de containerd obsoletas

Las propiedades de configuración de containerd registry.auths, registry.configs y registry.mirrors en el complemento de CRI están obsoletas y se quitarán en containerd 2.2, con una versión de GKE aún por anunciar. Sin embargo, registry.configs.tls ya se quitó en containerd 2.0.

Identifica las cargas de trabajo

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

Usa las estadísticas y las recomendaciones

Como enfoque inicial, puedes usar las estadísticas y las recomendaciones para encontrar clústeres que usen las propiedades de configuración de containerd que quedaron obsoletas. Esto requiere una versión mínima de GKE. Para obtener más información sobre este enfoque, consulta Cómo identificar los clústeres afectados.

Cuando veas estadísticas en la consola de Google Cloud , consulta el panel de la barra lateralMigra tu configuración de containerd del campo de autorizaciones de registro de CRI obsoleto oMigra tu configuración de containerd del campo de duplicados de registro de CRI obsoleto. Para encontrar cargas de trabajo que podrían acceder a la configuración de containerd, consulta la sección Cargas de trabajo para verificar.

Usa kubectl

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

Para ubicar las cargas de trabajo que modifican la configuración de containerd, busca 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 podría acceder a otros archivos en estos directorios que no son 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 maneras menos comunes.

Ejecuta el siguiente comando para verificar 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
'

Migra de las propiedades auths o configs.auth del registro de CRI

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 usan esas imágenes al campo imagePullSecrets. Para obtener más información, consulta Cómo extraer una imagen de un registro privado.

Para identificar y migrar las cargas de trabajo que usan las propiedades auths o configs.auth en desuso, revisa las siguientes instrucciones.

Busca los detalles de autenticación de tu registro

Puedes encontrar los detalles de autenticación de tu registro de una de las siguientes maneras:

  • Revisa las secciones auths y configs.auth del registro de CRI 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 con los métodos descritos anteriormente para identificar cargas de trabajo. GKE no usa estos parámetros de configuración para sus cargas de trabajo del sistema.

Si usas la propiedad registry.configs.auth, los detalles de autenticación podrían verse de la siguiente manera:

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

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

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

  2. Para identificar qué cargas de trabajo se deben migrar al campo imagePullSecrets, ejecuta 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 Secret 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 Secrets que creaste en el paso anterior.

    Como alternativa, si necesitas migrar una gran cantidad de cargas de trabajo, puedes implementar un MutatingAdmissionWebhook para agregar el campo imagePullSecrets.

Actualiza la configuración de containerd para dejar de establecer autorizaciones de registro

Después de migrar tus cargas de trabajo para que usen el campo imagePullSecrets, debes actualizar las cargas de trabajo que modifican tu configuración de containerd para que dejen de establecer autorizaciones de registro. Para cualquier carga de trabajo que hayas identificado como modificadora de la configuración, modifícala para que deje de establecer autenticaciones de registro.

Realiza pruebas con un grupo de nodos nuevo y migra las cargas de trabajo a ese grupo

Para mitigar el riesgo de causar problemas con tus cargas de trabajo, haz lo siguiente:

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

Migra de la propiedad configs.tls del registro de CRI

Si tus cargas de trabajo usan la propiedad registry.configs.tls, debes migrarlas para acceder a registros privados con certificados de CA privados.

Sigue las instrucciones para migrar desde DaemonSets de configuración. Este proceso se realiza con los siguientes pasos:

  1. Actualiza tus cargas de trabajo que modifican la configuración de containerd para que dejen de establecer detalles de TLS.
  2. Almacena los certificados en Secret Manager.
  3. Crea un archivo de configuración del entorno de ejecución que apunte a tus certificados.
  4. Crea un grupo de nodos nuevo y prueba que tus cargas de trabajo que usan imágenes alojadas desde el registro privado funcionen según lo esperado.
  5. Aplica la configuración a un clúster nuevo y comienza a ejecutar las cargas de trabajo en ese clúster, o bien aplica la configuración al clúster existente. Aplicar la configuración al clúster existente podría interrumpir otras cargas de trabajo existentes. Para obtener más información sobre estos dos enfoques, consulta Crea 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, ya que podrías tener problemas con containerd.

Obtenga asistencia

Si aún no puedes determinar la fuente de las llamadas a la API en desuso y las recomendaciones siguen activas, considera el siguiente paso: