Installer des buckets Cloud Storage en tant que volumes éphémères CSI

Ce guide explique comment utiliser des volumes éphémères CSI sauvegardés par vos buckets Cloud Storage pour gérer automatiquement les ressources de stockage de vos pods Kubernetes ou jobs sur Google Kubernetes Engine (GKE). Les volumes éphémères CSI sont liés au cycle de vie des pods ou des jobs, et vous n'avez pas besoin de gérer manuellement les objets PersistentVolume et PersistentVolumeClaim.

Ce guide est destiné aux administrateurs et opérateurs de plate-forme qui souhaitent simplifier la gestion du stockage de leurs applications GKE.

Avant de lire cette page, assurez-vous de maîtriser les volumes éphémères CSI, les pods et jobs Kubernetes, ainsi que les buckets Cloud Storage.

Si vous connaissez déjà les PersistentVolumes et que vous souhaitez assurer la cohérence avec vos déploiements existants qui reposent sur ce type de ressource, consultez Installer des buckets Cloud Storage en tant que volumes persistants.

Avant de commencer

Assurez-vous d'avoir rempli les conditions préalables suivantes :

Fonctionnement du stockage éphémère CSI pour les buckets Cloud Storage

Les volumes éphémères CSI simplifient la gestion du stockage de vos applications sur GKE. Vous définissez des volumes éphémères CSI directement dans la spécification de votre pod ou job. L'utilisation de volumes éphémères CSI élimine le besoin d'objets PersistentVolume et PersistentVolumeClaim distincts.

L'utilisation d'un volume éphémère CSI implique les opérations suivantes :

  1. Définition du stockage : vous spécifiez le stockage dans le fichier YAML de votre pod ou job, y compris le pilote CSI à utiliser et tous les paramètres requis. Pour le pilote CSI Cloud Storage FUSE, vous spécifiez le nom du bucket et d'autres informations pertinentes.

    Vous pouvez éventuellement affiner les performances de votre pilote CSI à l'aide de la fonctionnalité de mise en cache de fichiers. La mise en cache de fichiers peut améliorer les performances des applications GKE en mettant en cache les fichiers Cloud Storage fréquemment consultés sur un disque plus rapide.

    De plus, vous pouvez utiliser la fonctionnalité de téléchargement parallèle pour accélérer la lecture de fichiers volumineux à partir de Cloud Storage pour les téléchargements multithreads. Vous pouvez utiliser cette fonctionnalité pour améliorer les temps de chargement des modèles, en particulier pour les lectures de plus de 1 Go.

  2. Invocation du pilote : lorsque vous créez le pod ou le job, GKE détecte la requête de volume éphémère et appelle le pilote CSI Cloud Storage FUSE.

  3. Installation et association du volume : le pilote CSI installe le volume éphémère CSI (qui pointe vers le bucket Cloud Storage sous-jacent) et le met à la disposition du pod ou du job, le rendant ainsi accessible à votre application. Pour affiner la façon dont les buckets sont installés dans le système de fichiers, vous pouvez utiliser des options d'installation. Vous pouvez également utiliser des attributs de volume pour configurer un comportement spécifique du pilote CSI Cloud Storage FUSE.

  4. Gestion du cycle de vie : le volume éphémère existe pendant la durée de vie de le pod ou du job. Lorsque le pod est supprimé ou que le job est terminé, le pilote CSI gère automatiquement le nettoyage et le démontage du volume.

Associer le volume éphémère CSI

Suivez ces instructions, selon que vous souhaitez associer le volume éphémère CSI à un pod ou à un job.

Pod

Pour associer le volume éphémère CSI dans un pod, procédez comme suit :

  1. Créez un fichier manifeste YAML de pod avec la spécification suivante :

    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"

    Remplacez les valeurs suivantes :

    L'exemple de fichier manifeste montre les paramètres requis suivants :

    • metadata.annotations : l'annotation gke-gcsfuse/volumes: "true" est obligatoire. Consultez Configurer le conteneur side-car pour obtenir des annotations facultatives.
    • spec.volumes[n].csi.driver: utilisez gcsfuse.csi.storage.gke.io comme nom de pilote CSI.

    Vous pouvez éventuellement ajuster ces variables :

    • spec.terminationGracePeriodSeconds : 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 dispose de 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.volumes[n].csi.volumeAttributes.mountOptions : 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 : transmettez des attributs de volume supplémentaires à Cloud Storage FUSE.
    • spec.volumes[n].csi.readOnly: spécifiez "true" si toutes les installations de volume sont en lecture seule.
    • spec.containers[n].volumeMounts[m].readOnly: spécifiez "true" si une seule installation de volume spécifique est en lecture seule.

  2. Exécutez la commande suivante pour appliquer le fichier manifeste à votre cluster :

    kubectl apply -f FILE_PATH

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

Pod (mise en cache de fichiers)

Pour associer le volume éphémère CSI avec la mise en cache de fichiers dans un pod, 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 en suivant les étapes décrites dans Créer un cluster ou un pool de nœuds avec un stockage éphémère basé sur un disque SSD local.

  2. Créez un fichier manifeste YAML de pod avec la spécification suivante :

    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
        gcloud storage cp /test_files gs://BUCKET_NAME --recursive
  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,file-cache:max-size-mb:-1"

    Remplacez les valeurs suivantes :

    • NAMESPACE : espace de noms Kubernetes dans lequel vous souhaitez déployer votre pod.
    • KSA_NAME : nom du compte de service Kubernetes que vous avez spécifié lors de la configuration de l'accès aux buckets Cloud Storage.

    • BUCKET_NAME : nom du bucket Cloud Storage que vous avez spécifié lors de la configuration de l'accès aux buckets Cloud Storage. 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 Installation dynamique dans la documentation de Cloud Storage FUSE.

      Dans l'exemple de fichier manifeste, 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 enregistre la durée.

  3. Exécutez la commande suivante pour appliquer le fichier manifeste à votre cluster :

    kubectl apply -f FILE_PATH

    Remplacez FILE_PATH par le chemin d'accès à votre 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 doit ressembler à 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 un défaut de cache (miss).

Pod (téléchargement parallèle)

Pour associer le volume éphémère CSI avec le téléchargement parallèle dans un pod, procédez comme suit :

  1. Créez un fichier manifeste YAML de pod avec la spécification suivante :

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-ephemeral 
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/ephemeral-storage-limit: "50Gi" 
spec:
  containers:
  ...
  volumes:
  - name: gcs-fuse-csi-ephemeral 
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs,file-cache:enable-parallel-downloads:true,file-cache:max-size-mb:-1"
        fileCacheCapacity: "-1"

    Remplacez les valeurs suivantes :

    • NAMESPACE : espace de noms Kubernetes dans lequel vous souhaitez déployer votre pod.
    • BUCKET_NAME : nom du bucket Cloud Storage que vous avez spécifié lors de la configuration de l'accès aux buckets Cloud Storage. 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 Installation dynamique dans la documentation de Cloud Storage FUSE.

  2. Exécutez la commande suivante pour appliquer le fichier manifeste à votre cluster :

    kubectl apply -f FILE_PATH

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

Job

Pour associer le volume éphémère CSI dans un job, procédez comme suit :

  1. Créez un fichier manifeste YAML de job avec la spécification suivante :

    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 valeurs suivantes :

    • NAMESPACE : espace de noms Kubernetes dans lequel vous déployez votre pod.
    • KSA_NAME : nom du compte de service Kubernetes que vous avez spécifié lors de la configuration de l'accès aux buckets Cloud Storage.
    • BUCKET_NAME : nom du bucket Cloud Storage que vous avez spécifié lors de la configuration de l'accès aux buckets Cloud Storage. 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 Installation dynamique dans la documentation de Cloud Storage FUSE.

    L'exemple de fichier manifeste montre les paramètres requis suivants :

    • metadata.annotations : l'annotation gke-gcsfuse/volumes: "true" est obligatoire. Consultez Configurer le conteneur side-car pour obtenir des annotations facultatives.
    • spec.volumes[n].csi.driver : utilisez gcsfuse.csi.storage.gke.io comme nom de pilote CSI.

    Vous pouvez éventuellement ajuster ces variables :

    • spec.volumes[n].csi.volumeAttributes.mountOptions : 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 : transmettez des attributs de volume supplémentaires à Cloud Storage FUSE.
    • spec.volumes[n].csi.readOnly : spécifiez "true" si toutes les installations de volume sont en lecture seule.
    • spec.containers[n].volumeMounts[m].readOnly : spécifiez "true" si une seule installation de volume spécifique est en lecture seule.

  2. Exécutez la commande suivante pour appliquer le fichier manifeste à votre cluster :

    kubectl apply -f FILE_PATH

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

Installer le même bucket Cloud Storage avec différents volumes éphémères CSI

Vous pouvez éventuellement utiliser plusieurs volumes éphémères CSI sauvegardés par le même bucket Cloud Storage. Pour ce faire, associez au moins deux volumes qui font référence au même nom de bucket à différents chemins d'installation. Par exemple, vous pouvez installer différents volumes éphémères CSI avec différentes options d'installation sur le même pod, où chaque volume éphémère fait référence au même bucket Cloud Storage. Voici un exemple de fichier manifeste de pod utilisant cette fonctionnalité :

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
        volumeMounts:
        - name: gcs-fuse-csi-ephemeral-with-mo
          mountPath: /data2
      volumes:
      - name: gcs-fuse-csi-ephemeral
        csi:
          driver: gcsfuse.csi.storage.gke.io
          volumeAttributes:
            bucketName: BUCKET_NAME
      - name: gcs-fuse-csi-ephemeral-with-mo
        csi:
          driver: gcsfuse.csi.storage.gke.io
          volumeAttributes:
            bucketName: BUCKET_NAME
            mountOptions: "implicit-dirs"
      restartPolicy: Never
  backoffLimit: 1

Résoudre les problèmes

Pour en savoir plus sur la résolution des problèmes liés au pilote CSI Cloud Storage FUSE, consultez le guide de dépannage dans la documentation du projet GitHub.

Étape suivante