Es posible que parte de la información de esta página (o toda) no se aplique a Cloud de Confiance de S3NS. Consulta Diferencias con Google Cloud para obtener más información.

Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Automatiza el ajuste del rendimiento con los perfiles de Cloud Storage FUSE

Autopilot estándar

En este documento, se describe cómo puedes ajustar automáticamente el rendimiento del controlador de CSI de Cloud Storage FUSE y acelerar el acceso a los datos de tus cargas de trabajo de IA/ML con los perfiles de Cloud Storage FUSE en Google Kubernetes Engine (GKE).

Los perfiles de Cloud Storage FUSE automatizan el proceso crítico de ajuste del rendimiento. En lugar de ajustar la configuración de forma manual, puedes aplicar perfiles predefinidos que configuren el controlador CSI por ti. En el caso de tus aplicaciones de IA/AA, usar estos perfiles puede generar tiempos de entrenamiento e inferencia más rápidos con una sobrecarga operativa reducida.

Este documento está dirigido a desarrolladores de aplicaciones y a ingenieros de aprendizaje automático (AA) que deseen mejorar el rendimiento de sus aplicaciones sin tener experiencia en el ajuste del almacenamiento. Para obtener más información sobre los roles comunes, consulta Roles y tareas comunes del usuario de GKE.

Antes de leer este documento, asegúrate de conocer los conceptos básicos de Cloud Storage, Kubernetes y el controlador CSI de Cloud Storage FUSE. Además, revisa los requisitos para usar el controlador CSI de Cloud Storage FUSE.

Beneficios de usar perfiles de Cloud Storage FUSE

Para automatizar el ajuste del rendimiento de las cargas de trabajo de IA/AA, los perfiles de Cloud Storage FUSE usan configuraciones predefinidas de Cloud Storage FUSE y aplican parámetros de configuración adicionales específicos de GKE. Estos parámetros de configuración se basan en las prácticas recomendadas para ajustar el rendimiento de Cloud Storage FUSE. El uso de perfiles predefinidos ofrece los siguientes beneficios:

Ajuste de rendimiento simplificado: Usa perfiles predefinidos de Cloud Storage FUSE para aplicar las configuraciones optimizadas para cargas de trabajo comunes de IA/AA, como el entrenamiento, la entrega y la creación de puntos de control.
Optimización dinámica y con reconocimiento de recursos: El uso de los perfiles de Cloud Storage FUSE permite que el controlador de CSI ajuste automáticamente los tamaños de la caché y seleccione el medio de caché óptimo, como la RAM o el SSD local, según las características del bucket o del subdirectorio, como el tamaño, el recuento de objetos y el tipo de ubicación, los límites de los sidecars y los recursos disponibles de tu nodo.
Rendimiento de lectura acelerado: Cuando usas el perfil gcsfusecsi-serving, GKE habilita automáticamente Rapid Cache para mejorar el rendimiento de lectura de tus cargas de trabajo de procesamiento.
Estadísticas de optimización del rendimiento: Obtienes estadísticas sobre las decisiones de optimización automatizada a través de registros estructurados que detallan los indicadores de entrada de tu entorno y las configuraciones resultantes que aplica el controlador. Para obtener más información, consulta Cómo ver estadísticas de recomendaciones.

A medida que evolucionan las prácticas recomendadas de Cloud Storage FUSE, los perfiles se actualizan con el tiempo a través de las nuevas versiones de GKE.

Limitaciones

No puedes usar perfiles de Cloud Storage FUSE con los volúmenes efímeros del CSI de Cloud Storage FUSE.
Los perfiles no admiten el activación dinámica, en la que especificas un guion bajo (_) para activar todos los buckets a los que puede acceder la ServiceAccount de Kubernetes.
No se admite la anulación de la imagen del archivo adicional con una imagen privada personalizada del archivo adicional. Para obtener más información, consulta Configura una imagen privada para el contenedor secundario.

Requisitos

Tu clúster de GKE debe ejecutar la versión 1.35.1-gke.1616000 o una posterior.
Tu clúster debe tener habilitado el controlador de CSI de Cloud Storage FUSE. Si vas a crear un clúster nuevo o habilitar el controlador en uno existente, consulta los siguientes pasos del documento para configurar el controlador CSI de Cloud Storage FUSE para GKE:

Costos

Además de los costos estándar de GKE y Cloud Storage asociados con el controlador CSI de Cloud Storage FUSE, el uso de perfiles de Cloud Storage FUSE genera los siguientes costos.

Costos de análisis de buckets

Los perfiles de Cloud Storage FUSE realizan un análisis en segundo plano de tu bucket o subdirectorio. De forma predeterminada, este análisis se realiza cada siete días. El análisis de buckets genera cargos por operaciones de clase A de Cloud Storage por la enumeración de objetos.

Costos de Rapid Cache

El perfil gcsfusecsi-serving habilita automáticamente Rapid Cache, que se factura según los precios de Cloud Storage Rapid Cache. Para evitar cargos por instancias de caché cuando ya no se necesiten, consulta Controles de costos.

Antes de comenzar

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

Habilita la API de Cloud Storage y la API de Google Kubernetes Engine.

Habilita las APIs

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 indican en este documento.
Nota: Para las instalaciones de gcloud CLI existentes, asegúrate de configurar la propiedad compute/region. Si usas principalmente clústeres zonales, configura compute/zone en su lugar. Cuando configuras una ubicación predeterminada, puedes evitar errores en gcloud CLI como el siguiente: One of [--zone, --region] must be supplied: Please specify location. Es posible que debas especificar la ubicación en ciertos comandos si la ubicación de tu clúster difiere de la predeterminada que estableciste.

Elige una Cloud de Confiance by S3NS región adecuada para tus necesidades. Si bien recomendamos que crees tu clúster de GKE y tu bucket de Cloud Storage en la misma región para optimizar el rendimiento y el costo, es obligatorio que lo hagas cuando uses el perfil gcsfusecsi-serving o planees habilitar Rapid Cache.
Asegúrate de tener un bucket de Cloud Storage existente que contenga el conjunto de datos, el modelo o los puntos de control para tu carga de trabajo de IA/ML. Si necesitas crear un bucket, consulta Crea un bucket.

Selecciona un perfil de rendimiento

Elige un perfil que se adapte mejor a tu carga de trabajo. Cada perfil corresponde a un StorageClass preinstalado en tu clúster. Para obtener definiciones detalladas de los perfiles de Cloud Storage FUSE, consulta la referencia de configuración de StorageClass correspondiente.

Perfil	Nombre de StorageClass	Optimizado para	Características clave
Capacitación	`gcsfusecsi-training`	Lecturas de alta capacidad de procesamiento	Optimiza la latencia de datos para las GPUs y las TPUs durante el entrenamiento en conjuntos de datos grandes.
Creación de puntos de control	`gcsfusecsi-checkpointing`	Escrituras de alta capacidad de procesamiento	Minimiza el tiempo necesario para guardar puntos de control grandes, lo que reduce las pausas del entrenamiento.
Entrega	`gcsfusecsi-serving`	Acceso a los datos y almacenamiento en caché	Habilita Rapid Cache de forma predeterminada para acelerar las operaciones de lectura.

Para verificar las StorageClasses instaladas en tu clúster, ejecuta el siguiente comando:

kubectl get sc -l gke-gcsfuse/profile=true

Configura los permisos de IAM

Otorga permisos al agente de servicio de GKE para analizar tu bucket de Cloud Storage y administrar Rapid Cache.

Reemplaza los siguientes marcadores de posición cuando ejecutes los comandos de esta sección:

GCS_PROJECT: Es el ID del proyecto que contiene tu bucket de Cloud Storage.
PROJECT_NUMBER: Es el número del proyecto de tu clúster de GKE.
BUCKET_NAME: Es el nombre de tu bucket de Cloud Storage.

Elige una de las siguientes opciones que coincida con tu perfil y tus necesidades de uso.

Opción A: Rol personalizado (recomendado)

Esta opción es obligatoria para el perfil de Publicación o si se usa Rapid Cache. Si usas el perfil de Publicación o planeas habilitar manualmente la caché rápida para otros perfiles, debes otorgar permisos para administrar esa caché.

Crea un rol personalizado de IAM que permita analizar objetos y crear cachés de Rapid Cache:

gcloud iam roles create gke.gcsfuse.profileUser \
  --project=GCS_PROJECT \
  --title="GKE GCSFuse Profile User" \
  --description="Allows scanning Cloud Storage buckets for objects, retrieving bucket metadata, and creating caches." \
  --permissions="storage.objects.list,storage.buckets.get,storage.anywhereCaches.create,storage.anywhereCaches.get,storage.anywhereCaches.list,storage.anywhereCaches.update"

Vincula el rol personalizado al agente de servicio de GKE para tu bucket específico:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
  --project=GCS_PROJECT \
  --member="serviceAccount:service-PROJECT_NUMBER@container-engine-robot.s3ns-system.iam.gserviceaccount.com" \
  --role="projects/GCS_PROJECT/roles/gke.gcsfuse.profileUser"

Opción B: Rol estándar para los perfiles de entrenamiento y supervisión de puntos de control

Si solo usas los perfiles de entrenamiento o de puntos de control, y no planeas usar Rapid Cache, ejecuta el siguiente comando:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --project=GCS_PROJECT \
    --member="serviceAccount:service-PROJECT_NUMBER@container-engine-robot.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/storage.legacyBucketReader"

Implementa una carga de trabajo con un perfil de Cloud Storage FUSE

Sigue estos pasos para implementar una carga de trabajo con un perfil de Cloud Storage FUSE.

Crea un manifiesto de PersistentVolume (PV) que haga referencia a una de las StorageClasses del perfil de Cloud Storage FUSE:
```
apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: STORAGECLASS_NAME
  mountOptions:
    - only-dir=BUCKET_DIR_PATH # Optional
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME
```
Reemplaza lo siguiente:
- STORAGECLASS_NAME: Es el nombre de la StorageClass del perfil que deseas usar. El valor debe ser gcsfusecsi-training, gcsfusecsi-checkpointing o gcsfusecsi-serving.
- BUCKET_DIR_PATH: (opcional) Es la ruta de acceso dentro de tu bucket de Cloud Storage si deseas activar un directorio específico. Si se especifica, GKE analiza esta ruta de acceso para la optimización. Si se omite, GKE analiza todo el bucket.
- BUCKET_NAME: Es el nombre del bucket de Cloud Storage que especificaste cuando configuraste el acceso a los buckets de Cloud Storage.

Crea un PersistentVolumeClaim (PVC) que solicite la misma StorageClass que tu PV:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
  namespace: NAMESPACE
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  volumeName: my-pv
  storageClassName: STORAGECLASS_NAME

Reemplaza lo siguiente:

NAMESPACE: Es el espacio de nombres en el que deseas implementar tu Pod.
STORAGECLASS_NAME: Es el nombre de StorageClass que aparece en tu PV.

Consume el PVC en tu Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
  namespace: NAMESPACE
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
      annotations:
        gke-gcsfuse/volumes: "true"
    spec:
      serviceAccountName: KSA_NAME
      containers:
      - name: my-container
        image: busybox
        volumeMounts:
        - name: my-gcs-volume
          mountPath: "/data"
      volumes:
      - name: my-gcs-volume
        persistentVolumeClaim:
          claimName: my-pvc

Reemplaza lo siguiente:

NAMESPACE: Es el espacio de nombres en el que deseas implementar tu Pod.
KSA_NAME: Es el nombre de la cuenta de servicio de Kubernetes que creaste cuando configuraste el acceso a los buckets de Cloud Storage.

Una vez que se implementa, el controlador de CSI calcula automáticamente los tamaños óptimos de la caché y las opciones de montaje según los recursos de tu nodo, como las GPUs o las TPUs, la memoria, el SSD local, el tamaño del bucket o del subdirectorio, y los límites de recursos del sidecar.

Verifica la optimización automatizada

Los procesos en segundo plano de GKE analizan automáticamente tu bucket y sincronizan Rapid Cache (si se usa).

Verifica el estado del análisis del bucket y de la caché

Después de crear el PV, sigue estos pasos para verificar el estado del análisis del bucket y de la caché. No es necesario que esperes a que se implemente el Pod.

Verifica el estado de la PV:
```
kubectl describe pv my-pv
```

En el resultado, verifica que aparezca el evento ScanOperationSucceeded. El resultado es similar al siguiente:

Normal  ScanOperationSucceeded  gke-gcsfuse-scanner  Bucket scan completed successfully for bucket "my-bucket", directory "my-dir": "526893" objects, "57690897566" bytes

Si usas el perfil gcsfusecsi-serving, verifica que el evento AnywhereCacheSyncSucceeded aparezca después de que la capa de almacenamiento en caché esté lista. El resultado es similar a lo siguiente:
```
Normal  AnywhereCacheSyncSucceeded  gke-gcsfuse-scanner  Anywhere Cache sync succeeded for PV "my-pv": us-central1-c:running
```
Nota: La creación de Rapid Cache puede tardar varios minutos o varias horas. Tus cargas de trabajo no se bloquean durante este tiempo y pueden leer datos directamente del bucket hasta que la caché esté operativa. Para obtener más información, consulta Crea una caché.

Verifica que las anotaciones de PV se actualicen con el resultado del análisis:

gke-gcsfuse/bucket-scan-status: completed
gke-gcsfuse/bucket-scan-num-objects: 526893
gke-gcsfuse/bucket-scan-total-size-bytes: 57690897566
gke-gcsfuse/bucket-scan-location-type: multi-region
gke-gcsfuse/bucket-scan-hns-enabled: true
gke-gcsfuse/bucket-scan-last-updated-time: 2025-12-10T22:48:38Z

El estado del Pod

Después de implementar el Pod, ejecuta el siguiente comando:

kubectl get pods -n NAMESPACE

Reemplaza NAMESPACE por el espacio de nombres en el que implementaste tus Pods.

Tus Pods ahora deberían tener el estado RUNNING, con las prácticas recomendadas de rendimiento aplicadas automáticamente. Si tus Pods muestran el estado SchedulingGated, significa que GKE aún está analizando tu bucket o subdirectorio. Los Pods permanecen en este estado hasta que el controlador de CSI completa el análisis y actualiza el PV.

Para comprender las decisiones de ajuste específicas que registra el conductor después de que se inicia el Pod, consulta Cómo ver estadísticas de recomendaciones.

Si encuentras algún error, consulta la sección Solución de problemas.

Referencia de configuración de StorageClass

En esta sección, se proporcionan los manifiestos de StorageClass para los perfiles de Cloud Storage FUSE preinstalados y una referencia detallada para las opciones de activación y los parámetros que usan los perfiles. Estas configuraciones permiten que el controlador gcsfuse.csi.storage.gke.io automatice el ajuste del rendimiento y la administración de recursos para tus cargas de trabajo de IA/AA.

Capacitación

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-training
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-training
parameters:
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

Creación de puntos de control

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-checkpointing
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-checkpointing
  - read_ahead_kb=1024
parameters:
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

Entrega

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-serving
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-serving
  - read_ahead_kb=131072
  - file-cache:max-size-mb:0
  - read:enable-buffered-read:true
  - read:global-max-blocks:80
parameters:
  anywhereCacheZones: "*"
  anywhereCacheAdmissionPolicy: "admit-on-first-miss"
  anywhereCacheTTL: "1h"
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

Los perfiles usan las siguientes opciones de montaje y parámetros para el controlador gcsfuse.csi.storage.gke.io:

mountOptions:
- profile: Aplica un conjunto predefinido de optimizaciones de Cloud Storage FUSE diseñadas para cargas de trabajo de IA/AA. Los valores válidos para los perfiles preinstalados son aiml-training, aiml-checkpointing y aiml-serving.
- read_ahead_kb: Especifica el tamaño del búfer de lectura anticipada en kilobytes (KB). Esta opción permite que Cloud Storage FUSE obtenga datos por adelantado de Cloud Storage, lo que podría mejorar el rendimiento de lectura para los patrones de acceso secuencial.
- file-cache:max-size-mb: Para el perfil de Serving, especifica el tamaño máximo en mebibytes (MiB) para la caché de archivos. En las cargas de trabajo de entrega, en las que los modelos suelen cargarse en la memoria de la GPU o TPU solo una vez, este parámetro se establece en 0 para inhabilitar la caché de archivos local de Cloud Storage FUSE, lo que ayuda a evitar E/S de disco redundantes y ahorra almacenamiento local.
- read:enable-buffered-read: Para el perfil de Serving, habilita Cloud Storage FUSE para administrar sus propios búferes internos, lo que ayuda a reducir la cantidad de llamadas al sistema pequeñas y costosas entre la aplicación y el kernel.
- read:global-max-blocks: Para el perfil de entrega, limita la cantidad total de bloques de memoria simultáneos que se usan para las lecturas almacenadas en búfer. Esta opción ayuda a evitar que el proceso de FUSE consuma toda la RAM disponible cuando se atienden varias solicitudes.
parameters:
- skipCSIBucketAccessCheck: Cuando se establece en "true", hace que el controlador de CSI omita la verificación inicial de acceso al bucket. Este parámetro ayuda a reducir las llamadas al Servicio de tokens de seguridad para evitar posibles problemas de cuota.
- gcsfuseMetadataPrefetchOnMount: Cuando se configura como "true", dirige al controlador de CSI para que inicie la prefetching de los metadatos del objeto de Cloud Storage en la caché local tan pronto como se active el volumen. Este parámetro puede acelerar el primer acceso a los archivos.
- fuseFileCacheMediumPriority: Define el orden de prioridad para los medios de almacenamiento que usa la caché de archivos de Cloud Storage FUSE. Permite especificar diferentes preferencias para los nodos con GPU, TPU o nodos de uso general. Las opciones de medios incluyen ram y lssd (SSD local, si está disponible y habilitada).
- fuseMemoryAllocatableFactor: Especifica en formato de cadena una fracción que limita la memoria máxima que pueden consumir las cachés de Cloud Storage FUSE, en relación con la memoria total asignable del nodo y el límite de memoria del sidecar.
- fuseEphemeralStorageAllocatableFactor: Limita el uso de la caché de Cloud Storage FUSE del almacenamiento efímero en el nodo (como SSD local para el almacenamiento en caché de archivos), en relación con el almacenamiento efímero asignable del nodo o el almacenamiento efímero del sidecar limitado para el almacenamiento en caché.
- bucketScanResyncPeriod: Establece el intervalo de tiempo en el que se vuelve a analizar la PV para detectar los cambios realizados en el bucket de Cloud Storage.
- bucketScanTimeout: Es la duración máxima permitida para una sola operación de análisis de bucket. Si el análisis supera este tiempo, es posible que se usen resultados parciales.
- anywhereCacheZones: Especifica una lista separada por comas de las zonas admitidas en las que se crean las cachés de Rapid Cache, por ejemplo, "us-central1-a,us-central1-b". Para usar todas las zonas disponibles para el clúster, usa "*" como valor. Si estableces este parámetro en "none" o no lo especificas, se inhabilita Rapid Cache.
- anywhereCacheTTL: Es el tiempo de actividad (TTL) de los datos almacenados en la caché de Rapid Cache, medido desde el último acceso. Si cambias este valor, las instancias existentes de Rapid Cache se actualizarán con el nuevo TTL.
- anywhereCacheAdmissionPolicy: Determina cuándo se admiten datos en la caché de Rapid Cache después de una lectura fallida (cuando no se encuentran los datos solicitados en la caché). Las opciones incluyen "admit-on-first-miss", que admite datos en el primer error de lectura, o "admit-on-second-miss", que admite datos solo en un segundo error de lectura para el mismo objeto. Si cambias este valor, las instancias existentes de Rapid Cache se actualizarán con la nueva política.

Opcional: Ajusta la configuración del perfil

Puedes personalizar parámetros de configuración específicos en un perfil y, al mismo tiempo, aprovechar su configuración base. Usa las siguientes opciones para ajustar un perfil sin crear una nueva StorageClass.

Cómo anular los parámetros y las opciones de activación

Para modificar comportamientos específicos, agrega opciones de activación al campo spec.mountOptions o parámetros de CSI al campo spec.csi.volumeAttributes en tu PV. GKE aplica tu configuración manual sobre los valores predeterminados del perfil.

En el siguiente ejemplo, se muestra cómo anular la opción de activación read_ahead_kb y cómo inhabilitar el parámetro gcsfuseMetadataPrefetchOnMount en el perfil de Serving.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv-override
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: gcsfusecsi-serving
  mountOptions:
  - read_ahead_kb=2048 # Overrides the profile's default.
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: my-gcs-bucket
    volumeAttributes:
      gcsfuseMetadataPrefetchOnMount: "false" # Overrides the profile's default.

Los siguientes son algunos de los casos de uso comunes:

Para habilitar Rapid Cache en un perfil de entrenamiento, agrega el parámetro anywhereCacheZones directamente a tu especificación de PV.
Ajustar comportamientos específicos de Cloud Storage FUSE, como aumentar el tamaño de read_ahead_kb, para satisfacer los requisitos únicos de una carga de trabajo en particular

Cuando configures manualmente los tamaños de la caché, ten en cuenta lo siguiente:

Si especificas un tamaño de caché manual, se anulará el ajuste de tamaño dinámico automático solo para ese componente específico. El ajuste de tamaño dinámico continúa para todos los demás componentes de la mejor manera posible dentro del presupuesto de recursos restante.
Establecer una opción de metadata-cache o file-cache, como metadata-cache:stat-cache-max-size-mb, no inhabilita el cálculo automático para otros tipos de caché.
Si especificas file-cache:max-size-mb de forma manual, también debes configurar un volumen de caché de lectura personalizado. Esto ayuda a garantizar que se defina explícitamente un medio de almacenamiento con capacidad suficiente para el tamaño de caché personalizado.

Cómo omitir el análisis del bucket con anotaciones

Puedes omitir el proceso de análisis automático de bucket proporcionando tus propias métricas de recuento y tamaño de objetos a través de anotaciones. El controlador CSI usa estos valores para calcular las configuraciones de rendimiento óptimas sin analizar el bucket.

En el siguiente ejemplo, se muestra cómo agregar la anotación gke-gcsfuse/bucket-scan-status: "override" a tu PV, junto con las anotaciones de métricas específicas.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv-override
  annotations:
    gke-gcsfuse/bucket-scan-status: "override"
    gke-gcsfuse/bucket-scan-num-objects: 19238
    gke-gcsfuse/bucket-scan-total-size-bytes: 94837465
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: STORAGECLASS_NAME
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME

Los siguientes son algunos de los casos de uso comunes:

Si ya conoces el tamaño y el recuento de objetos de tu bucket, especialmente para las cargas de trabajo de inferencia en las que los datos rara vez cambian, puedes omitir el tiempo de análisis durante el inicio.
Si la API de Cloud Storage no está disponible temporalmente, estas anotaciones pueden ayudarte a mantener el rendimiento mientras se reparan los servicios subyacentes.

Soluciona problemas

Usa la siguiente información para supervisar el estado de los perfiles de Cloud Storage FUSE y resolver los problemas comunes que se producen durante el análisis de bucket y la sincronización de la caché.

Parámetro de configuración no válido (`InvalidArgument`)

No se pudieron iniciar las tareas de optimización en segundo plano porque uno o más parámetros proporcionados en tu manifiesto no eran válidos.

Síntoma

La PV muestra un evento ScanOperationStartError o AnywhereCacheSyncError con un mensaje que contiene rpc error: code = InvalidArgument. Estos son algunos ejemplos:

Bucket scan timeout configuration error: rpc error: code = InvalidArgument desc = invalid duration format for "INVALID_DURATION".
Anywhere Cache sync failed for PV "PV_NAME": rpc error: code = InvalidArgument desc = failed to get anywhere cache "CACHE_NAME" ... invalid anywhere cache "CACHE_NAME" provided.

Causa

Uno o más parámetros del campo spec.csi.volumeAttributes de tu PV tienen un formato incorrecto o contienen valores que el sistema no puede analizar.

Solución

Corrige los valores de parámetros no válidos en el manifiesto de PV y vuelve a implementar el PV. Asegúrate de que todos los valores de duración (como bucketScanTimeout) usen el formato correcto (por ejemplo, 2m o 10m) y de que todos los parámetros de configuración específicos del perfil coincidan con los valores admitidos válidos.

Se denegó el permiso cuando se analizó el bucket de Cloud Storage

GKE no puede acceder al bucket de Cloud Storage especificado para realizar el análisis de rendimiento requerido.

Síntoma

La PV muestra un evento ScanOperationStartError con un mensaje Error 403: Forbidden que indica que el llamador no tiene acceso a storage.buckets.get.

Causa

Al agente de servicio de GKE le faltan los permisos de IAM necesarios o el nombre del bucket es incorrecto.

Solución

Verifica que el nombre del bucket en el campo volumeHandle de tu PV sea correcto y que el bucket exista.
Asegúrate de que los permisos del agente de servicio de GKE se otorguen a la identidad service-PROJECT_NUMBER@container-engine-robot.s3ns-system.iam.gserviceaccount.com para el bucket específico. Para obtener más información, consulta Configura permisos de IAM.

La ubicación de Rapid Cache no coincide

No se pudo crear la caché de Rapid Cache porque la zona solicitada no es compatible con la ubicación del bucket.

Síntoma

La PV muestra un evento AnywhereCacheSyncWarning con el mensaje: Invalid zone. Rapid Cache isn't available in the requested zone.

Causa

Los cachés de Rapid Cache se deben crear en zonas que se encuentren dentro de la ubicación regional del bucket. Este error suele ocurrir cuando tu clúster de GKE y tu bucket de Cloud Storage están en regiones diferentes.

Solución

Mueve tu bucket de Cloud Storage a una región que coincida con la ubicación de tu clúster de GKE y vuelve a implementar el PV.

Se agotó el tiempo de espera del análisis del bucket

El análisis del bucket de Cloud Storage tardó más que el tiempo de espera configurado, lo que generó resultados de optimización parciales.

Síntoma

La PV muestra un evento ScanOperationTimedOut. La PV se anota con resultados parciales para el recuento de objetos y el tamaño total.

Causa

El bucket contiene una cantidad excepcionalmente grande de objetos (por lo general, varios millones) que no se pueden enumerar por completo dentro del tiempo de espera predeterminado de dos minutos.

Solución

Establece un valor más grande para el campo bucketScanTimeout en la sección spec.csi.volumeAttributes de tu PV, por ejemplo, 10m.
Si el tamaño del bucket es estático, omite el análisis proporcionando manualmente el recuento y el tamaño de los objetos.

La caché de metadatos está limitada por el presupuesto de memoria

El controlador limitó el tamaño de la caché de metadatos para que se ajuste a los recursos disponibles del nodo, lo que podría reducir el rendimiento.

Síntoma

Los registros contienen un mensaje que indica que el tamaño de la caché de estadísticas de metadatos requerida se limitó al presupuesto de memoria disponible de Cloud Storage FUSE.

Causa

La caché de metadatos para la cantidad de objetos en tu bucket supera la memoria asignada al archivo adicional de Cloud Storage FUSE o la memoria disponible del nodo.

Solución

Usa la opción de montaje only-dir para limitar el volumen a un subdirectorio más pequeño con menos objetos.
Aumenta el límite de memoria del contenedor secundario de Cloud Storage FUSE.
- Si los límites de sidecar ya son suficientes, usa un tipo de nodo con más memoria asignable.

Se inhabilitó la caché de archivos debido a límites de recursos

GKE inhabilitó la caché de archivos local porque no pudo encontrar un medio de almacenamiento adecuado con suficiente espacio.

Síntoma

En los registros, se muestra la advertencia No suitable file cache medium found or requirement exceeded limits for all options.

Causa

El tamaño de la caché de archivos calculado supera la RAM disponible del nodo y el almacenamiento disponible de la SSD local.

Solución

Usa la opción de montaje only-dir para limitar el volumen a un subdirectorio más pequeño con menos objetos.
Aumenta los límites de recursos del sidecar de Cloud Storage FUSE.
Usa un tipo de nodo con más memoria o habilita SSD locales en tu grupo de nodos.

Supervisa el estado con eventos de PersistentVolume

GKE registra los eventos y errores de configuración clave en el PV. Para verificar estos eventos, ejecuta el siguiente comando:

kubectl describe pv PV_NAME

Después de que el análisis del bucket se complete correctamente, verás un evento ScanOperationSucceeded. Si usas el perfil gcsfusecsi-serving, verás un evento AnywhereCacheSyncSucceeded después de que la capa de almacenamiento en caché esté operativa.

Supervisa el estado con los registros del controlador CSI

El controlador de CSI de Cloud Storage FUSE registra decisiones de configuración detalladas y estadísticas de rendimiento. Para ver estos registros en Cloud Logging, usa la siguiente consulta:

resource.type="k8s_container"
resource.labels.pod_name=~"gcsfusecsi-node-.*"

Consulta las estadísticas de las recomendaciones

Para comprender los indicadores de entrada específicos y las decisiones que toma la lógica de ajuste automático, busca la cadena GCSFuseCSIRecommendation en los registros del controlador de CSI. La carga útil JSON resultante proporciona métricas detalladas, incluidas las siguientes:

inputSignals: Es el recuento de objetos del bucket, el tamaño total de los datos y los recursos de nodos disponibles (RAM y almacenamiento efímero).
decision: Los tamaños de caché finales calculados y el medio de almacenamiento seleccionado (ram o lssd).

{
  "insertId": "INSERT_ID",
  "jsonPayload": {
    "decision": {
      "fileCacheBytes": 300000000,
      "fileCacheMedium": "lssd",
      "metadataStatCacheBytes": 4500,
    },
    "target": {
      "nodeName": "NODE_NAME",
      "pvName": "PV_NAME",
      "podName": "POD_NAME"
    },
    "message": "GCSFuseCSIRecommendation: Recommended cache configs for PV PV_NAME and Pod POD_NAME: FileCache: 287MiB (lssd) | MetadataStatCache: 1MiB | Expand for full details",
    "inputSignals": {
      "requiredFileCacheBytes": 300000000,
      "fuseBudgetMemoryBytes": 187904819,
      "sidecarLimitMemoryBytes": 268435456,
      "nodeType": "gpu",
      "bucketTotalObjects": 3,
      "nodeAllocatableMemoryBytes": 191291998208,
      "bucketTotalDataSizeBytes": 300000000,
      "bucketLocationType": "multi-region",
      "bucketHNSEnabled": true,
      "sidecarLimitEphemeralStorageBytes": 0,
      "requiredMetadataStatCacheBytes": 4500,
      "nodeAllocatableEphemeralStorageBytes": 1317908854882,
      "nodeHasEphemeralStorageLSSD": true,
      "fuseBudgetEphemeralStorageBytes": 1120222526649
    }
  },
  ...
}

Realiza una limpieza

Para evitar que se apliquen cargos a tu cuenta de Cloud de Confiance by S3NS por los recursos que creaste en esta guía, sigue estos pasos:

Borra la implementación:
```
kubectl delete deployment my-deployment -n NAMESPACE
```
Reemplaza NAMESPACE por el espacio de nombres de Kubernetes en el que creaste la Deployment.
Borra la PersistentVolumeClaim:
```
kubectl delete pvc my-pvc -n NAMESPACE
```
Reemplaza NAMESPACE por el espacio de nombres de Kubernetes en el que creaste el PVC.
Borra el PersistentVolume:
```
kubectl delete pv my-pv
```
Si usaste el perfil gcsfusecsi-serving o habilitaste manualmente Rapid Cache, sigue las instrucciones para inhabilitar una caché y dejar de generar cargos por las instancias de caché.

¿Qué sigue?

Obtén más información sobre el controlador de CSI de Cloud Storage FUSE.
Obtén más información para optimizar manualmente el controlador de CSI de Cloud Storage FUSE para mejorar el rendimiento.

Automatiza el ajuste del rendimiento con los perfiles de Cloud Storage FUSE

Beneficios de usar perfiles de Cloud Storage FUSE

Limitaciones

Requisitos

Costos

Costos de análisis de buckets

Costos de Rapid Cache

Antes de comenzar

Selecciona un perfil de rendimiento

Configura los permisos de IAM

Opción A: Rol personalizado (recomendado)

Opción B: Rol estándar para los perfiles de entrenamiento y supervisión de puntos de control

Implementa una carga de trabajo con un perfil de Cloud Storage FUSE

Verifica la optimización automatizada

Verifica el estado del análisis del bucket y de la caché

El estado del Pod

Referencia de configuración de StorageClass

Capacitación

Creación de puntos de control

Entrega

Opcional: Ajusta la configuración del perfil

Cómo anular los parámetros y las opciones de activación

Cómo omitir el análisis del bucket con anotaciones

Soluciona problemas

Parámetro de configuración no válido (InvalidArgument)

Se denegó el permiso cuando se analizó el bucket de Cloud Storage

La ubicación de Rapid Cache no coincide

Se agotó el tiempo de espera del análisis del bucket

La caché de metadatos está limitada por el presupuesto de memoria

Se inhabilitó la caché de archivos debido a límites de recursos

Supervisa el estado con eventos de PersistentVolume

Supervisa el estado con los registros del controlador CSI

Consulta las estadísticas de las recomendaciones

Realiza una limpieza

¿Qué sigue?

Parámetro de configuración no válido (`InvalidArgument`)