Configurar el controlador CSI de Cloud Storage FUSE para GKE

En esta página se describe cómo configurar y preparar el controlador CSI de Cloud Storage FUSE para GKE.

Para usar el controlador CSI de Cloud Storage FUSE, sigue estos pasos:

• Crea el segmento de Cloud Storage.
• Habilita el controlador.
• Configurar el acceso a un segmento de Cloud Storage

Crear el segmento de Cloud Storage

Si aún no lo has hecho, crea tus cubos de Cloud Storage. Montarás estos contenedores como volúmenes en tu clúster de GKE. Para mejorar el rendimiento, defina el Tipo de ubicación como Región y seleccione una región que coincida con su clúster de GKE.

Habilitar el controlador de CSI de Cloud Storage FUSE

Sigue estos pasos, en función de si usas clústeres Autopilot o Estándar de GKE. Te recomendamos que uses un clúster de Autopilot para disfrutar de una experiencia de Kubernetes totalmente gestionada. Para elegir el modo que mejor se adapte a tus cargas de trabajo, consulta Elegir un modo de funcionamiento de GKE.

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

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

Para verificar que el controlador CSI de FUSE de Cloud Storage 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)"

Configurar el acceso a segmentos de Cloud Storage

El controlador CSI de Cloud Storage FUSE usa Workload Identity Federation for GKE para que puedas definir permisos detallados sobre cómo pueden acceder tus pods de GKE a los datos almacenados en Cloud Storage.

Para que tu clúster de GKE pueda acceder a tus segmentos de Cloud Storage, autentícate mediante Workload Identity Federation for GKE con el segmento de Cloud Storage que quieras montar en la especificación de tu pod:

1. Si no tienes habilitada la federación de identidades de carga de trabajo para GKE, sigue estos pasos para habilitarla. Si quieres usar un grupo de nodos que ya tengas, habilita manualmente Workload Identity Federation for GKE en el grupo de nodos después de habilitar Workload Identity Federation for GKE en el clúster.

2. Obtén las credenciales de tu clúster:

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

   Haz los cambios siguientes:

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

3. Crea un espacio de nombres para usarlo con la cuenta de servicio de Kubernetes. También puedes usar el espacio de nombres default o cualquier otro espacio de nombres.

   kubectl create namespace NAMESPACE
   

   Sustituye NAMESPACE por el nombre del espacio de nombres de Kubernetes de la cuenta de servicio de Kubernetes.

4. Crea una cuenta de servicio de Kubernetes para que la use tu aplicación. También puedes usar cualquier cuenta de servicio de Kubernetes que ya tengas en cualquier espacio de nombres, incluida la cuenta de servicio de Kubernetes default.

   kubectl create serviceaccount KSA_NAME \
       --namespace NAMESPACE
   

   Sustituye KSA_NAME por el nombre de tu Kubernetes ServiceAccount.

5. Concede uno de los roles de gestión de identidades y accesos de Cloud Storage a la cuenta de servicio de Kubernetes. Sigue estos pasos, en función de si vas a conceder acceso a la cuenta de servicio de Kubernetes a un segmento de Cloud Storage específico o acceso global a todos los segmentos del proyecto.

   Acceso a un segmento 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"
   

   Haz los cambios siguientes:

   • BUCKET_NAME: el nombre de tu segmento de Cloud Storage.
   • PROJECT_NUMBER: el número de proyecto numérico de tu clúster de GKE. Para encontrar el número de tu proyecto, consulta el artículo sobre cómo identificar proyectos.
   • PROJECT_ID: el ID de proyecto de tu clúster de GKE.
   • NAMESPACE: el nombre del espacio de nombres de Kubernetes de la cuenta de servicio de Kubernetes.
   • KSA_NAME: el nombre de tu nueva cuenta de servicio de Kubernetes.
   • ROLE_NAME: el rol de gestión de identidades y accesos que se asignará a tu cuenta de servicio de Kubernetes.
     • Para las cargas de trabajo de solo lectura, usa el rol Visor de objetos de Storage (roles/storage.objectViewer).
     • Para las cargas de trabajo de lectura y escritura, usa el rol Usuario de objetos de Storage (roles/storage.objectUser).

   Acceso global a segmentos

   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"
   

   Haz los cambios siguientes:

   • GCS_PROJECT: el ID de proyecto de tus segmentos de Cloud Storage.
   • PROJECT_NUMBER: el número de proyecto numérico de tu clúster de GKE. Para encontrar el número de tu proyecto, consulta el artículo sobre cómo identificar proyectos.
   • PROJECT_ID: el ID de proyecto de tu clúster de GKE.
   • NAMESPACE: el nombre del espacio de nombres de Kubernetes de la cuenta de servicio de Kubernetes.
   • KSA_NAME: el nombre de tu nueva cuenta de servicio de Kubernetes.
   • ROLE_NAME: el rol de gestión de identidades y accesos que se asignará a tu cuenta de servicio de Kubernetes.
     • Para las cargas de trabajo de solo lectura, usa el rol Visor de objetos de Storage (roles/storage.objectViewer).
     • Para las cargas de trabajo de lectura y escritura, usa el rol Usuario de objetos de Storage (roles/storage.objectUser).

Configurar 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 CSI de Cloud Storage FUSE no admite pods que se ejecuten en la red del host (hostNetwork: true) debido a las restricciones de Workload Identity Federation para GKE. Sin embargo, en versiones posteriores de GKE, puedes configurar la autenticación segura para los pods con hostNetwork habilitado cuando usas el controlador CSI de FUSE de Cloud Storage para montar segmentos de Cloud Storage. La compatibilidad con redes de host solo está disponible en clústeres de GKE Standard.

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

• Tanto el plano de control como los grupos de nodos de tu clúster de GKE estándar deben tener la versión 1.33.3-gke.1226000 o una posterior.
• Habilita Workload Identity en tu clúster.
• Concede los permisos de gestión de identidades y accesos necesarios a la cuenta de servicio de Kubernetes que usa tu pod habilitado para hostNetwork para acceder a tu segmento de Cloud Storage. Para obtener más información, consulta Autenticarse en Cloud Storage FUSE.

Para permitir que tus pods HostNetwork accedan a los volúmenes de Cloud Storage, debes especificar el atributo de volumen hostNetworkPodKSA: "true" en la definición de tu pod o PersistentVolume. La configuración exacta varía en función de cómo gestione el contenedor sidecar de Cloud Storage FUSE.

Sidecars gestionados

Esta sección se aplica si GKE inserta y gestiona 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 CSI de FUSE 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"

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"

Sidecares privados

Esta sección se aplica si gestionas manualmente el contenedor sidecar de Cloud Storage FUSE en tus pods o si usas una imagen sidecar personalizada.

Asegúrate de que tu imagen de sidecar se base en la versión 1.17.2 o posterior del controlador CSI de FUSE 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"

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"

Siguientes pasos

• Solucionar problemas de Cloud Storage FUSE
• Optimizar Cloud Storage FUSE para mejorar el rendimiento
• Consulta cómo montar segmentos de Cloud Storage especificando tus segmentos en línea con la especificación de Pod.
• Consulta cómo montar grupos de Cloud Storage mediante un recurso PersistentVolume.
• Más información sobre cómo configurar aplicaciones para usar Workload Identity Federation for GKE