Configura el controlador de CSI de Cloud Storage FUSE para GKE

En este documento, se muestra cómo configurar el controlador de CSI de Cloud Storage FUSE para acceder a los buckets de Cloud Storage desde Google Kubernetes Engine (GKE).

Con el controlador de CSI de Cloud Storage FUSE, tus cargas de trabajo de GKE pueden acceder a los buckets de Cloud Storage como un sistema de archivos local. El controlador de CSI integra Cloud Storage con GKE y simplifica la forma en que tus aplicaciones alojadas en contenedores interactúan con grandes conjuntos de datos almacenados en buckets. El controlador de CSI proporciona una interfaz estándar para el almacenamiento de GKE. En este documento, prepararás tu entorno y conectarás tus clústeres de GKE a los buckets de Cloud Storage con el controlador de CSI de Cloud Storage FUSE.

Este documento está dirigido a desarrolladores, administradores y especialistas en almacenamiento que integran cargas de trabajo de GKE con almacenamiento de objetos. Para obtener más información sobre los roles comunes y las tareas de ejemplo a las que hacemos referencia en el contenido de Google Cloud , consulta Roles y tareas comunes del usuario de GKE.

Crea el bucket de Cloud Storage

Si aún no lo hiciste, crea tus buckets de Cloud Storage. Activarás estos buckets como volúmenes en tu clúster de GKE. Para mejorar el rendimiento, establece el Tipo de ubicación en Región y selecciona una región que coincida con tu clúster de GKE.

Habilita el controlador CSI del FUSE de Cloud Storage

Sigue estos pasos según si usas clústeres de GKE Autopilot o Standard. Te recomendamos que uses un clúster de Autopilot para una experiencia de Kubernetes completamente administrada. Para elegir el modo que se adapte mejor a tus cargas de trabajo, consulta Elige un modo de operación de GKE.

Autopilot

El controlador de CSI de Cloud Storage FUSE está habilitado de forma predeterminada para los clústeres de Autopilot. Puedes ir directamente a Configura el acceso a buckets de Cloud Storage.

Estándar

Si tu clúster estándar tiene habilitado el controlador de CSI de Cloud Storage FUSE, ve a Configura el acceso a los buckets de Cloud Storage.

El controlador de CSI de Cloud Storage FUSE no está habilitado de forma predeterminada en los clústeres de Standard. Para crear un clúster estándar con el controlador CSI de Cloud Storage FUSE habilitado, puedes usar el comando gcloud container clusters create:

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

Reemplaza lo siguiente:

  • 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: Es la región o zona de Compute Engine para el clúster.
  • PROJECT_ID: Es el ID del 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

Para verificar que el controlador de CSI de Cloud Storage FUSE esté habilitado en tu clúster, ejecuta el siguiente comando:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --project=PROJECT_ID \
    --format="value(addonsConfig.gcsFuseCsiDriverConfig.enabled)"

Configura el acceso a los buckets de Cloud Storage

El controlador de CSI de Cloud Storage FUSE usa la federación de identidades para cargas de trabajo para GKE, de modo que puedas establecer permisos detallados sobre cómo los Pods de GKE pueden acceder a los datos almacenados en Cloud Storage.

Para que tu clúster de GKE pueda acceder a los buckets de Cloud Storage, autentícate con Workload Identity Federation for GKE con el bucket de Cloud Storage que deseas activar en la especificación de tu Pod:

  1. Si no tienes habilitada la federación de identidades para cargas de trabajo para GKE, sigue estos pasos para habilitarla. Si deseas usar un grupo de nodos existente, habilita manualmente la federación de identidades para cargas de trabajo para GKE en tu grupo de nodos después de habilitar la federación de identidades para cargas de trabajo para GKE en tu clúster.

  2. 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 región o zona de Compute Engine del clúster.

  3. Crea un espacio de nombres para usar en la ServiceAccount de Kubernetes. También puedes usar el espacio de nombres default o cualquier espacio de nombres existente.

    kubectl create namespace NAMESPACE

    Reemplaza NAMESPACE por el nombre del espacio de nombres de Kubernetes para la ServiceAccount de Kubernetes.

  4. 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 KSA_NAME por el nombre de tu ServiceAccount de Kubernetes.

  5. Otorga uno de los roles de IAM para Cloud Storage a la ServiceAccount de Kubernetes. Sigue estos pasos, según si otorgas acceso a la cuenta de servicio de Kubernetes solo a un bucket de Cloud Storage específico o acceso global a todos los buckets del proyecto.

    Acceso a un bucket específico

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

    Acceso global al bucket

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

Configura el acceso para Pods con la red del host

En las versiones de clúster de GKE anteriores a 1.33.3-gke.1226000, el controlador de CSI de Cloud Storage FUSE no admite Pods que se ejecutan en la red del host (hostNetwork: true) debido a las restricciones de Workload Identity Federation for GKE. Sin embargo, para las versiones posteriores de GKE, puedes configurar la autenticación segura para los Pods habilitados para hostNetwork cuando usas el controlador CSI de Cloud Storage FUSE para activar buckets de Cloud Storage. La compatibilidad con la red de host solo está disponible en los clústeres de GKE Standard.

Asegúrate de que tu clúster de GKE cumpla con los siguientes requisitos:

  • Tanto el plano de control como los grupos de nodos de tu clúster de GKE Standard deben tener la versión 1.33.3-gke.1226000 o una posterior.
  • Habilita Workload Identity en tu clúster.
  • Otorga los permisos de IAM necesarios a la cuenta de servicio de Kubernetes que usa tu Pod habilitado para hostNetwork para acceder a tu bucket de Cloud Storage. Para obtener más información, consulta Autentica en Cloud Storage FUSE.

Especifica el atributo de volumen hostNetworkPodKSA: "true" en la definición de tu Pod o PersistentVolume para permitir que tus Pods de HostNetwork accedan a los volúmenes de Cloud Storage. La configuración exacta difiere según cómo administres el contenedor sidecar de Cloud Storage FUSE.

Sidecars administrados

Esta sección se aplica si GKE inserta y administra automáticamente el contenedor sidecar de Cloud Storage FUSE en tus Pods. Esta opción es la configuración predeterminada y recomendada para el controlador de CSI de Cloud Storage FUSE.

Volumen efímero

El siguiente manifiesto de Pod configura un volumen efímero para que un Pod de HostNetwork acceda a un bucket de Cloud Storage.

apiVersion: v1
kind: Pod
metadata:
  name: test-pod
  namespace: ns1
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  serviceAccountName: test-ksa-ns1
  hostNetwork: true
  containers:
  - image: busybox
    name: busybox
    command:
      - sleep
      - "3600"
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: test-bucket
        hostNetworkPodKSA: "true"

Volumen persistente

El siguiente manifiesto de PV configura un PV para que un Pod HostNetwork acceda a un bucket de Cloud Storage.

apiVersion: v1
kind: PersistentVolume
metadata:
name: gcp-cloud-storage-csi-pv
spec:
accessModes:
- ReadWriteMany
capacity:
  storage: 5Gi
persistentVolumeReclaimPolicy: Retain
# storageClassName does not need to refer to an existing StorageClass object.
storageClassName: test-storage-class
mountOptions:
  - uid=1001
  - gid=3003
csi:
  driver: gcsfuse.csi.storage.gke.io
  volumeHandle: test-wi-host-network-2
  volumeAttributes:
    hostNetworkPodKSA: "true"

Vehículos laterales privados

Esta sección se aplica si administras manualmente el contenedor sidecar de Cloud Storage FUSE dentro de tus Pods o si usas una imagen de sidecar personalizada.

Asegúrate de que tu imagen de sidecar se base en la versión v1.17.2 o posterior del controlador CSI de Cloud Storage FUSE.

Volumen efímero

En el siguiente manifiesto de Pod, se configura un volumen efímero para que un Pod de HostNetwork acceda a un bucket de Cloud Storage.

apiVersion: v1
kind: Pod
metadata:
  name: test-pod
  namespace: ns1
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  serviceAccountName: test-ksa-ns1
  hostNetwork: true
  containers:
  - image: busybox
    name: busybox
    command:
      - sleep
      - "3600"
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: test-bucket
        hostNetworkPodKSA: "true"
        identityProvider: "https://container.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME"

En el campo identityProvider, reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación de tu clúster.
  • CLUSTER_NAME: Es el nombre de tu clúster Standard de GKE.

Volumen persistente

En el siguiente manifiesto de PV, se configura un PV para que un Pod de HostNetwork acceda a un bucket de Cloud Storage.

apiVersion: v1
kind: PersistentVolume
metadata:
name: gcp-cloud-storage-csi-pv
spec:
accessModes:
- ReadWriteMany
capacity:
  storage: 5Gi
persistentVolumeReclaimPolicy: Retain
# storageClassName does not need to refer to an existing StorageClass object.
storageClassName: test-storage-class
mountOptions:
  - uid=1001
  - gid=3003
csi:
  driver: gcsfuse.csi.storage.gke.io
  volumeHandle: test-wi-host-network-2
  volumeAttributes:
    hostNetworkPodKSA: "true"
    identityProvider: "https://container.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME"

En el campo identityProvider, reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación de tu clúster.
  • CLUSTER_NAME: Es el nombre de tu clúster Standard de GKE.

¿Qué sigue?