Configura el controlador de 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 de CSI de Cloud Storage FUSE, sigue estos pasos:

• Crea el bucket de Cloud Storage
• Habilita el controlador
• Configura el acceso a tu bucket de Cloud Storage

Crea el bucket de Cloud Storage

Si aún no lo hiciste, crea tus buckets de Cloud Storage. Estos buckets se activarán 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.

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 de CSI del 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)"

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 puedes establecer permisos detallados sobre cómo tus 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 la federación de identidades para cargas de trabajo para 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 cuenta de servicio 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 a la ServiceAccount de Kubernetes acceso solo a un bucket de Cloud Storage específico o acceso global a todos los buckets del proyecto.

   Acceso bucket específicos

   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 los 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 la federación de identidades para cargas de trabajo de GKE. Sin embargo, para versiones posteriores de GKE, puedes configurar la autenticación segura para los Pods habilitados para hostNetwork cuando usas el controlador de CSI de Cloud Storage FUSE para activar buckets 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 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 Cómo autenticarse 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 HostNetwork accedan a los volúmenes de Cloud Storage. La configuración exacta difiere según cómo administres el contenedor de sidecar de Cloud Storage FUSE.

Sidecars administrados

Esta sección se aplica si GKE inserta y administra automáticamente el contenedor de 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.

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"

Sidecars privados

Esta sección se aplica si administras manualmente el contenedor de 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.

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"

¿Qué sigue?

• Soluciona problemas de Cloud Storage FUSE
• Optimiza Cloud Storage FUSE para mejorar el rendimiento
• Aprende a activar buckets de Cloud Storage especificándolos en línea con la especificación del Pod.
• Aprende a activar buckets de Cloud Storage con un recurso de PersistentVolume.
• Obtén más información para configurar aplicaciones para usar Workload Identity Federation for GKE.