Activa los buckets de Cloud Storage como volúmenes persistentes

En esta guía, se muestra cómo usar los volúmenes persistentes de Kubernetes respaldados por tus buckets de Cloud Storage para administrar los recursos de almacenamiento de tus Pods de Kubernetes en Google Kubernetes Engine (GKE). Considera usar esta opción de almacenamiento si ya conoces PersistentVolumes y deseas consistencia con tus implementaciones existentes que dependen de este tipo de recurso.

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

Antes de leer esta página, asegúrate de estar familiarizado con los volúmenes persistentes de Kubernetes, los pods de Kubernetes y los buckets de Cloud Storage.

Si deseas una interfaz optimizada basada en pods que no requiera experiencia previa con volúmenes persistentes de Kubernetes, consulta Cómo activar buckets de Cloud Storage como volúmenes efímeros de CSI.

Antes de comenzar

Asegúrate de cumplir con los siguientes requisitos previos:

Cómo funcionan los volúmenes persistentes para los buckets de Cloud Storage

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

El uso de un volumen persistente respaldado por un bucket de Cloud Storage implica las siguientes operaciones:

  1. Definición de almacenamiento: Defines un PersistentVolume en tu clúster de GKE, incluido el controlador de CSI que se usará y los parámetros obligatorios. Para el 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 local más rápido.

    Además, puedes usar la función de descarga en paralelo para acelerar la lectura de archivos grandes desde Cloud Storage para descargas de varios subprocesos. Puedes usar esta función para mejorar los tiempos de carga de los modelos, en especial para las operaciones de lectura de más de 1 GB de tamaño.

  2. Invocación del controlador: Cuando un PersistentVolumeClaim solicita almacenamiento que coincide con la especificación de PersistentVolume, GKE invoca el controlador de CSI de FUSE de Cloud Storage.

  3. Activa el bucket: El controlador de CSI activa el bucket en el nodo en el que se programa el Pod solicitante. Esto permite que el Pod acceda al contenido del bucket como un directorio en su sistema de archivos local. Para ajustar cómo se activan los buckets en el sistema de archivos, puedes usar las opciones de activación. También puedes usar los atributos de volumen para configurar el comportamiento específico del controlador de CSI de Cloud Storage FUSE.

  4. Vuelve a conectar: Si el Pod se reinicia o se reprograma para otro nodo, el controlador de CSI vuelve a activar el mismo bucket en el nodo nuevo, lo que garantiza la accesibilidad a los datos.

Crea un PersistentVolume

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

    Pod

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

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

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

    • spec.csi.driver: usa gcsfuse.csi.storage.gke.io como el nombre del controlador de CSI.

    De manera opcional, puedes ajustar estas variables:

    • spec.mountOptions: Pasa opciones de activación a Cloud Storage FUSE. Especifica las marcas en una cadena separada por comas y sin espacios.
    • spec.csi.volumeAttributes: Pasa atributos de volumen adicionales a Cloud Storage FUSE.

    Pod (almacenamiento en caché de archivos)

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

    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 GitHub del FUSE de Cloud Storage.

    Pod (descarga en paralelo)

    apiVersion: v1
kind: PersistentVolume
metadata:
  name: gcs-fuse-csi-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  storageClassName: example-storage-class 
  mountOptions:
    - implicit-dirs
    - file-cache:enable-parallel-downloads:true
    - file-cache:max-size-mb:-1
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME
  claimRef:
    name: gcs-fuse-csi-static-pvc
    namespace: NAMESPACE

    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 GitHub del FUSE de Cloud Storage.

  2. Aplica el manifiesto al clúster:

    kubectl apply -f PV_FILE_PATH

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

Crea una PersistentVolumeClaim

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

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

    Reemplaza NAMESPACE por el espacio de nombres de Kubernetes en el que deseas implementar tu Pod.

    Para vincular tu PersistentVolume a una PersistentVolumeClaim, verifica estos parámetros de configuración:

    • Los campos spec.storageClassName en los manifiestos de PersistentVolume y PersistentVolumeClaim 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 PersistentVolume y PersistentVolumeClaim deben coincidir.
    • El campo spec.capacity.storage en tu manifiesto de PersistentVolume debe coincidir con el spec.resources.requests.storage en el manifiesto de PersistentVolumeClaim. Dado que los buckets 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 PVC_FILE_PATH

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

Consume el volumen en un Pod

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

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-static-pvc  
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/ephemeral-storage-limit: "50Gi" 
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

    Reemplaza los siguientes valores:

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

    De manera opcional, puedes ajustar estas variables:

    • spec.containers[n].volumeMonts[n].readOnly: Especifica verdadero si solo las activaciones de volumen específicas son de solo lectura.
    • spec.volumes[n].persistentVolumeClaim.readOnly: Especifica "true" si todos los activaciones de volumen son de solo lectura.

  2. Aplica el manifiesto al clúster:

    kubectl apply -f POD_FILE_PATH

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

Soluciona problemas

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

Para obtener más sugerencias de solución de problemas, consulta la Guía de solución de problemas en la documentación del proyecto de GitHub.

¿Qué sigue?