Usa la transmisión de imágenes para extraer imágenes de contenedor

En esta página, se muestra cómo usar la transmisión de imágenes en Google Kubernetes Engine (GKE) para extraer imágenes de contenedor mediante la transmisión de datos de imágenes según tus necesidades.

Los clústeres de Autopilot usan automáticamente la transmisión de imágenes para extraer imágenes aptas. Las instrucciones de esta página para habilitar y inhabilitar la transmisión de imágenes se aplican a los clústeres estándar.

Descripción general

La transmisión de imágenes es un método para extraer imágenes de contenedores en el que GKE transmite datos de imágenes aptas según lo que soliciten tus aplicaciones. Puedes usar la transmisión de imágenes para permitir que tus cargas de trabajo se inicialicen sin esperar a que se descargue toda la imagen, lo que genera mejoras significativas en los tiempos de inicialización. El tiempo de extracción reducido te brinda beneficios que incluyen lo siguiente:

  • Ajuste de escala automático más rápido
  • Menor latencia cuando se extraen imágenes grandes
  • Inicio más rápido de los pods

Con la transmisión de imágenes, GKE usa un sistema de archivos remoto como sistema de archivos raíz para cualquier contenedor que use imágenes de contenedor aptas. GKE transmite datos de imágenes desde el sistema de archivos remoto según lo necesiten tus cargas de trabajo. Sin la transmisión de imágenes, GKE descarga la imagen de contenedor completa en cada nodo y la usa como sistema de archivos raíz para tus cargas de trabajo.

Mientras se transmiten los datos de imagen, GKE descarga la imagen de contenedor completa en el disco local, en segundo plano, y la almacena en caché. Luego, GKE entrega solicitudes de lectura de datos futuras desde la imagen en caché.

Cuando implementas cargas de trabajo que necesitan leer archivos específicos en la imagen de contenedor, el backend de transmisión de imágenes solo entrega los archivos solicitados.

Requisitos

Debes cumplir con los siguientes requisitos para usar la transmisión de imágenes en los clústeres de GKE Autopilot y Standard:

  • Debes habilitar la API del sistema de archivos de contenedor.

    Habilita la API del sistema de archivos de contenedor

  • Debes usar Container-Optimized OS con la imagen de nodo containerd. Los nodos de Autopilot siempre usan esta imagen de nodo.

  • Tus imágenes de contenedor deben almacenarse en repositorios estándar o remotos en Artifact Registry, o bien en registros públicos en Docker Hub.

  • Si habilitas nodos privados en tu clúster, debes habilitar el Acceso privado a Google en la subred para que tus nodos accedan al servicio de transmisión de imágenes.

  • Si los Controles del servicio de VPC protegen las imágenes de contenedor y usas la transmisión de imágenes, también debes incluir la API de transmisión de imágenes (containerfilesystem.googleapis.com) en el perímetro de servicio.

  • Si los nodos de GKE del clúster no usan la cuenta de servicio predeterminada, debes asegurarte de que tu cuenta de servicio personalizada tenga el rol Consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer) de IAM en el proyecto que aloja la imagen de contenedor.

Limitaciones

  • Las imágenes de contenedor que usan el manifiesto de imágenes de V2, versión de esquema 1 no son aptas.
  • No se admiten imágenes de contenedor con capas duplicadas. GKE descarga estas imágenes sin transmitir los datos. Revisa la imagen de contenedor en busca de capas vacías o duplicadas.
  • Si las cargas de trabajo leen muchos archivos en una imagen durante la inicialización, es posible que notes un aumento en los tiempos de inicialización debido a la latencia que agregan las lecturas de archivos remotos.
  • Si tus cargas de trabajo requieren que una gran proporción de la imagen esté disponible antes de que se pueda ejecutar el código, es posible que veas una demora entre el momento en que kubelet inicia el contenedor y el momento en que el contenedor comienza a enviar registros.
  • Es posible que no notes los beneficios de la transmisión de imágenes durante la primera extracción de una imagen apta. Sin embargo, después de que la transmisión de imágenes almacena en caché la imagen, las futuras imágenes extraen cualquier beneficio del clúster de la transmisión de imágenes.
  • Los clústeres de GKE Standard usan la configuración a nivel de clúster para determinar si deseas habilitar la transmisión de imágenes en grupos de nodos nuevos creados con el aprovisionamiento automático de nodos. Sin embargo, no puedes usar la separación de cargas de trabajo para crear grupos de nodos con la transmisión de imágenes habilitada cuando está inhabilitada a nivel de clúster.

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 el comando gcloud components update para obtener la versión más reciente. Es posible que las versiones anteriores de gcloud CLI no admitan la ejecución de los comandos que se describen en este documento.

Habilita la transmisión de imágenes en clústeres

Puedes habilitar la transmisión de imágenes en clústeres Standard nuevos o existentes con la marca --enable-image-streaming de gcloud CLI o con laGoogle Cloud consola. Cuando creas un clúster con la marca --enable-image-streaming, la transmisión de imágenes se habilitará en el grupo de nodos predeterminado. Los nuevos grupos de nodos que crees también tendrán habilitada la transmisión de imágenes, a menos que la inhabilites cuando crees los grupos de nodos.

Todos los clústeres de Autopilot usan la transmisión de imágenes para extraer imágenes aptas. Para obtener instrucciones, consulta Configura la versión y el canal de versiones de un nuevo clúster de Autopilot. Las siguientes instrucciones solo se aplican a los clústeres de GKE Standard.

Puedes habilitar la transmisión de imágenes en clústeres existentes que cumplan con los requisitos mediante gcloud CLI o la Google Cloud consola.

gcloud

A fin de actualizar un clúster existente para usar la transmisión de imágenes, ejecuta el siguiente comando mediante la CLI de gcloud:

gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-image-streaming

Reemplaza lo siguiente:

  • CLUSTER_NAME: El nombre de tu clúster.
  • CONTROL_PLANE_LOCATION: Es la ubicación del plano de control de tu clúster.

Console

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

    Ir a Google Kubernetes Engine

  2. Haz clic en el nombre del clúster que deseas modificar.

  3. En la página Clústeres, en la sección Funciones, haz clic en junto a Transmisión de imágenes.

  4. En el cuadro de diálogo Editar transmisión de imágenes, selecciona la casilla de verificación Habilitar la transmisión de imágenes.

  5. Haz clic en Guardar cambios.

Después de modificar el clúster, GKE habilita la transmisión de imágenes en tus grupos de nodos existentes de forma automática y predeterminada. Si habilitaste o inhabilitaste la transmisión de imágenes de forma explícita en grupos de nodos individuales, esos grupos no heredan los cambios en la configuración a nivel del clúster.

Cambiar el parámetro de configuración de transmisión de imágenes respeta la disponibilidad de mantenimiento cuando se actualiza a nivel del clúster, pero no a nivel del grupo de nodos.

Este cambio requiere volver a crear los nodos, lo que puede causar interrupciones en tus cargas de trabajo en ejecución. Para obtener detalles sobre este cambio específico, busca la fila correspondiente en la tabla Cambios manuales que recrean los nodos con una estrategia de actualización de nodos y respetan las políticas de mantenimiento. Para obtener más información sobre las actualizaciones de nodos, consulta Planificación de interrupciones por actualizaciones de nodos.

Verifica que la transmisión de imágenes esté habilitada en un clúster

Puedes verificar si la transmisión de imágenes está habilitada a nivel del clúster con gcloud CLI o la Google Cloud consola.

gcloud

Ejecuta el siguiente comando:

gcloud container clusters describe CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --flatten "nodePoolDefaults.nodeConfigDefaults"

Reemplaza lo siguiente:

  • CLUSTER_NAME: El nombre de tu clúster.
  • CONTROL_PLANE_LOCATION: Es la ubicación del plano de control de tu clúster.

La configuración está habilitada si el resultado es similar al siguiente:

gcfsConfig:
  enabled: true
...

La configuración está inhabilitada si el resultado es similar al siguiente:

gcfsConfig: {}
...

Console

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

    Ir a Google Kubernetes Engine

  2. Haz clic en el nombre del clúster que deseas modificar.

  3. En la página Clústeres, en la sección Funciones, junto a Transmisión de imágenes, se mostrará si la configuración está habilitada.

Habilita la transmisión de imágenes en grupos de nodos

De forma predeterminada, los grupos de nodos heredan la configuración de transmisión de imágenes a nivel de clúster. Puedes habilitar o inhabilitar la transmisión de imágenes en grupos de nodos específicos mediante la CLI de gcloud.

En un grupo de nodos nuevo

Para crear un grupo de nodos nuevo con la transmisión de imágenes habilitada, ejecuta el siguiente comando:

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --image-type="COS_CONTAINERD" \
    --enable-image-streaming

Reemplaza lo siguiente:

  • NODE_POOL_NAME: es el nombre de tu grupo de nodos nuevo.
  • CLUSTER_NAME: el nombre del clúster para el grupo de nodos.
  • CONTROL_PLANE_LOCATION: Es la ubicación de Compute Engine del plano de control de tu clúster. Proporciona una región para los clústeres regionales o una zona para los clústeres zonales.

En un grupo de nodos existente

Puedes habilitar la transmisión de imágenes en grupos de nodos existentes que cumplan con los requisitos.

A fin de actualizar un grupo de nodos existente para usar la transmisión de imágenes, ejecuta el siguiente comando:

gcloud container node-pools update POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-image-streaming

Reemplaza lo siguiente:

  • POOL_NAME: es el nombre de tu grupo de nodos.
  • CLUSTER_NAME: el nombre del clúster para el grupo de nodos.
  • CONTROL_PLANE_LOCATION: Es la ubicación del plano de control de tu clúster.

Cambiar el parámetro de configuración de transmisión de imágenes respeta la disponibilidad de mantenimiento cuando se actualiza a nivel del clúster, pero no a nivel del grupo de nodos.

Este cambio requiere volver a crear los nodos, lo que puede causar interrupciones en tus cargas de trabajo en ejecución. Para obtener detalles sobre este cambio específico, busca la fila correspondiente en la tabla de cambios manuales que recrean los nodos con una estrategia de actualización de nodos sin respetar las políticas de mantenimiento. Para obtener más información sobre las actualizaciones de nodos, consulta Planificación de interrupciones por actualizaciones de nodos.

Verifica que la transmisión de imágenes esté habilitada en un grupo de nodos

Verifica si la transmisión de imágenes está habilitada para un grupo de nodos:

gcloud container node-pools describe POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION

Reemplaza lo siguiente:

  • POOL_NAME: es el nombre de tu grupo de nodos.
  • CLUSTER_NAME: el nombre del clúster para el grupo de nodos.
  • CONTROL_PLANE_LOCATION: Es la ubicación del plano de control de tu clúster.

La configuración está habilitada si el resultado es similar al siguiente:

gcfsConfig:
  enabled: true
...

La configuración está inhabilitada si el resultado es similar al siguiente:

gcfsConfig: {}
...

Programa una carga de trabajo mediante la transmisión de imágenes

Después de habilitar la transmisión de imágenes en tu clúster, GKE usa la transmisión de imágenes de forma automática cuando extrae imágenes de contenedor aptas de Artifact Registry sin necesidad de realizar una configuración adicional.

GKE agrega la etiqueta cloud.google.com/gke-image-streaming: "true" a los nodos en grupos de nodos con la transmisión de imágenes habilitada. En GKE Standard, si habilitas o inhabilitas la transmisión de imágenes en grupos de nodos específicos para que tu clúster tenga una combinación de nodos que usen la transmisión de imágenes y otros que no lo hacen, puedes usar selectores de nodos en las implementaciones para controlar si GKE programa las cargas de trabajo en los nodos que usan la transmisión de imágenes.

En el siguiente ejemplo, programarás una implementación que usa una imagen de contenedor grande en un clúster con la transmisión de imágenes habilitada. Luego, de manera opcional, puedes comparar el rendimiento con una extracción de imagen sin la transmisión de imágenes habilitada.

  1. Crea un clúster nuevo con la transmisión de imágenes habilitada:

    gcloud container clusters create CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-image-streaming \
    --image-type="COS_CONTAINERD"

  2. Obtén credenciales para el clúster:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION

  3. Guarda el siguiente manifiesto como frontend-deployment.yaml:

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
spec:
  replicas: 1
  selector:
    matchLabels:
      app: guestbook
      tier: frontend
  template:
    metadata:
      labels:
        app: guestbook
        tier: frontend
    spec:
      containers:
      - name: php-redis
        image: us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5
        env:
        - name: GET_HOSTS_FROM
          value: "dns"
        resources:
          requests:
            cpu: 100m
            memory: 100Mi
        ports:
        - containerPort: 80

    La imagen de contenedor gb-frontend tiene un tamaño de 327 MB.

  4. Aplica el manifiesto al clúster:

    kubectl apply -f frontend-deployment.yaml

  5. Verifica que GKE haya creado el Deployment:

    kubectl get pods -l app=guestbook

    El resultado es similar a este:

    NAMESPACE    NAME                          READY    STATUS       RESTARTS    AGE
default      frontend-64bcc69c4b-pgzgm     1/1      Completed    0           3s

  6. Obtén el registro de eventos de Kubernetes para ver los eventos de extracción de imágenes:

    kubectl get events --all-namespaces

    El resultado es similar a este:

    NAMESPACE  LAST SEEN  TYPE    REASON          OBJECT                                                 MESSAGE
default    11m        Normal  Pulling         pod/frontend-64bcc69c4b-pgzgm                          Pulling image "us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5"
default    11m        Normal  Pulled          pod/frontend-64bcc69c4b-pgzgm                          Successfully pulled image "us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5" in 1.536908032s
default    11m        Normal  ImageStreaming  node/gke-riptide-cluster-default-pool-f1552ec4-0pjv    Image us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5 is backed by image streaming.
...

    En este resultado, se ilustra lo siguiente:

    • En el evento Pulled, se muestra el tiempo que tarda la transmisión de imágenes en extraer la imagen.

    • En el evento ImageStreaming, se muestra que el nodo usa la transmisión de imágenes para entregar la imagen de contenedor.

Compara el rendimiento con las extracciones de imágenes estándar

En este ejemplo opcional, crearás un clúster nuevo con la transmisión de imágenes inhabilitada y, además, implementarás el Deployment de frontend para comparar el rendimiento con la transmisión de imágenes.

  1. Crea un clúster nuevo con la transmisión de imágenes inhabilitada:

    gcloud container clusters create CLUSTER2_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --image-type="COS_CONTAINERD"

  2. Obtén credenciales para el clúster:

    gcloud container clusters get-credentials CLUSTER2_NAME \
    --location=CONTROL_PLANE_LOCATION

  3. Implementa el Deployment de frontend del ejemplo anterior:

    kubectl apply -f frontend-deployment.yaml

  4. Obtén el registro de eventos de Kubernetes:

    kubectl get events --all-namespaces

    El resultado es similar a este:

     NAMESPACE  LAST SEEN  TYPE    REASON     OBJECT                             MESSAGE
 default    87s        Normal  Pulled     pod/frontend-64bcc69c4b-qwmfp      Successfully pulled image "us-docker.pkg.dev/google-samples/containers/gke/gb-frontend:v5" in 23.929723476s

    Observa el tiempo que GKE tardó en extraer toda la imagen. En este resultado de ejemplo, GKE necesitó casi 24 segundos. Con la transmisión de imágenes habilitada, GKE solo necesitaba 1.5 segundos para extraer los datos de imagen necesarios para el inicio de la carga de trabajo.

Realiza una limpieza

Para evitar cargos, borra los clústeres que creaste en los ejemplos anteriores:

gcloud container clusters delete CLUSTER_NAME CLUSTER2_NAME \
    --location=CONTROL_PLANE_LOCATION

Reemplaza lo siguiente:

  • CLUSTER_NAME: Es el nombre de tu primer clúster.
  • CLUSTER2_NAME: Es el nombre de tu segundo clúster.
  • CONTROL_PLANE_LOCATION: Es la ubicación del plano de control de los clústeres.

Inhabilita la transmisión de imágenes

Si usas GKE Autopilot, no puedes inhabilitar la transmisión de imágenes en clústeres individuales. Puedes inhabilitar la API del sistema de archivos de contenedor, lo que inhabilita la transmisión de imágenes para todo el proyecto.

Si usas clústeres de GKE Standard, puedes inhabilitar la transmisión de imágenes en clústeres individuales o grupos de nodos específicos, como se describe en las siguientes secciones.

Inhabilita la transmisión de imágenes en un clúster de GKE Standard

Puedes inhabilitar la transmisión de imágenes en clústeres de GKE Standard existentes con gcloud CLI o la consola deGoogle Cloud .

gcloud

Para inhabilitar la transmisión de imágenes en un clúster existente, ejecuta el siguiente comando:

gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --no-enable-image-streaming

Reemplaza lo siguiente:

  • CLUSTER_NAME: El nombre de tu clúster.
  • CONTROL_PLANE_LOCATION: Es la ubicación del plano de control de tu clúster.

Console

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

    Ir a Google Kubernetes Engine

  2. Haz clic en el nombre del clúster que deseas modificar.

  3. En la página Clústeres, en Funciones, haz clic en junto a Transmisión de imágenes.

  4. En el cuadro de diálogo Edita la transmisión de imágenes, desmarca la casilla de verificación Habilitar la transmisión de imágenes.

  5. Haz clic en Guardar cambios.

Cambiar el parámetro de configuración de transmisión de imágenes respeta la disponibilidad de mantenimiento cuando se actualiza a nivel del clúster, pero no a nivel del grupo de nodos.

Este cambio requiere volver a crear los nodos, lo que puede causar interrupciones en tus cargas de trabajo en ejecución. Para obtener detalles sobre este cambio específico, busca la fila correspondiente en la tabla Cambios manuales que recrean los nodos con una estrategia de actualización de nodos y respetan las políticas de mantenimiento. Para obtener más información sobre las actualizaciones de nodos, consulta Planificación de interrupciones por actualizaciones de nodos.

En un grupo de nodos nuevo

Para inhabilitar la transmisión de imágenes cuando creas un grupo de nodos nuevo, especifica la marca --no-enable-image-streaming, como en el siguiente comando:

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --no-enable-image-streaming

En un grupo de nodos existente

Para inhabilitar la transmisión de imágenes en un grupo de nodos existente, ejecuta el siguiente comando:

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --no-enable-image-streaming

Reemplaza lo siguiente:

  • NODE_POOL_NAME: es el nombre de tu grupo de nodos.
  • CLUSTER_NAME: el nombre del clúster para el grupo de nodos.
  • CONTROL_PLANE_LOCATION: Es la ubicación del plano de control de tu clúster.

Cambiar el parámetro de configuración de transmisión de imágenes respeta la disponibilidad de mantenimiento cuando se actualiza a nivel del clúster, pero no a nivel del grupo de nodos.

Este cambio requiere volver a crear los nodos, lo que puede causar interrupciones en tus cargas de trabajo en ejecución. Para obtener detalles sobre este cambio específico, busca la fila correspondiente en la tabla de cambios manuales que recrean los nodos con una estrategia de actualización de nodos sin respetar las políticas de mantenimiento. Para obtener más información sobre las actualizaciones de nodos, consulta Planificación de interrupciones por actualizaciones de nodos.

Reserva de memoria para la transmisión de imágenes

GKE reserva recursos de memoria para la transmisión de imágenes, además de la memoria reservada para que se ejecuten los componentes del sistema de nodos. GKE no reserva recursos de CPU adicionales para la transmisión de imágenes. En los clústeres de GKE Standard, esta reserva cambia los recursos de memoria disponibles para que solicites en tus Pods. En GKE Autopilot, GKE administra las asignaciones del sistema, por lo que no hay impacto en la programación de tus cargas de trabajo.

Si deseas obtener detalles sobre las reservas de memoria que GKE realiza para los componentes de nodo, consulta Arquitectura del clúster estándar.

En los nodos que usan la transmisión de imágenes, GKE realiza las siguientes reservas de memoria adicionales para las reservas nuevas:

  • No hay una memoria adicional para las máquinas con menos de 1 GiB de memoria
  • Un 1% de los primeros 4 GiB de memoria
  • Un 0.8% de los siguientes 4 GiB de memoria (hasta 8 GiB)
  • Un 0.4% de los siguientes 8 GiB de memoria (hasta 16 GiB)
  • Un 0.24% de los siguientes 112 GiB de memoria (hasta 128 GiB)
  • Un 0.08% de cualquier memoria por encima de 128 GiB

Soluciona problemas

En las siguientes secciones, se proporcionan sugerencias para solucionar problemas relacionados con Image streaming. Para obtener asesoramiento sobre la solución de problemas de extracción de imágenes estándar, consulta Soluciona problemas de extracción de imágenes.

GKE no usa el sistema de archivos de transmisión de imágenes

Si el registro de eventos de GKE no muestra los eventos de transmisión de imágenes, el sistema de archivos remoto no respalda la imagen. Si GKE extrajo antes la imagen en el nodo, este es el comportamiento esperado, ya que GKE usa la caché local de la imagen para las extracciones posteriores en lugar de usar la transmisión de imágenes. Para verificar esto, busca Container image IMAGE_NAME already present on machine en el campo Message del evento Pulled del pod.

Si no ves el evento de transmisión de imágenes durante la primera extracción de imagen en el nodo, asegúrate de cumplir con los requisitos para la transmisión de imágenes. Si cumples con los requisitos, puedes diagnosticar el problema si revisas los registros del servicio de transmisión de imágenes (llamado gcfsd):

  1. Ve a la página del Explorador de registros en la consola de Google Cloud :

    Ir al Explorador de registros

  2. En el campo Consulta, ingresa la siguiente consulta:

    logName="projects/PROJECT_ID/logs/gcfsd"
resource.labels.cluster_name="CLUSTER_NAME"

    Reemplaza lo siguiente:

    • PROJECT_ID: el nombre del proyecto.
    • CLUSTER_NAME: Es el nombre del clúster.

  3. Haga clic en Ejecutar consulta.

También puedes verificar los registros gcfsd con el explorador de registros:

  1. Ve al Explorador de registros en la consola de Google Cloud :

    Ir al Explorador de registros

  2. En el campo Consulta, ingresa la siguiente consulta:

    logName="projects/PROJECT_ID/logs/gcfsd"

    Reemplaza PROJECT_ID por el ID de tu proyecto Google Cloud .

PermissionDenied

Si los registros gcfsd muestran un mensaje de error similar al siguiente, el nodo no tiene el alcance de API correcto. GKE extrae imágenes de contenedor para cargas de trabajo sin usar la transmisión de imágenes.

level=fatal msg="Failed to create a Container File System client: rpc error:
code = PermissionDenied desc = failed to probe endpoint: rpc error: code = PermissionDenied
desc = Request had insufficient authentication scopes."

Para solucionar este problema, otorga el permiso correcto al nodo a fin de permitirle que use la transmisión de imágenes. Agrega el permiso devstorage.read_only al clúster o grupo de nodos, de manera similar al siguiente comando:

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --image-type="COS_CONTAINERD" \
    --enable-image-streaming \
    --scopes="https://www.googleapis.com/auth/devstorage.read_only"

FailedPrecondition

Si observas un mensaje de error con code = FailedPrecondition, la imagen no se importó al sistema de archivos remoto de transmisión de imágenes.

Es posible que notes este error si intentaste usar la transmisión de imágenes con un grupo de nodos existente. Si un nodo del grupo de nodos ya tiene la imagen de contenedor en el disco, GKE usa la imagen local en lugar de usar la transmisión de imágenes para obtener la imagen.

Para solucionar este problema, prueba lo siguiente:

  • Espera unos minutos y, luego, intenta implementar tu carga de trabajo de nuevo.
  • Agrega nodos o un grupo de nodos nuevos y programa la carga de trabajo en esos nodos.

InvalidArgument

Si observas un mensaje de error con code=InvalidArgument, la imagen de contenedor que usa tu carga de trabajo no es apta para la transmisión de imágenes. Asegúrate de que la imagen cumpla con los requisitos. Si tu imagen no está en Artifact Registry, intenta migrar a Artifact Registry.

backend.FileContent failed

El siguiente error puede aparecer cuando se leen archivos de contenedor con la transmisión de imágenes habilitada:

level=error msg="backend.FileContent failed" error="rpc error: code = ResourceExhausted desc = Quota exceeded for quota metric 'Content requests per project per region' and limit 'Content requests per project per region per minute per region' of service 'containerfilesystem.googleapis.com' for consumer 'project_number:PROJECT_NUMBER'." layer_id="sha256:1234567890" module=gcfs_backend offset=0 path=etc/passwd size=4096

Este error indica que el proyecto superó la cuota necesaria para leer archivos del servicio de sistema de archivos del contenedor remoto. Para resolver este problema, solicita un ajuste de cuota para aumentar los siguientes valores de cuota:

  • Solicitudes de contenido por proyecto por región por minuto por región
  • Solicitudes de contenido por proyecto por región

GKE descarga la imagen sin transmitir los datos.

Las imágenes de contenedor que usan claves de encriptación administradas por el cliente (CMEK) solo son aptas para la transmisión de imágenes en la versión 1.25.3-gke.1000 o posterior de GKE. Las imágenes de contenedor con capas duplicadas no son aptas para la transmisión de imágenes. Consulta las Limitaciones para obtener más información.

Comprueba si hay capas vacías o duplicadas

Para verificar la imagen del contenedor en busca de capas vacías o duplicadas, ejecuta el siguiente comando:

docker inspect IMAGE_NAME

Reemplaza IMAGE_NAME por el nombre de la imagen de contenedor.

En el resultado del comando, inspecciona las entradas bajo "Layers".

Si una de las entradas coincide con exactitud con el siguiente resultado "sha256", la imagen de contenedor tiene una capa vacía y no es apta para la transmisión de imágenes.

"Layers": [
  ...
  "sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4",
  ...
]

Si hay entradas duplicadas, como en el siguiente ejemplo, la imagen de contenedor tiene capas duplicadas y no es apta para la transmisión de imágenes.

"Layers": [
  "sha256:28699c71935fe3ffa56533db44ad93e5a30322639f7be70d5d614e06a1ae6d9b",
  ...
  "sha256:28699c71935fe3ffa56533db44ad93e5a30322639f7be70d5d614e06a1ae6d9b",
  ...
]

El comando mv y las llamadas al sistema renameat2 fallan en los archivos symlink

Para los nodos de GKE que ejecutan la versión 1.25 y otras posteriores, cuando la transmisión de imágenes está habilitada, el comando mv y la llamada al sistema renameat2 pueden fallar en archivos symlink de imágenes de contenedor con el mensaje de error “No existe el dispositivo o la dirección”. El problema se debe a una regresión en kernels de Linux recientes.

Estas llamadas al sistema no son comunes, por lo que la mayoría de las imágenes no se ven afectadas por este problema. Por lo general, el problema ocurre en las etapas de inicialización del contenedor, cuando una aplicación se prepara para ejecutarse y moverse por los archivos. No es posible probar la imagen de forma local, por lo que GKE recomienda usar la transmisión de imágenes en entornos de prueba para encontrar el problema antes de usar la imagen en producción.

La corrección está disponible en las siguientes versiones de parche de GKE:

  • 1.25: 1.25.14-gke.1351000 y versiones posteriores
  • 1.26: 1.26.9-gke.1345000 y versiones posteriores
  • 1.27: 1.27.6-gke.100 y versiones posteriores
  • 1.28: 1.28.1-gke.1157000 y versiones posteriores

De forma alternativa, para mitigar este problema en las cargas de trabajo afectadas, puedes intentar reemplazar el código que conduce a la llamada al sistema renameat2. Si no puedes modificar el código, debes inhabilitar la transmisión de imágenes en el grupo de nodos para mitigar el problema.

¿Qué sigue?