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 nuevos de Autopilot que ejecutan la versión 1.25.5-gke.1000 y posteriores de GKE usan la transmisión de imágenes de forma automática para extraer imágenes aptas. Las instrucciones de esta página solo 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

  • Los clústeres Autopilot nuevos deben ejecutar la versión 1.25.5-gke.1000 o posterior de GKE para que la transmisión de imágenes se habilite automáticamente. Para obtener instrucciones, consulta Configura la versión y el canal de versiones de un clúster de Autopilot nuevo.

  • Los clústeres nuevos y existentes de GKE Standard deben ejecutar la versión 1.18.6-gke.4801 o una posterior.

  • 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 se deben almacenar en Artifact Registry.

  • Si usas clústeres privados, 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

  • No puedes usar un secreto para extraer imágenes de contenedor en las versiones de GKE anteriores a la 1.23.5-gke.1900.
  • Las imágenes de contenedor que usan el manifiesto de imágenes de V2, versión de esquema 1 no son aptas.
  • Las imágenes de contenedor encriptadas con claves de encriptación administradas por el cliente (CMEK) son aptas para la transmisión de imágenes en la versión 1.25.3-gke.1000 o posteriores de GKE. En versiones anteriores, GKE descarga estas imágenes sin transmitir los datos. Aún puedes usar CMEK para proteger discos persistentes y discos de arranque personalizados conectados en clústeres que usan transmisión de imágenes.
  • Las imágenes de contenedor con capas duplicadas solo son aptas para la transmisión de imágenes en la versión 1.28 de GKE o una posterior. En versiones anteriores, GKE descarga estas imágenes sin transmitir los datos. Revisa la imagen de contenedor en busca de capas vacías o duplicadas.
  • El repositorio de Artifact Registry debe estar en la misma región que tus nodos de GKE o en una multirregión que corresponda a la región en la que se ejecutan los nodos. Por ejemplo:
    • Si tus nodos están en us-east1, la transmisión de imágenes está disponible para los repositorios en la región us-east1 o la multirregión us, ya que GKE y Artifact Registry se ejecutan en ubicaciones de centros de datos en EE.UU.
    • Si tus nodos están en la región northamerica-northeast1, se ejecutan en Canadá. En este caso, la transmisión de imágenes solo está disponible para repositorios en la misma región.
  • 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.
  • 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.
  • Las funciones de archivos de Linux, como CAP_NET_RAW, son compatibles con la transmisión de imágenes en la versión 1.22.6-gke.300 y posteriores de GKE. En versiones anteriores de GKE, estas funciones no están disponibles cuando se transmite el archivo de imagen ni cuando se guarda la imagen en el disco local. A fin de evitar posibles interrupciones, no uses la transmisión de imágenes para contenedores con estas funciones en versiones de GKE anteriores a la 1.22.6-gke.300. Si el contenedor depende de las capacidades de los archivos de Linux, es posible que falle su inicio con errores de permiso denegado cuando se ejecuta con la transmisión de imágenes habilitada.

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.

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 mediante la marca --enable-image-streaming de la CLI de gcloud o con la consola de Google Cloud. De forma predeterminada, los grupos de nodos del clúster heredan la configuración de transmisión de imágenes a nivel de clúster. Puedes cambiar este comportamiento si habilitas o inhabilitas la transmisión de imágenes en los grupos de nodos del clúster.

Todos los clústeres nuevos de Autopilot que ejecutan la versión 1.25.5-gke.1000 de GKE y versiones posteriores 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 clúster de Autopilot nuevo. Las siguientes instrucciones solo se aplican a los clústeres de GKE Standard.

En un clúster nuevo

Puedes habilitar la transmisión de imágenes en clústeres nuevos mediante la CLI de gcloud o la consola de Google Cloud.

gcloud

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

gcloud container clusters create CLUSTER_NAME \
    --zone=COMPUTE_ZONE \
    --image-type="COS_CONTAINERD" \
    --enable-image-streaming

Reemplaza lo siguiente:

  • CLUSTER_NAME: Es el nombre del clúster nuevo.
  • COMPUTE_ZONE: Es la zona de Compute Engine para el clúster nuevo. Para los clústeres regionales, usa la marca --region=COMPUTE_REGION en su lugar. Asegúrate de que la zona o región sea la misma región o que esté dentro de la multirregión del repositorio de Artifact Registry que contiene la imagen.

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 Crear.

  3. En la sección GKE Standard, haz clic en Configurar.

  4. En el panel de navegación, en Clúster, haz clic en Funciones.

  5. En la sección Otro, selecciona la casilla de verificación Habilitar la transmisión de imágenes.

  6. Configura el clúster según sea necesario y, luego, haz clic en Crear.

En un clúster existente

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

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 \
    --enable-image-streaming

Consola

  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 Edita la 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 de clúster.

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 mediante la CLI de gcloud o la consola de Google Cloud.

gcloud

Ejecuta el siguiente comando:

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

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: {}
...

Consola

  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 \
    --zone=COMPUTE_ZONE \
    --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.
  • COMPUTE_ZONE: Es la zona de Compute Engine de tu clúster. Para los clústeres regionales, usa la marca --region=COMPUTE_REGION en su lugar.

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 \
    --enable-image-streaming

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 \

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 \
    --zone=COMPUTE_ZONE \
    --enable-image-streaming \
    --image-type="COS_CONTAINERD"

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

    gcloud container clusters get-credentials CLUSTER_NAME \
    --zone=COMPUTE_ZONE

  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\
    --zone=COMPUTE_ZONE \
    --image-type="COS_CONTAINERD"

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

    gcloud container clusters get-credentials CLUSTER2_NAME \
    --zone=COMPUTE_ZONE

  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.

Limpia

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

gcloud container clusters delete CLUSTER_NAME CLUSTER2_NAME

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, 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 mediante la CLI de gcloud o la consola de Google 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 \
    --no-enable-image-streaming

Consola

  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.

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 \
    --zone=COMPUTE_ZONE \
    --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 \
    --no-enable-image-streaming

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

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

Si el registro de acontecimientos 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 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"
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 del proyecto de 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 \
    --zone=COMPUTE_ZONE \
    --image-type="COS_CONTAINERD" \
    --enable-image-streaming \
    --scope="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, aumenta las siguientes cuotas:

  • 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 solo son aptas para la transmisión de imágenes en la versión 1.28 de GKE o una posterior. 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.