Activa los buckets de Cloud Storage como volúmenes efímeros de CSI

En esta guía, se muestra cómo usar los volúmenes efímeros de CSI respaldados por tus buckets de Cloud Storage para administrar automáticamente los recursos de almacenamiento de tus Pods o trabajos de Kubernetes en Google Kubernetes Engine (GKE). Los volúmenes efímeros de CSI están vinculados al ciclo de vida del Pod o del trabajo, y no es necesario que manejes manualmente los objetos PersistentVolume y PersistentVolumeClaim.

Esta guía está dirigida a los administradores y operadores de la plataforma que desean simplificar la administración del almacenamiento para sus aplicaciones de GKE.

Antes de leer esta página, asegúrate de estar familiarizado con los volúmenes efímeros de CSI, los Pods y los Jobs de Kubernetes, y los buckets de Cloud Storage.

Si ya conoces los PersistentVolumes y deseas mantener la coherencia con tus implementaciones existentes que dependen de este tipo de recurso, consulta Cómo activar buckets de Cloud Storage como volúmenes persistentes.

Antes de comenzar

Asegúrate de haber completado los siguientes requisitos previos:

Cómo funciona el almacenamiento efímero de CSI para los buckets de Cloud Storage

Los volúmenes efímeros de CSI simplifican la administración del almacenamiento para tus aplicaciones en GKE. Puedes definir volúmenes efímeros de CSI directamente en la especificación de tu Pod o Job. El uso de volúmenes efímeros de CSI elimina la necesidad de objetos PersistentVolume y PersistentVolumeClaim separados.

El uso de un volumen efímero de CSI implica las siguientes operaciones:

  1. Definición de almacenamiento: Especificas el almacenamiento en el archivo YAML de tu Pod o Job, incluido el controlador CSI que se usará y cualquier parámetro requerido. En el caso del controlador CSI de Cloud Storage FUSE, debes especificar el nombre del bucket y otros detalles relevantes.

    De manera opcional, puedes ajustar el rendimiento de tu controlador de CSI con la función de almacenamiento en caché de archivos. El almacenamiento en caché de archivos puede mejorar el rendimiento de las apps de GKE, ya que almacena en caché los archivos de Cloud Storage a los que se accede con frecuencia en un disco más rápido.

    Además, puedes usar la función de descarga en paralelo para acelerar la lectura de archivos grandes de Cloud Storage para descargas de varios subprocesos. Puedes usar esta función para mejorar los tiempos de carga del modelo, especialmente para las lecturas de más de 1 GB.

  2. Invocación del controlador: Cuando creas el Pod o el trabajo, GKE detecta la solicitud de volumen efímero y llama al controlador de CSI de Cloud Storage FUSE.

  3. Activación y conexión de volúmenes: El controlador CSI activa el volumen efímero CSI (que apunta al bucket de Cloud Storage subyacente) y lo pone a disposición del Pod o del trabajo, lo que lo hace accesible para tu aplicación. Para ajustar la forma en que se activan los buckets en el sistema de archivos, puedes usar opciones de activación. También puedes usar atributos de volumen para configurar el comportamiento específico del controlador CSI de Cloud Storage FUSE.

  4. Administración del ciclo de vida: El volumen efímero existe durante la vida útil del Pod o el trabajo. Cuando se borra el Pod o se completa el trabajo, el controlador de CSI controla automáticamente la limpieza y el desmontaje del volumen.

Adjunta el volumen efímero de CSI

Sigue estas instrucciones según si deseas conectar el volumen efímero del CSI a un Pod o a un trabajo.

Pod

Para adjuntar el volumen efímero de CSI en un Pod, sigue estos pasos:

  1. Crea un manifiesto YAML de Pod con la siguiente especificación:

    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"

    Reemplaza los siguientes valores:

    • NAMESPACE: Es el espacio de nombres de Kubernetes en el que deseas implementar tu Pod.
    • KSA_NAME: Es el nombre de la ServiceAccount de Kubernetes que especificaste cuando configuraste el acceso a los buckets de Cloud Storage.
    • BUCKET_NAME: Es el nombre del bucket de Cloud Storage que especificaste cuando configuraste el acceso a los buckets de Cloud Storage. 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 Cloud Storage FUSE.

    En el manifiesto de ejemplo, se muestran estos parámetros de configuración obligatorios:

    • metadata.annotations: La anotación gke-gcsfuse/volumes: "true" es obligatoria. Consulta Configura el contenedor de sidecar para obtener anotaciones opcionales.
    • spec.volumes[n].csi.driver: Usa gcsfuse.csi.storage.gke.io como el nombre del controlador de CSI.

    De manera opcional, puedes ajustar estas variables:

    • spec.terminationGracePeriodSeconds: De forma predeterminada, este valor se establece en 30. Si necesitas escribir archivos grandes en el bucket de Cloud Storage, aumenta este valor para 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.volumes[n].csi.volumeAttributes.mountOptions: Pasa opciones de activación a Cloud Storage FUSE. Especifica las marcas en una cadena separada por comas y sin espacios.
    • spec.volumes[n].csi.volumeAttributes: Pasa atributos de volumen adicionales a Cloud Storage FUSE.
    • spec.volumes[n].csi.readOnly: Especifica verdadero si todas las activaciones de volumen son de solo lectura.
    • spec.containers[n].volumeMounts[m].readOnly: Especifica verdadero si solo una activación de volumen específica es de solo lectura.

  2. Ejecuta el siguiente comando para aplicar el manifiesto a tu clúster:

    kubectl apply -f FILE_PATH

    Reemplaza FILE_PATH por la ruta de acceso a tu archivo YAML.

Pod (almacenamiento en caché de archivos)

Para adjuntar el volumen efímero de CSI con almacenamiento en caché de archivos en un Pod, sigue estos pasos:

  1. Crea un clúster o grupo de nodos con almacenamiento efímero respaldado por SSD local siguiendo los pasos que se indican en Crea un clúster o grupo de nodos con almacenamiento efímero respaldado por SSD local.

  2. Crea un manifiesto YAML de Pod con la siguiente especificación:

    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
        gcloud storage cp /test_files gs://BUCKET_NAME --recursive
  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,file-cache:max-size-mb:-1"

    Reemplaza los siguientes valores:

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

    • BUCKET_NAME: Es el nombre del bucket de Cloud Storage que especificaste cuando configuraste el acceso a los buckets de Cloud Storage. 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 Cloud Storage FUSE.

      En el manifiesto de ejemplo, 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. Ejecuta el siguiente comando para aplicar el manifiesto a tu clúster:

    kubectl apply -f FILE_PATH

    Reemplaza FILE_PATH por la ruta de acceso a tu 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 debería ser similar al siguiente:

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

    El resultado muestra que la segunda lectura con la caché local es mucho más rápida que la primera lectura con un error de caché.

Pod (descarga paralela)

Para adjuntar el volumen efímero de CSI con descarga paralela en un Pod, sigue estos pasos:

  1. Crea un manifiesto YAML de Pod con la siguiente especificación:

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-ephemeral 
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/ephemeral-storage-limit: "50Gi" 
spec:
  containers:
  ...
  volumes:
  - name: gcs-fuse-csi-ephemeral 
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs,file-cache:enable-parallel-downloads:true,file-cache:max-size-mb:-1"
        fileCacheCapacity: "-1"

    Reemplaza los siguientes valores:

    • NAMESPACE: Es el espacio de nombres de Kubernetes en el que deseas implementar tu Pod.
    • BUCKET_NAME: Es el nombre del bucket de Cloud Storage que especificaste cuando configuraste el acceso a los buckets de Cloud Storage. 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 Cloud Storage FUSE.

  2. Ejecuta el siguiente comando para aplicar el manifiesto a tu clúster:

    kubectl apply -f FILE_PATH

    Reemplaza FILE_PATH por la ruta de acceso a tu archivo YAML.

Trabajo

Para adjuntar el volumen efímero de CSI en un trabajo, sigue estos pasos:

  1. Crea un manifiesto YAML de Job con la siguiente especificación:

    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 los siguientes valores:

    • NAMESPACE: Es el espacio de nombres de Kubernetes en el que implementas tu Pod.
    • KSA_NAME: Es el nombre de la ServiceAccount de Kubernetes que especificaste cuando configuraste el acceso a los buckets de Cloud Storage.
    • BUCKET_NAME: Es el nombre del bucket de Cloud Storage que especificaste cuando configuraste el acceso a los buckets de Cloud Storage. 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 Cloud Storage FUSE.

    En el manifiesto de ejemplo, se muestran estos parámetros de configuración obligatorios:

    • metadata.annotations: La anotación gke-gcsfuse/volumes: "true" es obligatoria. Consulta Configura el contenedor de sidecar para obtener anotaciones opcionales.
    • spec.volumes[n].csi.driver: Usa gcsfuse.csi.storage.gke.io como el nombre del controlador de CSI.

    De manera opcional, puedes ajustar estas variables:

    • spec.volumes[n].csi.volumeAttributes.mountOptions: Pasa opciones de activación a Cloud Storage FUSE. Especifica las marcas en una cadena separada por comas y sin espacios.
    • spec.volumes[n].csi.volumeAttributes: Pasa atributos de volumen adicionales a Cloud Storage FUSE.
    • spec.volumes[n].csi.readOnly: Especifica verdadero si todas las activaciones de volumen son de solo lectura.
    • spec.containers[n].volumeMounts[m].readOnly: Especifica verdadero si solo una activación de volumen específica es de solo lectura.

  2. Ejecuta el siguiente comando para aplicar el manifiesto a tu clúster:

    kubectl apply -f FILE_PATH

    Reemplaza FILE_PATH por la ruta de acceso a tu archivo YAML.

Soluciona problemas

Si necesitas solucionar problemas de Cloud Storage FUSE, puedes configurar la marca log-severity en TRACE. Establece la marca en la sección args de la especificación del contenedor del controlador dentro del YAML de implementación. Esto hace que el atributo de volumen gcsfuseLoggingSeverity se establezca automáticamente en el seguimiento.

Para obtener sugerencias adicionales para solucionar problemas, consulta la Guía de solución de problemas en la documentación del proyecto de GitHub.

¿Qué sigue?