Accéder aux buckets Cloud Storage avec le pilote CSI Cloud Storage FUSE

Filesystem in Userspace (FUSE) est une interface utilisée pour exporter un système de fichiers vers le noyau Linux. Cloud Storage FUSE vous permet d'installer des buckets Cloud Storage en tant que système de fichiers afin que les applications puissent accéder aux objets d'un bucket à l'aide d'opérations d'E/S de fichier courantes (par exemple, ouverture, lecture, écriture, fermeture) plutôt que d'utiliser des API spécifiques au cloud.

Le pilote CSI Cloud Storage FUSE vous permet d'utiliser l'API Kubernetes pour utiliser les buckets Cloud Storage préexistants en tant que volumes. Vos applications peuvent importer et télécharger des objets à l'aide de la sémantique du système de fichiers Cloud Storage FUSE. Le pilote CSI Cloud Storage FUSE fournit une expérience entièrement gérée, basée sur le pilote CSI Google Cloud Storage FUSE Open Source.

Le pilote est compatible de manière native avec les méthodes suivantes pour vous permettre de configurer vos volumes reposant sur Cloud Storage :

Vous pouvez utiliser le pilote CSI Cloud Storage FUSE avec la mise en cache de fichiers pour améliorer les performances de lecture des applications qui gèrent de petits fichiers à partir de buckets Cloud Storage. La fonctionnalité de cache de fichiers Cloud Storage FUSE est un cache de lecture basé sur le client qui permet de diffuser plus rapidement des lectures de fichiers répétées à partir du stockage dans le cache de votre choix. Vous pouvez choisir parmi une gamme d'options de stockage pour le cache en lecture, y compris des disques SSD locaux et un stockage basé sur disque persistant, en fonction de vos besoins en termes de rapport prix/performances. Vous devez activer l'activation de la mise en cache des fichiers avec le pilote CSI Cloud Storage FUSE. Pour en savoir plus sur les bonnes pratiques en matière de mise en cache, consultez la page Performances et bonnes pratiques de Cloud Storage FUSE.

Avantages

  • Le pilote CSI Cloud Storage FUSE sur votre cluster active le déploiement et la gestion automatiques du pilote. Le pilote fonctionne à la fois sur les clusters Standard et Autopilot.
  • Le pilote CSI Cloud Storage FUSE n'a pas besoin d'un accès privilégié qui est généralement requis par les clients FUSE. Cela permet un meilleur niveau de sécurité.
  • La compatibilité avec les volumes CSI éphémères simplifie la configuration et la gestion des volumes en éliminant le besoin d'objets PersistentVolumeClaim et PersistentVolume.
  • Le pilote CSI Cloud Storage FUSE est compatible avec les modes d'accès ReadWriteMany, ReadOnlyMany et ReadWriteOnce.
  • Vous pouvez utiliser la fédération d'identité de charge de travail pour GKE pour gérer l'authentification tout en disposant d'un contrôle précis sur la manière dont vos pods accèdent aux objets Cloud Storage.
  • Si vous exécutez des charges de travail d'entraînement et d'inférence de ML avec des frameworks tels que Ray, PyTorch, Spark et TensorFlow, la portabilité et la simplicité fournies par le pilote CSI Cloud Storage FUSE vous permettent d'exécuter vos charges de travail directement sur vos clusters GKE sans modification supplémentaire du code.
  • Vous pouvez lire des objets Cloud Storage avec la mise en cache des fichiers activée pour améliorer les performances de lecture. Pour en savoir plus sur les avantages de la mise en cache de fichiers, reportez-vous à la documentation de Cloud Storage FUSE.
  • Vous pouvez utiliser les volumes Cloud Storage FUSE dans des conteneurs d'initialisation.

Avant de commencer

Avant de commencer, effectuez les tâches suivantes :

  • Activez l'API Google Kubernetes Engine.
    • Activer l'API Google Kubernetes Engine
  • Si vous souhaitez utiliser Google Cloud CLI pour cette tâche, installez puis initialisez gcloud CLI. Si vous avez déjà installé gcloud CLI, assurez-vous de disposer de la dernière version en exécutant la commande gcloud components update.
  • Créez vos buckets Cloud Storage. Pour améliorer les performances, définissez le champ Location type sur Region et sélectionnez une région dans laquelle votre cluster GKE s'exécute.

Limites

Conditions requises

Pour utiliser le pilote CSI Cloud Storage FUSE, vos clusters doivent répondre aux exigences suivantes :

Activer le pilote CSI Cloud Storage FUSE

Pour créer un cluster Standard avec le pilote CSI Cloud Storage FUSE activé, vous pouvez utiliser gcloud CLI :

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

Remplacez les éléments suivants :

  • CLUSTER_NAME : nom du cluster
  • VERSION : numéro de version de GKE. Vous devez sélectionner la version 1.24 ou une version ultérieure.
  • LOCATION : emplacement Compute Engine du cluster.
  • PROJECT_ID : ID de votre projet.

Pour activer le pilote sur un cluster Standard existant, exécutez la commande gcloud container clusters update :

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

Remplacez les éléments suivants :

Après avoir activé le pilote CSI Cloud Storage FUSE, vous pouvez l'utiliser dans les volumes Kubernetes en spécifiant le nom du pilote et de l'approvisionneur : gcsfuse.csi.storage.gke.io.

Configurer l'accès aux buckets Cloud Storage à l'aide de la fédération d'identité de charge de travail pour GKE

Pour rendre vos buckets Cloud Storage accessibles à votre cluster GKE à l'aide de la fédération d'identité de charge de travail pour GKE, procédez comme suit : Pour en savoir plus, consultez la page Configurer des applications pour qu'elles utilisent la fédération d'identité de charge de travail pour GKE.

  1. Obtenez les identifiants de votre cluster :

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

    Remplacez les éléments suivants :

    • CLUSTER_NAME : nom de votre cluster sur lequel la fédération d'identité de charge de travail pour GKE est activée.
    • LOCATION : emplacement Compute Engine du cluster.

  2. Créez un espace de noms à utiliser pour le compte de service Kubernetes. Vous pouvez également utiliser l'espace de noms default ou tout espace de noms existant.

    kubectl create namespace NAMESPACE

    Remplacez les éléments suivants :

    • NAMESPACE : nom de l'espace de noms Kubernetes du compte de service Kubernetes.

  3. Créez un compte de service Kubernetes que votre application pourra utiliser. Vous pouvez également utiliser n'importe quel compte de service Kubernetes existant dans n'importe quel espace de noms, y compris le compte de service Kubernetes default.

    kubectl create serviceaccount KSA_NAME \
    --namespace NAMESPACE

    Remplacez les éléments suivants :

    • KSA_NAME : nom de votre nouveau compte de service Kubernetes.
    • NAMESPACE : nom de l'espace de noms Kubernetes du compte de service Kubernetes.

  4. Attribuez l'un des rôles IAM pour Cloud Storage au compte de service Kubernetes.

    Vous pouvez attribuer le rôle à votre compte de service Kubernetes pour lui permettre d'accéder uniquement à un bucket Cloud Storage spécifique à l'aide de la commande suivante :

    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"

    Remplacez les éléments suivants :

    • BUCKET_NAME : nom de votre bucket Cloud Storage.
    • PROJECT_NUMBER : numéro de projet de votre cluster GKE. Pour trouver votre numéro de projet, consultez Identifier des projets.
    • PROJECT_ID : ID de projet de votre cluster GKE.
    • NAMESPACE : nom de l'espace de noms Kubernetes du compte de service Kubernetes.
    • KSA_NAME : nom de votre nouveau compte de service Kubernetes.
    • ROLE_NAME : rôle IAM à attribuer à votre compte de service Kubernetes.
      • Pour les charges de travail en lecture seule, utilisez le rôle "Lecteur des objets de l'espace de stockage" (roles/storage.objectViewer).
      • Pour les charges de travail en lecture/écriture, utilisez le rôle Utilisateur des objets de l'espace de stockage (roles/storage.objectUser).

    Si vous le souhaitez, vous pouvez attribuer le rôle à votre compte de service Kubernetes pour lui permettre d'accéder à tous vos buckets Cloud Storage du projet à l'aide de la commande suivante :

    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"

    Remplacez les éléments suivants :

    • GCS_PROJECT : ID de projet de vos buckets Cloud Storage.
    • PROJECT_NUMBER : numéro de projet de votre cluster GKE. Pour trouver votre numéro de projet, consultez Identifier des projets.
    • PROJECT_ID : ID de projet de votre cluster GKE.
    • NAMESPACE : nom de l'espace de noms Kubernetes du compte de service Kubernetes.
    • KSA_NAME : nom de votre nouveau compte de service Kubernetes.
    • ROLE_NAME : rôle IAM à attribuer à votre compte de service Kubernetes.
      • Pour les charges de travail en lecture seule, utilisez le rôle "Lecteur des objets de l'espace de stockage" (roles/storage.objectViewer).
      • Pour les charges de travail en lecture/écriture, utilisez le rôle Utilisateur des objets de l'espace de stockage (roles/storage.objectUser).

Préparer l'installation des buckets Cloud Storage FUSE

Cette section explique comment préparer l'installation de buckets Cloud Storage FUSE sur vos clusters.

Spécifier des annotations de pod

Le pilote CSI s'appuie sur les annotations de pod pour déterminer si votre pod utilise des volumes reposant sur Cloud Storage. Si le pilote détecte les annotations nécessaires, il injecte un conteneur side-car appelé gke-gcsfuse-sidecar dans votre pod de charge de travail. Les instances Cloud Storage FUSE s'exécutent dans le conteneur side-car et installent les buckets Cloud Storage pour votre charge de travail.

Pour permettre au pilote CSI d'installer les buckets Cloud Storage, veillez à spécifier l'annotation gke-gcsfuse/volumes: "true" dans la spécification du pod, sous le champ metadata. Si vous souhaitez que vos volumes reposant sur Cloud Storage soient utilisés par d'autres types de charges de travail Kubernetes (par exemple, Job, Déploiement ou StatefulSet), assurez-vous de configurer les annotations sous le champ spec.template.metadata.annotations.

Configurer des ressources pour le conteneur side-car

Par défaut, le conteneur side-car est configuré avec les demandes de ressources suivantes, sans que les limites de ressources soient définies :

  • 250 mCPU
  • 256 Mio de mémoire
  • 5 Gio d'espace de stockage éphémère

Pour écraser ces valeurs, vous pouvez éventuellement spécifier l'annotation gke-gcsfuse/[cpu-limit|memory-limit|ephemeral-storage-limit|cpu-request|memory-request|ephemeral-storage-request] comme illustré dans l'exemple suivant :

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/cpu-limit: "10"
    gke-gcsfuse/memory-limit: 10Gi
    gke-gcsfuse/ephemeral-storage-limit: 1Ti
    gke-gcsfuse/cpu-request: 500m
    gke-gcsfuse/memory-request: 1Gi
    gke-gcsfuse/ephemeral-storage-request: 50Gi

Prenez en compte les éléments suivants lorsque vous déterminez la quantité de ressources à allouer :

  • Si vous ne définissez qu'une seule annotation de demande ou de limite de ressource, GKE applique les mêmes valeurs pour la demande et la limite de ressources.
  • Si votre pod de charge de travail utilise plusieurs volumes Cloud Storage, les ressources de conteneur side-car sont partagées par plusieurs instances Cloud Storage FUSE. Le cas échéant, envisagez d'augmenter l'allocation des ressources pour plusieurs volumes Cloud Storage.
  • Allouez plus de processeurs au conteneur side-car si vos charges de travail nécessitent un débit plus élevé. Une utilisation insuffisante du processeur entraînera une limitation de Cloud Storage FUSE.
  • Si vos charges de travail doivent traiter un grand nombre de fichiers et que la mise en cache des métadonnées de Cloud Storage FUSE est activée, augmentez l'allocation de mémoire du conteneur side-car. La consommation de mémoire de Cloud Storage FUSE pour la mise en cache des métadonnées est proportionnelle au nombre de fichiers, mais pas à leur taille. Une mémoire insuffisante entraîne des erreurs de mémoire saturée Cloud Storage et provoque le plantage de l'application de charge de travail.
  • Pour la mise en cache de fichiers, Cloud Storage FUSE met en cache par défaut les fichiers dans un répertoire temporaire local. Estimez l'espace libre dont votre charge de travail a besoin pour la mise en cache de fichiers, et augmentez votre limite de stockage éphémère en conséquence. Pour en savoir plus, consultez la section Attributs des volumes.
  • Pour les opérations d'écriture, Cloud Storage FUSE préproduit par défaut les fichiers dans un répertoire temporaire local avant leur importation dans le bucket Cloud Storage. Estimez l'espace libre dont votre charge de travail a besoin pour la préproduction lors de l'écriture de fichiers volumineux, et augmentez votre limite de stockage éphémère en conséquence. Pour en savoir plus, consultez la section sémantique lecture/écriture dans la documentation GitHub de Cloud Storage FUSE.
  • Vous pouvez utiliser la valeur "0" pour annuler la définition de limites de ressources ou de requêtes sur des clusters standards. Par exemple, l'annotation gke-gcsfuse/memory-limit: "0" permet de laisser vides la limite de mémoire du conteneur side-car vide avec la requête de mémoire par défaut. Cela s'avère utile lorsque vous ne pouvez pas déterminer la quantité de ressources dont Cloud Storage FUSE a besoin pour vos charges de travail et que vous souhaitez laisser Cloud Storage FUSE utiliser toutes les ressources disponibles sur un nœud. Après avoir calculé les besoins en ressources pour Cloud Storage FUSE en fonction de vos métriques de charge de travail, vous pouvez définir les limites appropriées.

Configurer une image privée pour le conteneur side-car

Cette section explique comment utiliser l'image de conteneur side-car si vous l'hébergez dans un registre de conteneurs privés. Ce scénario peut s'appliquer si vous devez utiliser des clusters privés pour des raisons de sécurité, ou si votre cluster dispose d'un accès limité à l'Internet public. Procédez comme suit pour configurer et utiliser l'image de conteneur side-car privé :

  1. Reportez-vous à cette page pour rechercher une image de conteneur side-car public compatible.

  2. Extrayez-la dans votre environnement local et transférez-la vers votre registre de conteneurs privés.

  3. Dans le fichier manifeste, spécifiez un conteneur nommé gke-gcsfuse-sidecar ne comportant que le champ image. GKE utilise l'image de conteneur side-car spécifiée pour préparer l'injection de conteneur side-car. Voici un exemple :

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  containers:
  - name: gke-gcsfuse-sidecar
    image: PRIVATE_REGISTRY/gcs-fuse-csi-driver-sidecar-mounter:PRIVATE_IMAGE_TAG
  - name: main # your main workload container.

Remplacez les éléments suivants :

  • PRIVATE_REGISTRY : votre registre de conteneurs privés.
  • PRIVATE_IMAGE_TAG : tag de l'image de votre conteneur side-car privé.

Configurer un volume de mémoire tampon d'écriture personnalisé pour le conteneur side-car

Cette section explique comment configurer un volume de mémoire tampon personnalisé pour la mise en mémoire tampon d'écriture de Cloud Storage FUSE. Ce scénario peut s'appliquer si vous devez remplacer le volume par défaut emptyDir pour Cloud Storage FUSE afin de préparer les fichiers dans les opérations d'écriture. Vous pouvez spécifier n'importe quel type de stockage compatible avec GKE, par exemple PersistentVolumeClaim. GKE utilisera le volume spécifié pour la mise en mémoire tampon d'écriture des fichiers. C'est utile si vous devez écrire des fichiers de plus de 10 Gio sur des clusters Autopilot. Pour utiliser le volume de tampon personnalisé, vous devez spécifier une valeur fsGroup non nulle. L'exemple suivant montre comment utiliser une PVC prédéfinie comme volume de mémoire tampon :

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  securityContext:
    fsGroup: FS_GROUP
  containers:
  ...
  volumes:
  - name: gke-gcsfuse-buffer
    persistentVolumeClaim:
      claimName: BUFFER_VOLUME_PVC

Remplacez les éléments suivants :

  • FS_GROUP : ID fsGroup.
  • BUFFER_VOLUME_PVC : nom de la PVC prédéfinie.

Configurer un volume de cache de lecture personnalisé pour le conteneur side-car

Cette section explique comment configurer un volume de cache personnalisé pour la mise en cache en lecture de Cloud Storage FUSE. Ce scénario peut s'appliquer si vous devez remplacer le volume par défaut emptyDir pour Cloud Storage FUSE afin de mettre en cache les fichiers dans les opérations de lecture. Vous pouvez spécifier n'importe quel type de stockage compatible avec GKE, par exemple PersistentVolumeClaim. GKE utilisera le volume spécifié pour la mise en cache des fichiers. C'est utile si vous devez mettre en cache des fichiers de plus de 10 Gio sur des clusters Autopilot. Pour utiliser le volume de cache personnalisé, vous devez spécifier une valeur fsGroup non nulle. L'exemple suivant montre comment utiliser une PVC prédéfinie comme volume de mémoire de mise en cache :

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  securityContext:
    fsGroup: FS_GROUP
  containers:
  ...
  volumes:
  - name: gke-gcsfuse-cache
    persistentVolumeClaim:
      claimName: CACHE_VOLUME_PVC

Remplacez les éléments suivants :

  • FS_GROUP : ID fsGroup.
  • CACHE_VOLUME_PVC : nom de la PVC prédéfinie.

Provisionner votre volume en tant que volume éphémère CSI

Les volumes éphémères CSI sauvegardés par des buckets Cloud Storage sont liés au cycle de vie des pods. Avec cette approche de provisionnement, vous n'avez pas besoin de gérer les objets PersistentVolume et PersistentVolumeClaim associés aux buckets Cloud Storage après l'arrêt du pod.

Utiliser le volume de stockage éphémère CSI dans un pod

  1. Enregistrez le manifeste YAML suivant :

    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"
        gcsfuseLoggingSeverity: warning

    L'exemple précédent montre comment vous pouvez spécifier le bucket Cloud Storage de manière intégrée dans le fichier manifeste du pod. L'exemple comprend les champs suivants :

    • metadata.annotations : l'annotation gke-gcsfuse/volumes: "true" est obligatoire. Consultez la section Configurer des ressources pour le conteneur side-car pour obtenir des annotations facultatives.
    • spec.terminationGracePeriodSeconds : Facultatif. Par défaut, cette valeur est définie sur 30. Si vous devez écrire des fichiers volumineux dans le bucket Cloud Storage, augmentez cette valeur pour vous assurer que Cloud Storage FUSE a suffisamment de temps pour vider les données après la fermeture de votre application. Pour en savoir plus, consultez les Bonnes pratiques Kubernetes : arrêt progressif.
    • spec.serviceAccountName : utilisez le même compte de service Kubernetes que celui utilisé à l'étape Configurer l'accès aux buckets Cloud Storage à l'aide de la fédération d'identité de charge de travail pour GKE.
    • spec.volumes[n].csi.driver : utilisez gcsfuse.csi.storage.gke.io comme nom de pilote CSI.
    • spec.volumes[n].csi.volumeAttributes.bucketName : spécifiez le nom de votre bucket Cloud Storage FUSE. Vous pouvez spécifier un trait de soulignement (_) pour installer tous les buckets auxquels le compte de service Kubernetes peut accéder. Pour en savoir plus, consultez la section Installation dynamique dans la documentation de Cloud Storage FUSE.
    • spec.volumes[n].csi.volumeAttributes.mountOptions : Facultatif. Transmettez des options d'installation à Cloud Storage FUSE. Spécifiez les options en une seule chaîne séparée par des virgules, sans espaces.
    • spec.volumes[n].csi.volumeAttributes : Facultatif. Transmettez d'autres attributs de volume à Cloud Storage FUSE.
    • spec.volumes[n].csi.readOnly : Facultatif. Spécifiez true si toutes les installations de volume sont en lecture seule.
    • spec.containers[n].volumeMounts[m].readOnly : Facultatif. Spécifiez true si une seule installation de volume spécifique est en lecture seule.

  2. Appliquez le fichier manifeste au cluster :

    kubectl apply -f FILE_PATH

    Remplacez FILE_PATH par le chemin d'accès au fichier YAML.

Utiliser le volume de stockage éphémère CSI dans une charge de travail de job

  1. Enregistrez le manifeste YAML suivant :

    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

    Remplacez les éléments suivants :

    Le fichier manifeste déploie un job qui utilise un bucket Cloud Storage FUSE via un volume éphémère CSI.

  2. Appliquez le fichier manifeste au cluster :

    kubectl apply -f FILE_PATH

    Remplacez FILE_PATH par le chemin d'accès au fichier YAML.

Si vous utilisez le pilote CSI dans une charge de travail Job, ou si le pod RestartPolicy est défini sur Never, le conteneur side-car se ferme automatiquement après la fermeture de tous les autres conteneurs de charge de travail.

Pour obtenir des exemples supplémentaires, consultez la section Exemples d'applications dans la documentation du projet GitHub.

Provisionner votre volume à l'aide du provisionnement statique

Le provisionnement statique vous permet de créer un ou plusieurs objets PersistentVolume (PV) contenant les détails du système de stockage sous-jacent. Les pods de vos clusters peuvent ensuite utiliser le stockage via desPersistentVolumeClaims (PVC).

Créer un volume persistant

  1. Enregistrez le manifeste YAML suivant :

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

    L'exemple de fichier manifeste montre comment définir un PersistentVolume pour les buckets Cloud Storage. L'exemple comprend les champs suivants :

    • spec.claimRef.namespace : spécifiez l'espace de noms du PersistentVolumeClaim.
    • spec.claimRef.name : spécifiez le nom du PersistentVolumeClaim.
    • spec.csi.driver : utilisez gcsfuse.csi.storage.gke.io comme nom de pilote CSI.
    • spec.csi.volumeHandle : spécifiez le nom de votre bucket Cloud Storage. Vous pouvez transmettre un trait de soulignement (_) pour installer tous les buckets auxquels le compte de service Kubernetes est configuré pour avoir accès. Pour en savoir plus, consultez la section Installation dynamique dans la documentation de Cloud Storage FUSE.
    • spec.mountOptions : Facultatif. Transmettez des options d'installation à Cloud Storage FUSE.
    • spec.csi.volumeAttributes : Facultatif. Transmettez des attributs de volume à Cloud Storage FUSE.

  2. Appliquez le fichier manifeste au cluster :

    kubectl apply -f FILE_PATH

    Remplacez FILE_PATH par le chemin d'accès au fichier YAML.

Créer un objet PersistentVolumeClaim

  1. Enregistrez le manifeste YAML suivant :

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

    L'exemple de fichier manifeste montre comment définir un PersistentVolumeClaim pour lier le PersistentVolume. L'exemple comprend les champs suivants :

    • metadata.namespace : spécifiez l'espace de noms de PersistentVolumeClaim qui doit être cohérent avec celui de votre charge de travail.
    • spec.volumeName : spécifiez le nom du PersistentVolume.

    Pour lier un PersistentVolume à un PersistentVolumeClaim, assurez-vous de suivre ces instructions :

    • Les champs spec.storageClassName des fichiers manifestes de PV et PVC doivent correspondre. Le storageClassName n'a pas besoin de faire référence à un objet StorageClass existant. Pour lier la revendication à un volume, vous pouvez utiliser le nom de votre choix. Toutefois, il ne peut pas être vide.
    • Les champs spec.accessModes des fichiers manifestes de PV et PVC doivent correspondre.
    • spec.capacity.storage sur le fichier manifeste de PersistentVolume doit correspondre à spec.resources.requests.storage sur le fichier manifeste de PersistentVolumeClaim. Étant donné que les buckets Cloud Storage n'ont pas de limite de taille, vous pouvez placer n'importe quel nombre pour la capacité. Toutefois, il ne peut pas être vide.

  2. Appliquez le fichier manifeste au cluster :

    kubectl apply -f FILE_PATH

    Remplacez FILE_PATH par le chemin d'accès au fichier YAML.

Utiliser le volume à partir d'un PersistentVolumeClaim

  1. Enregistrez le manifeste YAML suivant :

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

    L'exemple montre comment définir un pod qui utilise un bucket Cloud Storage FUSE via un PersistentVolumeClaim. L'exemple comprend les champs suivants :

  2. Appliquez le fichier manifeste au cluster :

    kubectl apply -f FILE_PATH

    Remplacez FILE_PATH par le chemin d'accès au fichier YAML.

Pour obtenir des exemples supplémentaires, consultez la section Exemples d'applications dans la documentation du projet GitHub.

Utiliser vos volumes avec la mise en cache de fichiers activée

Par défaut, la fonctionnalité de mise en cache des fichiers est désactivée sur GKE. Pour activer et contrôler la mise en cache des fichiers, utilisez l'attribut de volume fileCacheCapacity.

GKE utilise un volume emptyDir pour la mise en cache des fichiers Cloud Storage FUSE sauvegardé par le disque de démarrage de la VM de nœud. Si vous activez le disque SSD local sur le nœud, GKE utilise le disque SSD local pour sauvegarder le volume emptyDir.

Vous pouvez configurer un volume de cache de lecture personnalisé pour le conteneur side-car afin de remplacer le volume emptyDir par défaut pour la mise en cache de fichiers dans les opérations de lecture. Pour les familles de VM de processeur et de GPU compatibles avec les disques SSD locaux, nous vous recommandons d'utiliser le stockage SSD local. Pour les familles de TPU ou Autopilot, nous vous recommandons d'utiliser un disque persistant avec équilibrage ou un disque persistant SSD.

Utiliser un volume de stockage éphémère CSI avec la mise en cache de fichiers activée

Pour déployer un pod qui utilise un bucket Cloud Storage FUSE via un volume éphémère CSI avec mise en cache de fichiers, procédez comme suit :

  1. Créez un cluster ou un pool de nœuds avec un stockage éphémère basé sur un disque SSD local.

    Suivez la documentation GKE pour créer un cluster ou un pool de nœuds doté d'un espace de stockage éphémère basé sur SSD local.

  2. Enregistrez le manifeste YAML suivant :

    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
        gsutil -m cp -r /test_files gs://BUCKET_NAME
  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"
        fileCacheCapacity: "10Gi"

    Remplacez les éléments suivants :

    Le conteneur d'initialisation data-loader génère 1 000 fichiers d'une taille de 64 Kio et les importe dans un bucket Cloud Storage. Le conteneur principal data-validator lit tous les fichiers du bucket deux fois et consigne leur durée.

  3. Appliquez le fichier manifeste au cluster :

    kubectl apply -f FILE_PATH

    Remplacez FILE_PATH par le chemin d'accès au fichier YAML.

  4. Pour afficher les sorties du journal, exécutez la commande suivante :

    kubectl logs -n NAMESPACE gcs-fuse-csi-file-cache-example -c data-validator

    Remplacez NAMESPACE par l'espace de noms de votre charge de travail.

    Le résultat ressemble à ce qui suit :

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

    Le résultat montre que la deuxième lecture avec le cache local est beaucoup plus rapide que la première lecture avec le défaut de cache.

Configurer le mode d'installation des buckets Cloud Storage FUSE

Cette section explique comment configurer les volumes Cloud Storage FUSE.

Options d'installation

Le pilote CSI Cloud Storage FUSE est compatible avec les options d'installation pour configurer le mode d'installation des buckets Cloud Storage sur votre système de fichiers local. Pour obtenir la liste complète des options d'installation compatibles, consultez la documentation de la CLI gcsfuse.

Vous pouvez spécifier les options d'installation comme suit :

  • Dans le champ spec.mountOptions d'un fichier manifeste PersistentVolume, si vous utilisez le provisionnement statique.
  • Dans le champ spec.volumes[n].csi.volumeAttributes.mountOptions, si vous utilisez des volumes éphémères CSI.

Attributs de volume

Le pilote CSI Cloud Storage FUSE ne vous permet pas de spécifier directement le fichier de configuration Cloud Storage FUSE. Vous pouvez configurer certains des champs du fichier de configuration à l'aide des attributs de volume suivants. Les valeurs sont traduites en champs du fichier de configuration.

  • gcsfuseLoggingSeverity

    • Description : correspond à la gravité des journaux que Cloud Storage FUSE doit générer, exprimée sous forme d'énumération. Si vous utilisez déjà les options d'installation debug_fuse, debug_fs ou debug_gcs, cette nouvelle configuration sera automatiquement définie sur trace. Cet attribut de volume est traduit par le champ du fichier de configuration logging:severity.

    • Valeurs valides (classées de la gravité la moins grave à la plus grave) :

      • trace
      • debug
      • info
      • warning
      • error

    • Valeur par défaut : info

  • fileCacheCapacity

    • Description : taille maximale que le cache de fichiers peut utiliser. Si une valeur non nulle est présente, cet attribut de volume active la mise en cache des fichiers dans Cloud Storage FUSE. Cet attribut de volume est traduit par le champ du fichier de configuration file-cache:max-size-mb.

    • Valeurs valides :

      • Les valeurs de quantité, par exemple : 500Mi, 10Gi.
      • "-1" : pour utiliser toute la capacité disponible du volume de cache.
      • "0" : le cache de fichiers est désactivé.

    • Valeur par défaut : "0".

  • fileCacheForRangeRead

    • Description : indique si l'objet complet doit être téléchargé de manière asynchrone et stocké dans le répertoire de cache Cloud Storage FUSE lorsque la première lecture est effectuée à partir d'un décalage différent de zéro. Ce champ doit être défini sur "true" si vous prévoyez d'effectuer plusieurs lectures aléatoires ou partielles. Cet attribut de volume est traduit par le champ du fichier de configuration file-cache:cache-file-for-range-read.

    • Valeurs valides :

      • Valeurs booléennes au format de chaîne : "true", "false".

    • Valeur par défaut : "false".

  • metadataStatCacheCapacity

    • Description : taille maximale que le cache de statistiques peut utiliser. Le cache de statistiques est toujours entièrement conservé en mémoire. Si vous utilisez déjà l'option d'installation stat-cache-capacity, la valeur sera toujours respectée et sera correctement traduite dans cette nouvelle configuration. Cet attribut de volume est traduit par le champ du fichier de configuration metadata-cache:stat-cache-max-size-mb.

    • Valeurs valides :

      • Les valeurs de quantité, par exemple : 500Mi, 1Gi.
      • "-1" : permet au cache de statistiques d'utiliser autant de mémoire que nécessaire.
      • "0" : le cache de statistiques est désactivé.
      • Utilisez la valeur par défaut de 32Mi si votre charge de travail implique jusqu'à 20 000 fichiers. Si votre charge de travail dépasse 20 000 fichiers, augmentez la taille avec des valeurs de 10 Mio pour 6 000 fichiers supplémentaires, soit une moyenne d'environ 1 500 octets par fichier.

    • Valeur par défaut : 32Mi

  • metadataTypeCacheCapacity

    • Description : taille maximale par répertoire que le cache de type peut utiliser. Le cache de types est toujours entièrement conservé en mémoire. Cet attribut de volume est traduit par le champ du fichier de configuration metadata-cache:type-cache-max-size-mb.

    • Valeurs valides :

      • Les valeurs de quantité, par exemple : 500Mi, 1Gi.
      • "-1" : permet au cache de type d'utiliser autant de mémoire que nécessaire.
      • "0" : le cache du type est désactivé.
      • Utilisez la valeur par défaut 4Mi si le nombre maximal de fichiers dans un seul répertoire à partir du bucket que vous installez contient 20 000 fichiers ou moins. Si le nombre maximal de fichiers dans un même répertoire que vous installez contient plus de 20 000 fichiers, augmentez la valeur de pour 5 000 fichiers, soit une moyenne d'environ 200 octets par fichier.

    • Valeur par défaut : 4Mi

  • metadataCacheTtlSeconds

    • Description : définit la valeur TTL (Time To Live), en secondes, des entrées de métadonnées mises en cache. Si vous utilisez déjà les options d'installation stat-cache-ttl ou type-cache-ttl, les valeurs seront toujours acceptées et seront correctement traduites dans cette nouvelle configuration. Cet attribut de volume est traduit par le champ du fichier de configuration metadata-cache:ttl-secs.

    • Valeurs valides :

      • Valeurs entières au format chaîne, par exemple : "600".
      • "-1" : contourne le délai d'expiration de la valeur TTL et diffuse le fichier à partir du cache chaque fois qu'il est disponible.
      • "0" : vérifie que le fichier le plus récent est lu. L'utilisation d'une valeur 0 émet un appel de métadonnées Get pour s'assurer que la génération d'objets pour le fichier dans le cache correspond à ce qui est stocké dans Cloud Storage.

    • Valeur par défaut : "60".

Vous pouvez spécifier les attributs du volume des manières suivantes :

  • Dans le champ spec.csi.volumeAttributes d'un fichier manifeste PersistentVolume, si vous utilisez le provisionnement statique.
  • Dans le champ spec.volumes[n].csi.volumeAttributes, si vous utilisez des volumes éphémères CSI.

Remarques

Tenez compte des points suivants lorsque vous configurez des installations :

  • Les options suivantes ne sont pas autorisées : app-name, temp-dir, foreground, log-file, log-format, key-file, token-url et reuse-token-from-url.
  • Cloud Storage FUSE ne rend pas les répertoires implicites visibles par défaut. Pour rendre ces répertoires visibles, vous pouvez activer l'option d'installation implicit-dirs. Pour en savoir plus, consultez la section Fichiers et répertoires dans la documentation GitHub de Cloud Storage FUSE.
  • Si vous utilisez un Contexte de sécurité pour votre pod ou votre conteneur, ou si votre image de conteneur utilise un utilisateur ou un groupe non racine, vous devez définir les options d'installation uid et gid. Vous devez également utiliser les options d'installation file-mode et dir-mode pour définir les autorisations du système de fichiers. Notez que vous ne pouvez pas exécuter les commandes chmod ,chown ou chgrp sur un système de fichiers Cloud Storage FUSE. Ainsi, les options d'installation uid ,gid ,file-mode etdir-mode sont nécessaires pour fournir un accès à un utilisateur ou à un groupe non racine.
  • Si vous souhaitez installer un répertoire uniquement dans le bucket plutôt que dans l'ensemble du bucket, transmettez le chemin d'accès relatif au répertoire à l'aide de l'option only-dir=relative/path/to/the/bucket/root.
  • Pour ajuster le comportement de la mise en cache de Cloud Storage FUSE, configurez des attributs de volume. Pour en savoir plus, consultez la documentation sur la mise en cache Cloud Storage FUSE.
  • Si le nombre de cœurs ou de threads est supérieur à 100, remplacez max-conns-per-host par cette valeur.
  • Si vous devez configurer les options d'installation du noyau Linux, vous pouvez les transmettre via l'option o. Par exemple, si vous ne souhaitez pas autoriser l'exécution directe de binaires sur le système de fichiers installé, définissez l'option o=noexec. Chaque option nécessite une option distincte, par exemple o=noexec,o=noatime. Seules les options suivantes sont autorisées : exec, noexec, atime, noatime, sync, async et dirsync.
  • Si vous devez résoudre des problèmes liés à Cloud Storage FUSE, définissez les options debug_fuse, debug_fs et debug_gcs. Si l'une des trois options est spécifiée, l'attribut de volume gcsfuseLoggingSeverity est automatiquement défini sur trace.
  • Le pilote CSI Cloud Storage FUSE ne vous permet pas de modifier le champ cache-dir dans le fichier de configuration Cloud Storage FUSE. Utilisez l'attribut de volume fileCacheCapacity pour activer ou désactiver le mise en cache de fichiers. Pour remplacer le volume emptyDir par défaut pour la mise en cache des fichiers, vous pouvez configurer un volume de cache personnalisé pour le conteneur side-car.

Désactiver le pilote CSI Cloud Storage FUSE

Vous ne pouvez pas désactiver le pilote CSI Cloud Storage FUSE sur des clusters Autopilot.

Vous pouvez désactiver le pilote CSI Cloud Storage FUSE sur un cluster Standard existant à l'aide de Google Cloud CLI.

gcloud container clusters update CLUSTER_NAME \
    --update-addons GcsFuseCsiDriver=DISABLED

Remplacez CLUSTER_NAME par le nom de votre cluster.

Dépannage

Pour résoudre les problèmes liés à l'utilisation du pilote CSI Cloud Storage FUSE, consultez le guide de dépannage dans la documentation du projet GitHub.

Étapes suivantes