Migra de Docker a imágenes de nodo containerd

Estándar

En esta página, se muestra cómo migrar tu clúster de Google Kubernetes Engine (GKE) estándar y los grupos de nodos a imágenes de nodo que usan el entorno de ejecución del contenedor de containerd.

Descripción general

Los nodos de Kubernetes usan el entorno de ejecución del contenedor para iniciar, administrar y detener contenedores que se ejecutan en Pods. El entorno de ejecución de containerd es un entorno de ejecución de contenedor estándar de la industria que es compatible con GKE.

El entorno de ejecución de containerd proporciona la abstracción por capas que permite la implementación de un amplio conjunto de funciones comogVisor y Transmisión de imágenes para extender la funcionalidad de GKE. El entorno de ejecución de containerd se considera el recurso más eficiente y seguro que el entorno de ejecución de Docker.

Para migrar el entorno de ejecución del contenedor, haz lo siguiente:

Identifica los nodos que usan el entorno de ejecución de Docker
Verifica el impacto de la migración
Cambia la imagen de nodo

Antes de comenzar

Antes de comenzar, asegúrate de haber realizado las siguientes tareas:

Habilita la API de Google Kubernetes Engine.

Habilitar la API de Google Kubernetes Engine

Si deseas usar Google Cloud CLI para esta tarea, instala y, luego, inicializa gcloud CLI. Si ya instalaste gcloud CLI, ejecuta gcloud components update para obtener la versión más reciente.
Nota: Para las instalaciones de gcloud CLI existentes, asegúrate de configurar las propiedades compute/region y compute/zone. Cuando configuras las ubicaciones predeterminadas, puedes evitar errores en la CLI de gcloud como el siguiente: One of [--zone, --region] must be supplied: Please specify location.

Identifica los nodos que usan el entorno de ejecución de Docker

Puedes verificar qué nodos usan imágenes de nodo basadas en Docker mediante los siguientes métodos:

Usa una secuencia de comandos para iterar sobre todos los nodos en todos los clústeres de GKE en tu proyecto de Google Cloud.
Usa Google Cloud CLI, kubectl o la consola de Google Cloud para identificar las imágenes de los nodos.
Usa estadísticas y recomendaciones de baja para identificar clústeres y nodos en zonas o regiones específicas en un proyecto de Google Cloud.

Te recomendamos que uses una secuencia de comandos para identificar con rapidez todos los nodos que necesitas migrar.

Usa una secuencia de comandos para identificar nodos de Docker

La siguiente secuencia de comandos itera en cada nodo de cada clúster de tus proyectos disponibles y proporciona recomendaciones prácticas, como las siguientes:

Si el aprovisionamiento automático de nodos está configurado para imágenes de Docker
Equivalentes sugeridos de imágenes de nodos de containerd para la migración
Versiones de imagen de nodo sugeridas para la migración
Comandos sugeridos para ejecutar a fin de migrar la configuración y los nodos identificados

La secuencia de comandos ignora los clústeres de Autopilot de GKE, que usan Container-Optimized OS con la imagen de nodo de containerd de forma predeterminada.

Ejecuta la siguiente secuencia de comandos:

for project in $(gcloud projects list --format="value(projectId)")
do
  echo "ProjectId: $project"
  for clusters in $( \
    gcloud container clusters list \
      --project $project \
      --format="csv[no-heading](name,location,autopilot.enabled,currentMasterVersion,autoscaling.enableNodeAutoprovisioning,autoscaling.autoprovisioningNodePoolDefaults.imageType)")
  do
    IFS=',' read -r -a clustersArray <<< "$clusters"
    cluster_name="${clustersArray[0]}"
    cluster_zone="${clustersArray[1]}"
    cluster_isAutopilot="${clustersArray[2]}"
    cluster_version="${clustersArray[3]}"
    cluster_minorVersion=${cluster_version:0:4}
    cluster_autoprovisioning="${clustersArray[4]}"
    cluster_autoprovisioningImageType="${clustersArray[5]}"

    if [ "$cluster_isAutopilot" = "True" ]; then
      echo "  Cluster: $cluster_name (autopilot) (zone: $cluster_zone)"
      echo "    Autopilot clusters are running Containerd."
    else
      echo "  Cluster: $cluster_name (zone: $cluster_zone)"

      if [ "$cluster_autoprovisioning" = "True" ]; then
        if [ "$cluster_minorVersion"  \< "1.20" ]; then
          echo "    Node autoprovisioning is enabled, and new node pools will have image type 'COS'."
          echo "    This settings is not configurable on the current version of a cluster."
          echo "    Please upgrade you cluster and configure the default node autoprovisioning image type."
          echo "    "
        else
          if [ "$cluster_autoprovisioningImageType" = "COS" ]; then
            echo "    Node autoprovisioning is configured to create new node pools of type 'COS'."
            echo "    Run the following command to update:"
            echo "    gcloud container clusters update '$cluster_name' --project '$project' --zone '$cluster_zone' --enable-autoprovisioning --autoprovisioning-image-type='COS_CONTAINERD'"
            echo "    "
          fi

          if [ "$cluster_autoprovisioningImageType" = "UBUNTU" ]; then
            echo "    Node autoprovisioning is configured to create new node pools of type 'UBUNTU'."
            echo "    Run the following command to update:"
            echo "    gcloud container clusters update '$cluster_name' --project '$project' --zone '$cluster_zone' --enable-autoprovisioning --autoprovisioning-image-type='UBUNTU_CONTAINERD'"
            echo "    "
          fi
        fi
      fi

      for nodepools in $( \
        gcloud container node-pools list \
          --project $project \
          --cluster $cluster_name \
          --zone $cluster_zone \
          --format="csv[no-heading](name,version,config.imageType)")
      do
        IFS=',' read -r -a nodepoolsArray <<< "$nodepools"
        nodepool_name="${nodepoolsArray[0]}"
        nodepool_version="${nodepoolsArray[1]}"
        nodepool_imageType="${nodepoolsArray[2]}"

        nodepool_minorVersion=${nodepool_version:0:4}

        echo "    Nodepool: $nodepool_name, version: $nodepool_version ($nodepool_minorVersion), image: $nodepool_imageType"

        minorVersionWithRev="${nodepool_version/-gke./.}"
        linuxGkeMinVersion="1.14"
        windowsGkeMinVersion="1.21.1.2200"

        suggestedImageType="COS_CONTAINERD"

        if [ "$nodepool_imageType" = "UBUNTU" ]; then
          suggestedImageType="UBUNTU_CONTAINERD"
        elif [ "$nodepool_imageType" = "WINDOWS_LTSC" ]; then
          suggestedImageType="WINDOWS_LTSC_CONTAINERD"
        elif [ "$nodepool_imageType" = "WINDOWS_SAC" ]; then
          suggestedImageType="WINDOWS_SAC_CONTAINERD"
        fi

        tab=$'\n      ';
        nodepool_message="$tab Please update the nodepool to use Containerd."
        nodepool_message+="$tab Make sure to consult with the list of known issues https://cloud.google.com/kubernetes-engine/docs/concepts/using-containerd#known_issues."
        nodepool_message+="$tab Run the following command to upgrade:"
        nodepool_message+="$tab "
        nodepool_message+="$tab gcloud container clusters upgrade '$cluster_name' --project '$project' --zone '$cluster_zone' --image-type '$suggestedImageType' --node-pool '$nodepool_name'"
        nodepool_message+="$tab "

        # see https://cloud.google.com/kubernetes-engine/docs/concepts/node-images
        if [ "$nodepool_imageType" = "COS_CONTAINERD" ] || [ "$nodepool_imageType" = "UBUNTU_CONTAINERD" ] ||
           [ "$nodepool_imageType" = "WINDOWS_LTSC_CONTAINERD" ] || [ "$nodepool_imageType" = "WINDOWS_SAC_CONTAINERD" ]; then
          nodepool_message="$tab Nodepool is using Containerd already"
        elif ( [ "$nodepool_imageType" = "WINDOWS_LTSC" ] || [ "$nodepool_imageType" = "WINDOWS_SAC" ] ) &&
               [ "$(printf '%s\n' "$windowsGkeMinVersion" "$minorVersionWithRev" | sort -V | head -n1)" != "$windowsGkeMinVersion" ]; then
          nodepool_message="$tab Upgrade nodepool to the version that supports Containerd for Windows"
        elif [ "$(printf '%s\n' "$linuxGkeMinVersion" "$minorVersionWithRev" | sort -V | head -n1)" != "$linuxGkeMinVersion" ]; then
          nodepool_message="$tab Upgrade nodepool to the version that supports Containerd"
        fi
        echo "$nodepool_message"
      done
    fi # not autopilot
  done
done

# Sample output:
#
# ProjectId:  my-project-id
#  Cluster: autopilot-cluster-1 (autopilot) (zone: us-central1)
#    Autopilot clusters are running Containerd.
#  Cluster: cluster-1 (zone: us-central1-c)
#    Nodepool: default-pool, version: 1.18.12-gke.1210 (1.18), image: COS
#
#       Please update the nodepool to use Containerd.
#       Make sure to consult with the list of known issues https://cloud.google.com/kubernetes-engine/docs/concepts/using-containerd#known_issues.
#       Run the following command to upgrade:
#
#       gcloud container clusters upgrade 'cluster-1' --project 'my-project-id' --zone 'us-central1-c' --image-type 'COS_CONTAINERD' --node-pool 'default-pool'
#
#    Nodepool: pool-1, version: 1.18.12-gke.1210 (1.18), image: COS
#
#       Please update the nodepool to use Containerd.
#       Make sure to consult with the list of known issues https://cloud.google.com/kubernetes-engine/docs/concepts/using-containerd#known_issues.
#       Run the following command to upgrade:
#
#       gcloud container clusters upgrade 'cluster-1' --project 'my-project-id' --zone 'us-central1-c' --image-type 'COS_CONTAINERD' --node-pool 'pool-1'
#
#    Nodepool: winpool, version: 1.18.12-gke.1210 (1.18), image: WINDOWS_SAC
#
#       Upgrade nodepool to the version that supports Containerd for Windows
#
#  Cluster: another-test-cluster (zone: us-central1-c)
#    Nodepool: default-pool, version: 1.20.4-gke.400 (1.20), image: COS_CONTAINERD
#
#      Nodepool is using Containerd already
#

Identifica las imágenes de nodo mediante Google Cloud

Puedes verificar las imágenes de nodo de los nodos existentes mediante Google Cloud CLI, kubectl o la consola de Google Cloud.

gcloud

Ejecuta el siguiente comando:

gcloud container node-pools list \
    --cluster=CLUSTER_NAME \
    --format="table(name,version,config.imageType)"

Reemplaza CLUSTER_NAME por el nombre del clúster.

El resultado es similar a este:

NAME          NODE_VERSION    IMAGE_TYPE
default-pool  1.19.6-gke.600  UBUNTU

Console

Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

Ir a Google Kubernetes Engine
En la lista de clústeres, haz clic en el nombre del clúster que deseas verificar.
Selecciona la pestaña Nodos.
En la sección Grupos de nodos, consulta el valor en la columna Tipo de imagen.

kubectl

Ejecuta el siguiente comando:

kubectl get nodes -o wide

El resultado es similar a este:

# For Docker runtime
NAME         STATUS   VERSION             OS-IMAGE                             CONTAINER-RUNTIME
gke-node-1   Ready    v1.16.15-gke.6000   Container-Optimized OS from Google   docker://19.3.1
gke-node-2   Ready    v1.16.15-gke.6000   Container-Optimized OS from Google   docker://19.3.1
gke-node-3   Ready    v1.16.15-gke.6000   Container-Optimized OS from Google   docker://19.3.1

El valor en la columna CONTAINER-RUNTIME muestra el entorno de ejecución y la versión.

Identifica clústeres con estadísticas y recomendaciones de baja

GKE detecta el uso de algunas APIs y funciones obsoletas, incluidas las imágenes de nodo basadas en Docker. Para obtener más información, consulta Bajas de GKE.

Como parte de la detección del uso de bajas, GKE genera estadísticas y recomendaciones que identifican el uso de imágenes de nodo basadas en Docker con el subtipo de estadística DEPRECATION_K8S_1_24_DOCKERSHIM.

Una sincronización de estadística y recomendación identifica un clúster que tiene nodos que usan imágenes de nodo basadas en Docker. Cada estadística y recomendación proporciona una lista de los grupos de nodos específicos en un clúster que usan imágenes de nodo basadas en Docker y se deben migrar a imágenes de nodo en contenedores.

Para comenzar, sigue las instrucciones a fin de ver las estadísticas y recomendaciones de baja. Para los comandos de gcloud CLI, usa la siguiente marca a fin de ver solo estadísticas de esta baja:

--filter="insightSubtype:DEPRECATION_K8S_1_24_DOCKERSHIM"

Una vez que identifiques qué grupos de nodos del clúster usan imágenes de nodo basadas en Docker, sigue las instrucciones para cambiar la imagen del nodo a una imagen de nodo containerd.

Verifica el impacto de la migración

Antes de migrar los clústeres de producción y los grupos de nodos a imágenes de nodo que usan containerd, recomendamos que pruebes el impacto de la migración en un entorno de etapa de pruebas para minimizar el riesgo de tener problemas.

Recomendamos que cuando migres los nodos, lo hagas sin importar la actualización de los nodos, de modo que puedas aislar las variables cuando verifiques las cargas de trabajo con la nueva configuración. Además, si actualizas el grupo de nodos a la versión 1.24 al mismo tiempo, no puedes revertir el cambio, ya que 1.24 no es compatible con nodos de Docker y no puedes cambiar a una versión inferior de versiones secundarias.

Cambia la imagen del nodo a una imagen de containerd

Si usaste la secuencia de comandos para identificar tus nodos de Docker, puedes usar los comandos sugeridos que muestra la secuencia de comandos para cambiar tu configuración de aprovisionamiento automático de nodos y tus imágenes de nodo a los equivalentes en containerd.

También puedes migrar nodos de un tipo de imagen de Docker a un tipo de imagen de containerd mediante la actualización del grupo de nodos y la configuración de una imagen diferente con la CLI de gcloud o la consola de Google Cloud.

GKE usa la estrategia de actualización de nodos y la configuración seleccionadas para migrar la imagen de un nodo. Para esta migración, te recomendamos que uses la estrategia de actualización azul-verde, ya que si tus cargas de trabajo tienen problemas con la imagen de nodo nueva durante la actualización, puedes revertir al entorno anterior con la configuración original de la imagen de nodo.

gcloud

Ejecuta el siguiente comando:

gcloud container clusters upgrade CLUSTER_NAME \
    --image-type=NODE_IMAGE \
    --node-pool=POOL_NAME \
    --cluster-version=NODE_VERSION

Reemplaza lo siguiente:

NODE_IMAGE: La imagen de nodo que deseas que usen los nodos.
POOL_NAME: El nombre del grupo de nodos que se migrará.
NODE_VERSION: la versión existente del grupo de nodos. Te recomendamos configurar esta marca porque, de lo contrario, GKE intenta actualizar la versión del grupo de nodos a la versión del plano de control y actualizar la imagen de nodo en la misma operación. Si el plano de control ejecuta la versión 1.24, el comando falla. Si el plano de control está en ejecución la versión 1.23, el comando se ejecuta de forma correcta, lo que evita que pruebes los dos cambios (actualización de versión y actualización de imagen) de forma aislada.

El resultado es similar a este:

NAME          NODE_VERSION    IMAGE_TYPE
default-pool  1.23.6-gke.600  UBUNTU_CONTAINERD

Console

Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

Ir a Google Kubernetes Engine
En la lista de clústeres, haz clic en el nombre del clúster que deseas verificar.
Haz clic en la pestaña Nodos.
En la sección Grupos de nodos, haz clic en el nombre del grupo de nodos que deseas modificar.
En la página Detalles del grupo de nodos, haz clic en Editar.
En la sección Nodos, en Tipo de imagen, haz clic en Cambiar.
Selecciona uno de los tipos de imágenes de containerd.
Haz clic en Cambiar.

Revierte a las imágenes de nodo de Docker

Si tus nodos se migraron automáticamente o de forma manual a nodos de containerd y viste un problema con tus cargas de trabajo, sigue estos pasos para volver a las imágenes de nodo de Docker:

Elige el siguiente paso según el estado de la operación:
- Si la operación aún está en curso, puedes cancelarla y revertirla.
- Si se completó la operación, consulta los pasos de la sección anterior y selecciona la imagen de Docker equivalente.
Configura una exclusión de mantenimiento para prevenir temporalmente que GKE vuelva a intentar la migración.
Investiga la causa raíz del problema para poder migrar desde Docker y asegúrate de que tu clúster ejecute una versión compatible de GKE.
Vuelve a intentar cambiar la imagen del nodo a una imagen de containerd. Si quitas la exclusión de mantenimiento, GKE volverá a activar la operación.

Actualiza la configuración de la herramienta de infraestructura como código (IaC)

Si usas herramientas de IaC como Terraform, Ansible o Pulumi para administrar los clústeres de GKE, asegúrate de actualizar los parámetros de configuración a fin de usar imágenes de nodo de containerd para evitar que las herramientas concilien el estado deseado con anterioridad con el nuevo estado actual. Por ejemplo, el proveedor de Terraform para GKE admite tipos de imágenes configurables.

Actualiza la configuración para que la herramienta no vuelva a actualizar la imagen de nodo a una imagen de nodo basada en Docker después de migrar a imágenes de nodo containerd.

Cambia la imagen de nodo predeterminada para el aprovisionamiento automático de nodos

Si usas el aprovisionamiento automático de nodos en tu clúster, cambia el tipo de imagen predeterminado a una imagen de nodo de containerd. Cambiar el tipo de imagen predeterminado solo se aplica a los grupos de nodos nuevos aprovisionados de forma automática. Debes cambiar de forma manual la imagen del nodo para los grupos de nodos aprovisionados de forma automática.

Puedes cambiar el tipo predeterminado de imagen de aprovisionamiento automático de nodos mediante la CLI de gcloud o un archivo de configuración.

gcloud

Ejecuta el siguiente comando:

gcloud container clusters update CLUSTER_NAME \
    --enable-autoprovisioning \
    --autoprovisioning-image-type=IMAGE_TYPE

Reemplaza lo siguiente:

CLUSTER_NAME: es el nombre del clúster que se actualizará.
IMAGE_TYPE: es el tipo de imagen de nodo, que puede ser una de las siguientes opciones:
- cos_containerd
- ubuntu_containerd
  
  Nota: Para ubuntu_containerd, especifica --autoprovisioning-scopes=https://www.googleapis.com/auth/devstorage.read_only en el comando.

Archivo

Puedes usar un archivo de configuración YAML a fin de cambiar el tipo de imagen de nodo predeterminado para el aprovisionamiento automático de nodos. Cuando usas un archivo, también debes especificar valores máximos para los recursos de CPU y memoria.

Guarda el siguiente archivo YAML:
```
resourceLimits:
  - resourceType: 'cpu'
      minimum: 4
      maximum: 10
  - resourceType: 'memory'
      maximum: 64
autoprovisioningNodePoolDefaults:
  imageType: 'IMAGE_TYPE'
```
Reemplaza IMAGE_TYPE por el tipo de imagen de containerd.

Nota: Para ubuntu_containerd, agrega scopes: https://www.googleapis.com/auth/devstorage.read_only al archivo de configuración.

Aplica la configuración:

gcloud container clusters update CLUSTER_NAME \
    --enable-autoprovisioning \
    --autoprovisioning-config-file=FILE_NAME

Reemplaza FILE_NAME por la ruta de acceso al archivo de configuración.

Soluciona problemas

Para solucionar problemas y ver problemas conocidos con soluciones alternativas, consulta Soluciona problemas del entorno de ejecución del contenedor.

Migra de Docker a imágenes de nodo containerd

Descripción general

Antes de comenzar

Identifica los nodos que usan el entorno de ejecución de Docker

Usa una secuencia de comandos para identificar nodos de Docker

Identifica las imágenes de nodo mediante Google Cloud

gcloud

Console

kubectl

Identifica clústeres con estadísticas y recomendaciones de baja

Verifica el impacto de la migración

Cambia la imagen del nodo a una imagen de containerd

gcloud

Console

Revierte a las imágenes de nodo de Docker

Actualiza la configuración de la herramienta de infraestructura como código (IaC)

Cambia la imagen de nodo predeterminada para el aprovisionamiento automático de nodos

gcloud

Archivo

Soluciona problemas

¿Qué sigue?