Accede a los buckets de Cloud Storage con el controlador de CSI del FUSE de Cloud Storage

El Sistema de archivos en el espacio del usuario (FUSE) es una interfaz que se usa para exportar un sistema de archivos al kernel de Linux. El FUSE de Cloud Storage te permite activar los buckets de Cloud Storage como un sistema de archivos para que las aplicaciones puedan acceder a los objetos de un depósito con las operaciones comunes de E/S de archivos (por ej., abiertas, de lectura, de escritura) en lugar de usar las APIs específicas de Cloud.

El controlador de CSI del FUSE de Cloud Storage te permite usar la API de Kubernetes para consumir buckets de Cloud Storage preexistentes como volúmenes. Tus aplicaciones pueden subir y descargar objetos mediante la semántica del sistema de archivos del FUSE de Cloud Storage. El controlador de CSI del FUSE de Cloud Storage proporciona una experiencia completamente administrada con la tecnología del controlador CSI del FUSE de Google Cloud Storage de código abierto.

El controlador admite de forma nativa las siguientes formas para que configures los volúmenes respaldados por Cloud Storage:

Puedes usar el controlador CSI de Cloud Storage FUSE con almacenamiento en caché de archivos para mejorar el rendimiento de lectura de las aplicaciones que controlan archivos pequeños de buckets de Cloud Storage. La característica de caché de archivos del FUSE de Cloud Storage es una caché de lectura basada en el cliente que permite que las lecturas de archivos repetidas se entreguen más rápido desde el almacenamiento en caché que elijas. Puedes elegir entre una variedad de opciones de almacenamiento para la caché de lectura, incluidos las SSD locales y el almacenamiento basado en Persistent Disks, según tus necesidades de precio y rendimiento. Debes habilitar la opción habilitar el almacenamiento en caché de archivos con el controlador de CSI de Cloud Storage FUSE. Si deseas obtener más información sobre las prácticas recomendadas para el almacenamiento en caché, consulta Rendimiento y prácticas recomendadas de Cloud Storage FUSE.

Ventajas

  • El controlador de CSI de Cloud Storage FUSE en tu clúster activa la implementación y la administración automáticas del controlador. El controlador funciona en clústeres Standard y de Autopilot.
  • El controlador de CSI de Cloud Storage FUSE no necesita acceso con privilegios que suelen requerir los clientes de FUSE. Esto permite una mejor postura de seguridad.
  • La compatibilidad con los volúmenes efímeros de CSI simplifica la configuración y la administración del volumen, ya que elimina la necesidad de objetos PersistentVolumeClaim y PersistentVolume.
  • El controlador de CSI del FUSE de Cloud Storage admite los modos de acceso ReadWriteMany, ReadOnlyMany y ReadWriteOnce.
  • Puedes usar la federación de identidades para cargas de trabajo para GKE para administrar la autenticación y, a la vez, tener un control detallado sobre cómo los Pods acceden a los objetos de Cloud Storage.
  • Si ejecutas el entrenamiento del AA y entregas cargas de trabajo con frameworks como Ray, PyTorch, Spark y TensorFlow, la portabilidad y simplicidad que proporciona el controlador de CSI del FUSE de Cloud Storage te permiten ejecutar las cargas de trabajo directamente en los clústeres de GKE sin cambios de código adicionales.
  • Puedes leer objetos de Cloud Storage con el almacenamiento en caché de archivos habilitado para aumentar el rendimiento de lectura. Para obtener más información sobre los beneficios del almacenamiento en caché de archivos, consulta la documentación de Cloud Storage FUSE.
  • Puedes consumir volúmenes de Cloud Storage FUSE en contenedores init.

Antes de comenzar

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

  • Habilita la API de Kubernetes Engine de Google.
    • Habilitar la API de Kubernetes Engine de Google
  • 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.
  • Crea buckets de Cloud Storage. Para mejorar el rendimiento, establece el campo Location type en Region y selecciona una región en la que se ejecuta tu clúster de GKE.

Limitaciones

  • El sistema de archivos del FUSE de Cloud Storage tiene diferencias en el rendimiento, disponibilidad, autorización de acceso y semántica en comparación con un sistema de archivos POSIX.
  • El controlador de CSI del FUSE de Cloud Storage no es compatible con GKE Sandbox.
  • El controlador CSI del FUSE de Cloud Storage no admite instantáneas, clonación ni expansiones de volumen.
  • Consulta los problemas conocidos en el proyecto de GitHub del controlador de CSI del FUSE de Cloud Storage.
  • Consulta los problemas abiertos en el proyecto de GitHub del controlador de CSI del FUSE de Cloud Storage. Los problemas se clasificarán y se resolverán en actualizaciones futuras.

Requisitos

Para usar el controlador de CSI del FUSE de Cloud Storage, tus clústeres deben cumplir con los siguientes requisitos:

Habilita el controlador CSI del FUSE de Cloud Storage

Para crear un clúster estándar con el controlador CSI del FUSE de Cloud Storage habilitado, puedes usar la CLI de gcloud:

gcloud container clusters create CLUSTER_NAME \
    --addons GcsFuseCsiDriver \
    --cluster-version=VERSION \
    --location=LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog

Reemplaza los siguientes datos:

  • CLUSTER_NAME: El nombre de tu clúster.
  • VERSION: el número de versión de GKE. Debes seleccionar 1.24 o una versión posterior.
  • LOCATION: la ubicación de Compute Engine para el clúster.
  • PROJECT_ID: Es el ID de tu proyecto.

Para habilitar el controlador en un clúster Estándar existente, usa el comando gcloud container clusters update:

gcloud container clusters update CLUSTER_NAME \
    --update-addons GcsFuseCsiDriver=ENABLED \
    --location=LOCATION

Reemplaza los siguientes datos:

Después de habilitar el controlador CSI de Cloud Storage FUSE, puedes usarlo en volúmenes de Kubernetes si especificas el nombre del controlador y del aprovisionador: gcsfuse.csi.storage.gke.io.

Configura el acceso a los buckets de Cloud Storage a través de la federación de identidades para cargas de trabajo de GKE para GKE

Para que tu clúster de GKE pueda acceder a los buckets de Cloud Storage a través de la federación de identidades para cargas de trabajo para GKE, sigue estos pasos. Consulta Configura las aplicaciones para usar la federación de identidades para cargas de trabajo para GKEpara obtener más información.

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

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

    Reemplaza lo siguiente:

    • CLUSTER_NAME: el nombre del clúster que tiene habilitada la federación de identidades para cargas de trabajo para GKE.
    • LOCATION: la ubicación de Compute Engine para el clúster.

  2. Crea un espacio de nombres para usar en la cuenta de servicio de Kubernetes. También puedes usar el espacio de nombres predeterminado default o cualquier espacio de nombres existente.

    kubectl create namespace NAMESPACE

    Reemplaza lo siguiente:

    • NAMESPACE es el nombre del espacio de nombres de Kubernetes para la ServiceAccount.

  3. Crea una cuenta de servicio de Kubernetes para que tu aplicación use: También puedes usar cualquier ServiceAccount de Kubernetes existente en cualquier espacio de nombres, incluida la ServiceAccount default de Kubernetes.

    kubectl create serviceaccount KSA_NAME \
    --namespace NAMESPACE

    Reemplaza lo siguiente:

    • KSA_NAME: Es el nombre de tu ServiceAccount de Kubernetes nueva.
    • NAMESPACE es el nombre del espacio de nombres de Kubernetes para la ServiceAccount.

  4. Otorga uno de los roles de IAM para Cloud Storage a la ServiceAccount de Kubernetes.

    Puedes otorgar el rol a tu cuenta de servicio de Kubernetes para que solo acceda a un bucket de Cloud Storage específico con el siguiente comando:

    gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member "principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME" \
    --role "ROLE_NAME"

    Reemplaza lo siguiente:

    • BUCKET_NAME: el nombre de tu bucket de Cloud Storage.
    • PROJECT_NUMBER: El número de proyecto numérico del clúster de GKE. Para encontrar el número de tu proyecto, consulta Identifica proyectos.
    • PROJECT_ID: el ID del proyecto de tu clúster de GKE.
    • NAMESPACE es el nombre del espacio de nombres de Kubernetes para la ServiceAccount.
    • KSA_NAME: Es el nombre de tu ServiceAccount de Kubernetes nueva.
    • ROLE_NAME: Es el rol de IAM que se asignará a la ServiceAccount de Kubernetes.
      • Para cargas de trabajo de solo lectura, usa el rol Visualizador de objetos de almacenamiento (roles/storage.objectViewer).
      • Para cargas de trabajo de lectura y escritura, usa el rol de usuario de objetos de almacenamiento (roles/storage.objectUser).

    De manera opcional, puedes otorgar el rol a tu ServiceAccount de Kubernetes para acceder a todos los buckets de Cloud Storage en el proyecto con el siguiente comando:

    gcloud projects add-iam-policy-binding GCS_PROJECT \
    --member "principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME" \
    --role "ROLE_NAME"

    Reemplaza lo siguiente:

    • GCS_PROJECT: Es el ID del proyecto de tus buckets de Cloud Storage.
    • PROJECT_NUMBER: El número de proyecto numérico del clúster de GKE. Para encontrar el número de tu proyecto, consulta Identifica proyectos.
    • PROJECT_ID: el ID del proyecto de tu clúster de GKE.
    • NAMESPACE es el nombre del espacio de nombres de Kubernetes para la ServiceAccount.
    • KSA_NAME: Es el nombre de tu ServiceAccount de Kubernetes nueva.
    • ROLE_NAME: Es el rol de IAM que se asignará a la ServiceAccount de Kubernetes.
      • Para cargas de trabajo de solo lectura, usa el rol Visualizador de objetos de almacenamiento (roles/storage.objectViewer).
      • Para cargas de trabajo de lectura y escritura, usa el rol de usuario de objetos de almacenamiento (roles/storage.objectUser).

Prepárate para activar los buckets de Cloud Storage FUSE

En esta sección, se explica cómo prepararte para activar los buckets de Cloud Storage FUSE en tus clústeres.

Especifica anotaciones de Pod

El controlador CSI depende de las anotaciones de Pod para identificar si tu Pod usa volúmenes respaldados por Cloud Storage. Si el controlador detecta las anotaciones necesarias, inserta un contenedor de sidecar con el nombre de gke-gcsfuse-sidecar en el Pod de carga de trabajo. Las instancias del FUSE de Cloud Storage se ejecutan dentro del contenedor de sidecar y activan los buckets de Cloud Storage para tu carga de trabajo.

Para permitir que el controlador CSI active los buckets de Cloud Storage, asegúrate de especificar la anotación gke-gcsfuse/volumes: "true" en tu especificación de pod, en el campo metadata. Si deseas que otros tipos de cargas de trabajo de Kubernetes consuman los volúmenes respaldados por Cloud Storage (por ejemplo, Job, Deployment o StatefulSet), asegúrate de configurar las anotaciones en el campo spec.template.metadata.annotations.

Configura los recursos para el contenedor de sidecar

De forma predeterminada, el contenedor del sidecar está configurado con las siguientes solicitudes de recursos, sin establecer los límites de recursos:

  • 250 m de CPU
  • 256 MiB de memoria
  • Almacenamiento efímero de 5 GiB

Para reemplazar estos valores, puedes especificar la anotación gke-gcsfuse/[cpu-limit|memory-limit|ephemeral-storage-limit|cpu-request|memory-request|ephemeral-storage-request] de manera opcional, como se muestra en el siguiente ejemplo:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/cpu-limit: "10"
    gke-gcsfuse/memory-limit: 10Gi
    gke-gcsfuse/ephemeral-storage-limit: 1Ti
    gke-gcsfuse/cpu-request: 500m
    gke-gcsfuse/memory-request: 1Gi
    gke-gcsfuse/ephemeral-storage-request: 50Gi

Ten en cuenta las siguientes consideraciones cuando decidas la cantidad de recursos para asignar:

  • Si configuras solo una de las anotaciones de solicitud o límite de recursos, GKE aplica los mismos valores para la solicitud de recursos y el límite de recursos.
  • Si tu Pod de carga de trabajo consume varios volúmenes de Cloud Storage, varias instancias de Cloud Storage FUSE comparten los recursos del contenedor de sidecar. Si esto se aplica a tu caso, considera aumentar la asignación de recursos para varios volúmenes de Cloud Storage.
  • Asigna más CPU al contenedor del archivo adicional si tus cargas de trabajo necesitan una capacidad de procesamiento mayor. Una CPU insuficiente causará una limitación de Cloud Storage FUSE.
  • Si tus cargas de trabajo necesitan procesar una gran cantidad de archivos y el almacenamiento en caché de metadatos de Cloud Storage FUSE está habilitado, debes aumentar la asignación de memoria del contenedor del archivo adicional. El consumo de memoria de Cloud Storage FUSE para el almacenamiento en caché de metadatos es proporcional a la cantidad de archivos, pero no al tamaño del archivo. Una memoria insuficiente provocará errores de memoria en Cloud Storage FUSE y hará que falle la aplicación de la carga de trabajo.
  • Para el almacenamiento en caché de archivos, Cloud Storage FUSE almacena en caché los archivos en un directorio temporal local de forma predeterminada. Estima cuánto espacio libre necesita tu carga de trabajo para el almacenamiento en caché de archivos y aumenta el límite de almacenamiento efímero según corresponda. Para obtener más información, consulta los atributos de volumen.
  • Para las operaciones de escritura, Cloud Storage FUSE almacena de forma predeterminada los archivos en un directorio temporal local antes de que los archivos se suban al bucket de Cloud Storage. Estima cuánto espacio libre necesita tu carga de trabajo para la etapa de pruebas cuando escribas archivos grandes y aumenta el límite de almacenamiento efímero según corresponda. Para obtener más información, consulta Semántica de lectura y escritura en la documentación de GitHub de Cloud Storage FUSE.
  • Puedes usar el valor "0" para anular cualquier límite o solicitud de recursos en los clústeres estándar. Por ejemplo, la anotación gke-gcsfuse/memory-limit: "0" deja el límite de memoria del contenedor de sidecar vacío con la solicitud de memoria predeterminada. Esto es útil cuando no puedes decidir la cantidad de recursos que Cloud Storage FUSE necesita para tus cargas de trabajo y deseas permitir que Cloud Storage FUSE consuma todos los recursos disponibles en un nodo. Después de calcular los requisitos de recursos para Cloud Storage FUSE según las métricas de las cargas de trabajo, puedes establecer los límites adecuados.

Configura una imagen privada para el contenedor de sidecar

En esta sección, se describe cómo usar la imagen del contenedor del archivo adicional si la alojas en un registro de contenedores privado. Esta situación podría aplicarse si necesitas usar clústeres privados con fines de seguridad o si tu clúster tiene acceso limitado a la Internet pública. Para configurar y consumir la imagen del contenedor de sidecar privada, sigue estos pasos:

  1. Consulta esta página para buscar una imagen de contenedor de sidecar pública compatible.

  2. Extráelo a tu entorno local y envíalo a tu Container Registry privado.

  3. En el manifiesto, especifica un contenedor llamado gke-gcsfuse-sidecar solo con el campo image. GKE usará la imagen de contenedor de sidecar especificada para prepararse para la inserción del contenedor de sidecar. A continuación, se muestra un ejemplo:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  containers:
  - name: gke-gcsfuse-sidecar
    image: PRIVATE_REGISTRY/gcs-fuse-csi-driver-sidecar-mounter:PRIVATE_IMAGE_TAG
  - name: main # your main workload container.

Reemplaza lo siguiente:

  • PRIVATE_REGISTRY: Es el registro de contenedores privado.
  • PRIVATE_IMAGE_TAG: Es la etiqueta de imagen del contenedor de sidecar privado.

Configura un volumen de búfer de escritura personalizado para el contenedor de sidecar

En esta sección, se describe cómo configurar un volumen de búfer personalizado para el almacenamiento en búfer de escritura de Cloud Storage FUSE. Esta situación puede aplicarse si necesitas reemplazar el volumen emptyDir predeterminado para Cloud Storage FUSE a fin de almacenar en etapa intermedia los archivos en las operaciones de escritura. Puedes especificar cualquier tipo de almacenamiento compatible con GKE, como PersistentVolumeClaim, y GKE usará el volumen especificado para el almacenamiento en búfer de escritura de archivos. Esto es útil si necesitas escribir archivos de más de 10 GiB en clústeres de Autopilot. Para usar el volumen de búfer personalizado, debes especificar un fsGroup que no sea cero. En el siguiente ejemplo, se muestra cómo puedes usar un PVC predefinido como volumen de búfer:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  securityContext:
    fsGroup: FS_GROUP
  containers:
  ...
  volumes:
  - name: gke-gcsfuse-buffer
    persistentVolumeClaim:
      claimName: BUFFER_VOLUME_PVC

Reemplaza lo siguiente:

  • FS_GROUP: es el ID de fsGroup.
  • BUFFER_VOLUME_PVC: Es el nombre predefinido de la PVC.

Configura un volumen de caché de lectura personalizado para el contenedor de sidecar

En esta sección, se describe cómo configurar un volumen de caché personalizado para el almacenamiento en caché de lectura de Cloud¡ Storage FUSE. Esta situación puede aplicarse si necesitas reemplazar el volumen emptyDir predeterminado para Cloud Storage FUSE a fin de almacenar en caché los archivos en las operaciones de lectura. Puedes especificar cualquier tipo de almacenamiento compatible con GKE, como PersistentVolumeClaim, y GKE usará el volumen especificado para el almacenamiento en caché de archivos. Esto es útil si necesitas guardar en caché archivos de más de 10 GiB en clústeres de Autopilot. Para usar el volumen de caché personalizado, debes especificar un fsGroup que no sea cero. En el siguiente ejemplo, se muestra cómo puedes usar un PVC predefinido como volumen de caché:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  securityContext:
    fsGroup: FS_GROUP
  containers:
  ...
  volumes:
  - name: gke-gcsfuse-cache
    persistentVolumeClaim:
      claimName: CACHE_VOLUME_PVC

Reemplaza lo siguiente:

  • FS_GROUP: es el ID de fsGroup.
  • CACHE_VOLUME_PVC: Es el nombre predefinido de la PVC.

Aprovisiona tu volumen como un volumen efímero de CSI

Los volúmenes efímeros CSI respaldados por los buckets de Cloud Storage están vinculados al ciclo de vida del Pod. Con este enfoque de aprovisionamiento, no necesitas mantener los objetos PersistentVolume y PersistentVolumeClaim asociados con los buckets de Cloud Storage después de la finalización del Pod.

Consume el volumen de almacenamiento efímero de CSI en un Pod

  1. Guarda el siguiente manifiesto YAML:

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-ephemeral
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  terminationGracePeriodSeconds: 60
  containers:
  - image: busybox
    name: busybox
    command: ["sleep"]
    args: ["infinity"]
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
      readOnly: true
  serviceAccountName: KSA_NAME
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      readOnly: true
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs"
        gcsfuseLoggingSeverity: warning

    En el ejemplo anterior, se muestra cómo puedes especificar el bucket de Cloud Storage intercalado en el manifiesto del Pod. El ejemplo incluye los siguientes campos:

    • metadata.annotations: La anotación gke-gcsfuse/volumes: "true" es obligatoria. Consulta Configura recursos para el contenedor de sidecar a fin de obtener anotaciones opcionales.
    • spec.terminationGracePeriodSeconds: Es opcional. El valor predeterminado es de 30. Si necesitas escribir archivos grandes en el bucket de Cloud Storage, aumenta este valor a fin de asegurarte de que Cloud Storage FUSE tenga tiempo suficiente para vaciar los datos después de que se cierre la aplicación. Para obtener más información, consulta Prácticas recomendadas de Kubernetes: Finalización controlada.
    • spec.serviceAccountName: usa la misma ServiceAccount de Kubernetes que en el paso Configura el acceso a los buckets de Cloud Storage a través de la federación de identidades para cargas de trabajo de GKE para GKE.
    • spec.volumes[n].csi.driver: usa gcsfuse.csi.storage.gke.io como el nombre del controlador de CSI.
    • spec.volumes[n].csi.volumeAttributes.bucketName: especifica el nombre de tu bucket de Cloud Storage FUSE. Puedes especificar un guion bajo (_) para activar todos los buckets a los que puede acceder la ServiceAccount de Kubernetes. Para obtener más información, consulta Activación dinámica en la documentación de GitHub del FUSE de Cloud Storage.
    • spec.volumes[n].csi.volumeAttributes.mountOptions: es opcional. Pasa opciones de activación a Cloud Storage FUSE. Especifica las marcas en una string separadas por comas y sin espacios.
    • spec.volumes[n].csi.volumeAttributes: es opcional. Pasa otros atributos de volumen a Cloud Storage FUSE.
    • spec.volumes[n].csi.readOnly: es opcional. Especifica true si todas las activaciones de volumen son de solo lectura.
    • spec.containers[n].volumeMounts[m].readOnly: Es opcional. Especifica true si solo una activación de volumen específica es de solo lectura.

  2. Aplica el manifiesto al clúster:

    kubectl apply -f FILE_PATH

    Reemplaza FILE_PATH por la ruta de acceso al archivo YAML.

Consume el volumen de almacenamiento efímero de CSI en una carga de trabajo de trabajo

  1. Guarda el siguiente manifiesto YAML:

    apiVersion: batch/v1
kind: Job
metadata:
  name: gcs-fuse-csi-job-example
  namespace: NAMESPACE
spec:
  template:
    metadata:
      annotations:
        gke-gcsfuse/volumes: "true"
    spec:
      serviceAccountName: KSA_NAME
      containers:
      - name: writer
        image: busybox
        command:
          - "/bin/sh"
          - "-c"
          - touch /data/test && echo $(date) >> /data/test && sleep 10
        volumeMounts:
        - name: gcs-fuse-csi-ephemeral
          mountPath: /data
      - name: reader
        image: busybox
        command:
          - "/bin/sh"
          - "-c"
          - sleep 10 && cat /data/test
        volumeMounts:
        - name: gcs-fuse-csi-ephemeral
          mountPath: /data
          readOnly: true
      volumes:
      - name: gcs-fuse-csi-ephemeral
        csi:
          driver: gcsfuse.csi.storage.gke.io
          volumeAttributes:
            bucketName: BUCKET_NAME
      restartPolicy: Never
  backoffLimit: 1

    Reemplaza lo siguiente:

    El manifiesto implementa un trabajo que consume un bucket de Cloud Storage FUSE a través de un volumen efímero de CSI.

  2. Aplica el manifiesto al clúster:

    kubectl apply -f FILE_PATH

    Reemplaza FILE_PATH por la ruta de acceso al archivo YAML.

Si usas el controlador de CSI en una carga de trabajo Job o si el pod RestartPolicy es Never, el contenedor de sidecar saldrá automáticamente después de que terminen todos los demás contenedores de carga de trabajo.

Para ver ejemplos adicionales, consulta Aplicaciones de ejemplo en la documentación del proyecto de GitHub.

Aprovisiona tu volumen con el aprovisionamiento estático

Con el aprovisionamiento estático, creas uno o más objetos PersistentVolume (PV) que contienen los detalles del sistema de almacenamiento subyacente. Los Pods de tus clústeres pueden consumir el almacenamiento a través de PersistentVolumeClaims (PVC).

Crea un PersistentVolume

  1. Guarda el siguiente manifiesto YAML:

    apiVersion: v1
kind: PersistentVolume
metadata:
  name: gcs-fuse-csi-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  storageClassName: example-storage-class
  claimRef:
    namespace: NAMESPACE
    name: gcs-fuse-csi-static-pvc
  mountOptions:
    - implicit-dirs
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME
    volumeAttributes:
      gcsfuseLoggingSeverity: warning

    En el manifiesto de ejemplo, se muestra cómo puedes definir un PersistentVolume para buckets de Cloud Storage. El ejemplo incluye los siguientes campos:

    • spec.claimRef.namespace: Especifica el espacio de nombres de PersistentVolumeClaim.
    • spec.claimRef.name: Especifica el nombre de PersistentVolumeClaim.
    • spec.csi.driver: usa gcsfuse.csi.storage.gke.io como el nombre del controlador de CSI.
    • spec.csi.volumeHandle: especifica el nombre de tu bucket de Cloud Storage. Puedes pasar un guion bajo (_) para activar todos los buckets a los que tiene acceso la ServiceAccount de Kubernetes. Para obtener más información, consulta Activación dinámica en la documentación de GitHub del FUSE de Cloud Storage.
    • spec.mountOptions: es opcional. Pasa opciones de activación a Cloud Storage FUSE.
    • spec.csi.volumeAttributes: es opcional. Pasa atributos de volumen a Cloud Storage FUSE.

  2. Aplica el manifiesto al clúster:

    kubectl apply -f FILE_PATH

    Reemplaza FILE_PATH por la ruta de acceso al archivo YAML.

Crea una PersistentVolumeClaim

  1. Guarda el siguiente manifiesto YAML:

    apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: gcs-fuse-csi-static-pvc
  namespace: NAMESPACE
spec:
  accessModes:
  - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  volumeName: gcs-fuse-csi-pv
  storageClassName: example-storage-class

    En el manifiesto de ejemplo, se muestra cómo puedes definir un PersistentVolumeClaim para vincular el PersistentVolume. El ejemplo incluye los siguientes campos:

    • metadata.namespace: Especifica el espacio de nombres de PersistentVolumeClaim que debe ser coherente con el de tu carga de trabajo.
    • spec.volumeName: Especifica el nombre de PersistentVolume.

    Para vincular un PersistentVolume a una PersistentVolumeClaim, asegúrate de seguir estos lineamientos:

    • Los campos spec.storageClassName en los manifiestos de PV y PVC deben coincidir. No es necesario que storageClassName se refiera a un objeto StorageClass existente. Para vincular la reclamación a un volumen, puedes usar el nombre que quieras, pero no puede estar vacío.
    • Los campos spec.accessModes en los manifiestos de PV y PVC deben coincidir.
    • spec.capacity.storage en el manifiesto de PersistentVolume debe coincidir con spec.resources.requests.storage en el manifiesto de PersistentVolumeClaim. Dado que los depósitos de Cloud Storage no tienen límites de tamaño, puedes ingresar cualquier número de capacidad, pero no puede estar vacío.

  2. Aplica el manifiesto al clúster:

    kubectl apply -f FILE_PATH

    Reemplaza FILE_PATH por la ruta de acceso al archivo YAML.

Consume el volumen desde una PersistentVolumeClaim

  1. Guarda el siguiente manifiesto YAML:

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-static-pvc
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  containers:
  - image: busybox
    name: busybox
    command: ["sleep"]
    args: ["infinity"]
    volumeMounts:
    - name: gcs-fuse-csi-static
      mountPath: /data
      readOnly: true
  serviceAccountName: KSA_NAME
  volumes:
  - name: gcs-fuse-csi-static
    persistentVolumeClaim:
      claimName: gcs-fuse-csi-static-pvc
      readOnly: true

    En el ejemplo, se muestra cómo puedes definir un Pod que consume un bucket de Cloud Storage FUSE a través de una PersistentVolumeClaim. El ejemplo incluye los siguientes campos:

  2. Aplica el manifiesto al clúster:

    kubectl apply -f FILE_PATH

    Reemplaza FILE_PATH por la ruta de acceso al archivo YAML.

Para ver ejemplos adicionales, consulta Aplicaciones de ejemplo en la documentación del proyecto de GitHub.

Consume tus volúmenes con el almacenamiento en caché de archivos habilitado

De forma predeterminada, la función de almacenamiento en caché de archivos está inhabilitada en GKE. Para habilitar y controlar el almacenamiento en caché de archivos, usa el atributo de volumen fileCacheCapacity.

GKE usa un volumen emptyDir para el almacenamiento en caché de archivos de Cloud Storage FUSE respaldado por el disco de arranque de la VM del nodo. Si habilitas SSD local en el nodo, GKE usa la SSD local para respaldar el volumen emptyDir.

Puedes configurar un volumen de caché de lectura personalizado para el contenedor de archivo adicional para reemplazar el volumen emptyDir predeterminado para el almacenamiento en caché de archivos en operaciones de lectura. Para las familias de VM de CPU y GPU compatibles con SSDs locales, recomendamos usar almacenamiento SSD local. Para las familias de TPU o Autopilot, recomendamos usar el disco persistente balanceado o el disco persistente SSD.

Consume un volumen de almacenamiento efímero de CSI con el almacenamiento en caché de archivos habilitado

Para implementar un Pod que consume un bucket de Cloud Storage FUSE a través de un volumen efímero de CSI con almacenamiento en caché de archivos, sigue estos pasos:

  1. Crea un clúster o grupo de nodos con almacenamiento efímero respaldado por SSD local.

    Sigue la documentación de GKE para crear un clúster o grupo de nodos con almacenamiento efímero respaldado por SSD local.

  2. Guarda el siguiente manifiesto YAML:

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-file-cache-example
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/ephemeral-storage-limit: "50Gi"
spec:
  nodeSelector:
    cloud.google.com/gke-ephemeral-storage-local-ssd: "true"
  restartPolicy: Never
  initContainers:
  - name: data-loader
    image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
    resources:
      limits:
        cpu: 500m
        memory: 1Gi
      requests:
        cpu: 500m
        memory: 1Gi
    command:
      - "/bin/sh"
      - "-c"
      - |
        mkdir -p /test_files
        for i in $(seq 1 1000); do dd if=/dev/zero of=/test_files/file_$i.txt bs=1024 count=64; done
        gsutil -m cp -r /test_files gs://BUCKET_NAME
  containers:
  - name: data-validator
    image: busybox
    resources:
      limits:
        cpu: 500m
        memory: 512Mi
      requests:
        cpu: 500m
        memory: 512Mi
    command:
      - "/bin/sh"
      - "-c"
      - |
        echo "first read with cache miss"
        time cat /data/test_files/file_* > /dev/null

        echo "second read from local cache"
        time cat /data/test_files/file_* > /dev/null
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
  serviceAccountName: KSA_NAME
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs"
        fileCacheCapacity: "10Gi"

    Reemplaza lo siguiente:

    El contenedor init data-loader genera 1,000 archivos con un tamaño de 64 KiB y los sube a un bucket de Cloud Storage. El contenedor principal data-validator lee todos los archivos del bucket dos veces y registra la duración.

  3. Aplica el manifiesto al clúster:

    kubectl apply -f FILE_PATH

    Reemplaza FILE_PATH por la ruta de acceso al archivo YAML.

  4. Para ver el resultado del registro, ejecuta el siguiente comando:

    kubectl logs -n NAMESPACE gcs-fuse-csi-file-cache-example -c data-validator

    Reemplaza NAMESPACE por el espacio de nombres de tu carga de trabajo.

    El resultado es similar al siguiente:

    first read with cache miss
real    0m 54.68s
...
second read from local cache
real    0m 0.38s
...

    En el resultado, se muestra que la segunda lectura con la caché local es mucho más rápida que la primera lectura con error de caché.

Configura cómo se activan los buckets de Cloud Storage FUSE

En esta sección, se describe cómo puedes configurar los volúmenes de Cloud Storage FUSE.

Opciones de activación

El controlador CSI del FUSE de Cloud Storage admite opciones de activación para configurar cómo se activan los buckets de Cloud Storage en tu sistema de archivos local. Para obtener una lista completa de las marcas de activación compatibles, consulta la documentación de la CLI de gcsfuse.

Puedes especificar las marcas de activación de las siguientes maneras:

  • En el campo spec.mountOptions de un manifiesto PersistentVolume, si usas el aprovisionamiento estático.
  • En el campo spec.volumes[n].csi.volumeAttributes.mountOptions, si usas volúmenes efímeros de CSI.

Atributos de volumen

El controlador de CSI de Cloud Storage FUSE no te permite especificar directamente el archivo de configuración de Cloud Storage FUSE. Puedes configurar algunos de los campos del archivo de configuración mediante los siguientes atributos de volumen. Los valores se traducen en los campos del archivo de configuración.

  • gcsfuseLoggingSeverity

    • Descripción: la gravedad de los registros que deseas que Cloud Storage FUSE genere, expresado como una enumeración. Si ya usas las opciones de activación debug_fuse, debug_fs o debug_gcs, esta nueva configuración se establecerá de forma automática en trace. Este atributo de volumen se traduce al campo del archivo de configuración logging:severity.

    • Valores válidos (ordenados desde la gravedad más baja a la más alta):

      • trace
      • debug
      • info
      • warning
      • error

    • Valor predeterminado: info.

  • fileCacheCapacity

    • Descripción: El tamaño máximo que puede usar la caché del archivo. Si se presenta un valor distinto de cero, este atributo de volumen habilita el almacenamiento en caché de archivos en Cloud Storage FUSE. Este atributo de volumen se traduce al campo del archivo de configuración file-cache:max-size-mb.

    • Valores válidos:

      • Valores de cantidad, por ejemplo: 500Mi, 10Gi.
      • "-1": para usar toda la capacidad disponible del volumen de caché.
      • "0": la caché del archivo está inhabilitada.

    • Valor predeterminado: "0".

  • fileCacheForRangeRead

    • Descripción: Indica si el objeto completo debe descargarse de forma asíncrona y almacenarse en el directorio de caché de Cloud Storage FUSE cuando la primera lectura se realiza desde un desplazamiento distinto de cero. Esto debe configurarse como “true” si planeas realizar varias lecturas aleatorias o parciales. Este atributo de volumen se traduce al campo del archivo de configuración file-cache:cache-file-for-range-read.

    • Valores válidos:

      • Valores booleanos en formato de string: "true", "false".

    • Valor predeterminado: "false".

  • metadataStatCacheCapacity

    • Descripción: El tamaño máximo que puede usar la caché de estadísticas. La caché de estadística siempre se mantiene por completo en la memoria. Si ya usas la opción de activación stat-cache-capacity, el valor se respetará y se traducirá de forma adecuada a esta configuración nueva. Este atributo de volumen se traduce al campo del archivo de configuración metadata-cache:stat-cache-max-size-mb.

    • Valores válidos:

      • Valores de cantidad, por ejemplo: 500Mi, 1Gi.
      • “-1”: para permitir que la caché de estadísticas use tanta memoria como sea necesario
      • “0”: la caché de estadísticas está inhabilitada.
      • Usa el valor predeterminado de 32Mi si tu carga de trabajo incluye hasta 20,000 archivos. Si tu carga de trabajo supera los 20,000 archivos, aumenta el tamaño en valores de 10 MiB por cada 6,000 archivos adicionales, un promedio de alrededor de 1,500 bytes por archivo.

    • Valor predeterminado: 32Mi.

  • metadataTypeCacheCapacity

    • Descripción: El tamaño máximo por directorio que puede usar la caché de tipo. La caché de tipo siempre se mantiene por completo en la memoria. Este atributo de volumen se traduce al campo del archivo de configuración metadata-cache:type-cache-max-size-mb.

    • Valores válidos:

      • Valores de cantidad, por ejemplo: 500Mi, 1Gi.
      • "-1": Permite que el tipo caché use tanta memoria como sea necesario.
      • "0": el tipo de caché está inhabilitada.
      • 4Mi: Usa el valor predeterminado de si la cantidad máxima de archivos dentro de un solo directorio del bucket que activas contiene 20,000 archivos o menos. Si la cantidad máxima de archivos dentro de un solo directorio que activas contiene más de 20,000 archivos, aumenta el tamaño en 1 MiB por cada 5,000 archivos, un promedio de 200 bytes por archivo.

    • Valor predeterminado: 4Mi.

  • metadataCacheTtlSeconds

    • Descripción: El tiempo de actividad (TTL), en segundos, de las entradas de metadatos almacenadas en caché. Si ya usas las opciones de activación stat-cache-ttl o type-cache-ttl, los valores se respetarán y se traducirán de forma adecuada a esta configuración nueva. Este atributo de volumen se traduce al campo del archivo de configuración metadata-cache:ttl-secs.

    • Valores válidos:

      • Números enteros en formato de string, por ejemplo: “600”.
      • "-1": Omite un vencimiento de TTL y entrega el archivo desde la caché cuando esté disponible.
      • "0": Asegúrate de que se lea el archivo más actualizado. El uso de un valor de 0 emite una llamada de metadatos Get para garantizar que la generación de objetos del archivo en la caché coincida con lo que se almacena en Cloud Storage.

    • Valor predeterminado: "60".

Puedes especificar los atributos de volumen de las siguientes maneras:

  • En el campo spec.csi.volumeAttributes de un manifiesto PersistentVolume, si usas el aprovisionamiento estático.
  • En el campo spec.volumes[n].csi.volumeAttributes, si usas volúmenes efímeros de CSI.

Consideraciones

Considera lo siguiente cuando configures las activaciones:

  • Las siguientes marcas no están permitidas: app-name, temp-dir, foreground, log-file, log-format, key-file, token-url y reuse-token-from-url.
  • El FUSE de Cloud Storage no hace que los directorios implícitos sean visibles de forma predeterminada. Para hacer que estos directorios sean visibles, puedes activar la marca de activación implicit-dirs. Para obtener más información, consulta Archivos y directorios en la documentación de GitHub del FUSE Cloud Storage.
  • Si usas un Contexto de seguridad para tu Pod o contenedor, o si tu imagen de contenedor usa un usuario o grupo no raíz, debes configurar las marcas de activación uid y gid. También debes usar las marcas de activación file-mode y dir-mode para configurar los permisos del sistema de archivos. Ten en cuenta que no puedes ejecutar los comandos chmod, chown o chgrp en un sistema de archivos de Cloud Storage FUSE, por lo que las marcas de activación uid, gid, file-mode y dir-mode son necesarias para proporcionar acceso a un usuario o grupo no raíz.
  • Si solo deseas activar un directorio en el bucket en lugar de todo el bucket, pasa la ruta de acceso relativa al directorio con la marca only-dir=relative/path/to/the/bucket/root.
  • Para ajustar el comportamiento del almacenamiento en caché de Cloud Storage FUSE, configura los atributos de volumen. Consulta la documentación de Almacenamiento en caché de Cloud Storage FUSE para obtener más detalles.
  • Si la cantidad de núcleos o subprocesos es mayor que 100, cambia max-cons-per-host a este valor.
  • Si necesitas configurar las opciones de activación del kernel de Linux, puedes pasar las opciones a través de la marca o. Por ejemplo, si no deseas permitir la ejecución directa de ningún objeto binario en el sistema de archivos activado, establece la marca o=noexec. Cada opción requiere una marca independiente, por ejemplo, o=noexec,o=noatime. Solo se permiten las siguientes opciones: exec, noexec, atime, noatime, sync, async y dirsync.
  • Si necesitas solucionar problemas del FUSE de Cloud Storage, configura las marcas debug_fuse, debug_fs y debug_gcs. Si se especifica alguna de las tres opciones, el atributo de volumen gcsfuseLoggingSeverity se establece de forma automática en trace.
  • El controlador de CSI de Cloud Storage FUSE no te permite modificar el campo cache-dir en el archivo de configuración de Cloud Storage FUSE; usa el atributo de volumen fileCacheCapacity para habilitar o inhabilitar el almacenar en caché los archivos. Para reemplazar el volumen emptyDir predeterminado para el almacenamiento en caché de archivos, puedes configurar un volumen de caché personalizado para el contenedor de archivo adicional.

Inhabilita el controlador de CSI de Cloud Storage FUSE

No puedes inhabilitar el controlador de CSI de Cloud Storage FUSE en clústeres de Autopilot.

Puedes inhabilitar el controlador de CSI de Cloud Storage FUSE en un clúster estándar existente con Google Cloud CLI.

gcloud container clusters update CLUSTER_NAME \
    --update-addons GcsFuseCsiDriver=DISABLED

Reemplaza CLUSTER_NAME por el nombre del clúster.

Soluciona problemas

Para solucionar problemas cuando se usa el controlador de CSI del FUSE de Cloud Storage, consulta la guía de solución de problemas en la documentación del proyecto de GitHub.

¿Qué sigue?