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

Ce guide explique comment utiliser des volumes éphémères CSI basés sur 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 éphémères CSI sont liés au cycle de vie du pod ou de la tâche, 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 de l'espace de stockage de 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 reposent 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 éphémères CSI 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 é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 de l'espace de stockage: vous spécifiez l'espace de stockage dans le fichier YAML de votre pod ou de votre tâche, y compris le pilote CSI à utiliser et les paramètres requis. Pour le pilote CSI Cloud Storage FUSE, vous devez spécifier 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 du modèle, en particulier pour les lectures de plus de 1 Go.

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

  3. Installation et association de volumes: 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, ce qui le rend 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 toute la durée de vie du pod ou de la tâche. Lorsque le pod est supprimé ou que la tâche est terminée, 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 à une tâche.

Pod

Pour joindre 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 :

    • 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 présente les paramètres obligatoires 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 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 seule l'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 SSD local en suivant la procédure décrite dans Créer un cluster ou un pool de nœuds avec un stockage éphémère basé sur 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 chargeur de données du conteneur d'initialisation 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 joindre 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 joindre le volume éphémère CSI dans une tâche, procédez comme suit:

  1. Créez un fichier manifeste YAML de tâche avec les spécifications suivantes:

    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 présente les paramètres obligatoires 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 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 seule l'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 de conteneur du pilote dans le fichier YAML de déploiement. L'attribut de volume gcsfuseLoggingSeverity est alors automatiquement défini sur "trace".

Pour obtenir des conseils de dépannage supplémentaires, consultez le guide de dépannage dans la documentation du projet GitHub.

Étape suivante