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

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

Ce guide s'adresse aux administrateurs et opérateurs de plate-forme qui souhaitent simplifier la gestion du stockage pour leurs applications GKE.

Avant de lire cette page, assurez-vous de connaître les volumes éphémères CSI, les pods et les 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 s'appuient sur ce type de ressource, consultez Monter des buckets Cloud Storage en tant que volumes persistants.

Avant de commencer

Assurez-vous de remplir les conditions préalables suivantes :

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

Les volumes CSI éphémères simplifient la gestion du stockage pour vos applications sur GKE. Vous définissez les volumes éphémères CSI directement dans la spécification de votre pod ou de votre job. L'utilisation de volumes CSI éphémères é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 de votre 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 des 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.

    Vous pouvez également 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 multithread. 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. Appel du pilote : lorsque vous créez le pod ou le job, GKE détecte la demande de volume éphémère et appelle le pilote CSI Cloud Storage FUSE.

  3. Montage et association de volumes : le pilote CSI monte 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 les options de montage. Vous pouvez également utiliser des attributs de volume pour configurer le comportement spécifique du pilote CSI Cloud Storage FUSE.

  4. Gestion du cycle de vie : le volume éphémère existe pendant toute la durée de vie du 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 à 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 :

    • 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 la section 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 la section 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 les variables suivantes :

    • 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 a suffisamment de temps pour vider les données après la fermeture de votre application. Pour en savoir plus, consultez 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 d'autres attributs de volume à 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 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 la section 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 consigne leur 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 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 la section 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 à un job, procédez comme suit :

  1. Créez un fichier manifeste YAML pour le 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 la section 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 la section 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 les variables suivantes :

    • 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 d'autres attributs de volume à 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.

Résoudre les problèmes

Si vous devez résoudre des problèmes liés à Cloud Storage FUSE, vous pouvez définir l'option log-severity sur TRACE. Vous définissez l'indicateur dans la section args de la spécification du conteneur du pilote dans le fichier YAML de déploiement. L'attribut de volume gcsfuseLoggingSeverity est alors automatiquement défini sur "trace".

Pour obtenir d'autres conseils de dépannage, consultez le guide de dépannage dans la documentation du projet GitHub.

Étapes suivantes