Automatiser l'optimisation des performances avec les profils Cloud Storage FUSE

Ce document explique comment régler automatiquement les performances du pilote CSI Cloud Storage FUSE et accélérer l'accès aux données de vos charges de travail d'IA/ML à l'aide des profils Cloud Storage FUSE sur Google Kubernetes Engine (GKE).

Les profils Cloud Storage FUSE automatisent le processus essentiel d'optimisation des performances. Au lieu d'ajuster manuellement les paramètres, vous pouvez appliquer des profils prédéfinis qui configurent le pilote CSI pour vous. Pour vos applications d'IA/de ML, l'utilisation de ces profils peut entraîner des temps d'entraînement et d'inférence plus rapides, avec une réduction des frais généraux opérationnels.

Ce document s'adresse aux développeurs d'applications et aux ingénieurs en machine learning (ML) qui souhaitent améliorer les performances de leurs applications sans avoir besoin d'une expertise approfondie en optimisation du stockage. Pour en savoir plus sur les rôles courants, consultez Rôles utilisateur et tâches courantes de GKE.

Avant de lire ce document, assurez-vous de connaître les bases de Cloud Storage, de Kubernetes et du pilote CSI Cloud Storage FUSE. Consultez également les exigences pour utiliser le pilote CSI Cloud Storage FUSE.

Avantages de l'utilisation des profils Cloud Storage FUSE

Pour automatiser l'optimisation des performances des charges de travail d'IA/ML, les profils Cloud Storage FUSE utilisent des configurations Cloud Storage FUSE prédéfinies et appliquent des paramètres GKE supplémentaires. Ces paramètres sont basés sur les bonnes pratiques pour optimiser les performances de Cloud Storage FUSE. L'utilisation de profils prédéfinis offre les avantages suivants :

  • Réglage des performances simplifié : utilisez des profils Cloud Storage FUSE prédéfinis pour appliquer les configurations optimisées aux charges de travail d'IA/ML courantes, telles que l'entraînement, la diffusion et la création de points de contrôle.
  • Optimisation dynamique et tenant compte des ressources : l'utilisation des profils Cloud Storage FUSE permet au pilote CSI d'ajuster automatiquement la taille du cache et de sélectionner le support de cache optimal, tel que la RAM ou le SSD local, en fonction des caractéristiques du bucket ou du sous-répertoire, telles que la taille, le nombre d'objets et le type d'emplacement, les limites du side-car et les ressources disponibles de votre nœud.
  • Performances de lecture accélérées : lorsque vous utilisez le profil gcsfusecsi-serving, GKE active automatiquement Rapid Cache pour améliorer les performances de lecture de vos charges de travail de diffusion.
  • Insights sur l'optimisation des performances : vous obtenez des informations sur les décisions d'optimisation automatisées grâce à des journaux structurés qui détaillent les signaux d'entrée de votre environnement et les configurations résultantes appliquées par le pilote. Pour en savoir plus, consultez Afficher les insights sur les recommandations.

À mesure que les bonnes pratiques de Cloud Storage FUSE évoluent, les profils sont mis à jour au fil du temps grâce aux nouvelles versions de GKE.

Limites

Conditions requises

Coûts

En plus des coûts standards GKE et Cloud Storage associés au pilote CSI Cloud Storage FUSE, l'utilisation de profils Cloud Storage FUSE entraîne les coûts suivants.

Coûts d'analyse des buckets

Les profils Cloud Storage FUSE effectuent une analyse en arrière-plan de votre bucket ou sous-répertoire. Par défaut, cette analyse a lieu tous les sept jours. L'analyse des buckets entraîne des frais d'opération de classe A Cloud Storage pour la liste des objets.

Coûts de Rapid Cache

Le profil gcsfusecsi-serving active automatiquement le cache rapide, qui est facturé selon la tarification du cache rapide Cloud Storage. Pour éviter d'encourir des frais pour les instances de cache lorsque vous n'en avez plus besoin, consultez Contrôles des coûts.

Avant de commencer

Avant de commencer, effectuez les tâches suivantes :

  • Activez l'API Cloud Storage et l'API Google Kubernetes Engine.
    • Activer les API
  • Si vous souhaitez utiliser Google Cloud CLI pour cette tâche, installez puis initialisez gcloud CLI. Si vous avez déjà installé la gcloud CLI, obtenez la dernière version en exécutant la commande gcloud components update. Il est possible que les versions antérieures de la gcloud CLI ne permettent pas d'exécuter les commandes de ce document.
  • Choisissez une Google Cloud région adaptée à vos besoins. Bien que nous vous recommandions de créer votre cluster GKE et votre bucket Cloud Storage dans la même région pour optimiser les performances et les coûts, il est obligatoire de le faire lorsque vous utilisez le profil gcsfusecsi-serving ou que vous prévoyez d'activer le Rapid Cache.
  • Assurez-vous de disposer d'un bucket Cloud Storage existant contenant l'ensemble de données, le modèle ou les points de contrôle pour votre charge de travail d'IA/ML. Si vous devez créer un bucket, consultez Créer un bucket.

Sélectionnez un profil de performances.

Choisissez un profil qui correspond le mieux à votre charge de travail. Chaque profil correspond à une StorageClass préinstallée sur votre cluster. Pour obtenir des définitions détaillées des profils Cloud Storage FUSE, consultez la documentation de référence sur la configuration de StorageClass correspondante.

Profil Nom de la StorageClass Optimisé pour Principales fonctionnalités
Formation gcsfusecsi-training Lectures à haut débit Optimise la latence des données pour les GPU et les TPU lors de l'entraînement sur de grands ensembles de données.
Points de contrôle gcsfusecsi-checkpointing Écritures à haut débit Minimise le temps nécessaire pour enregistrer les points de contrôle volumineux, ce qui réduit les pauses d'entraînement.
Diffusion gcsfusecsi-serving Accès aux données et mise en cache Active Rapid Cache par défaut pour accélérer les opérations de lecture.

Vous pouvez vérifier les StorageClasses installées dans votre cluster en exécutant la commande suivante :

kubectl get sc -l gke-gcsfuse/profile=true

Configurer les autorisations IAM

Accordez à l'agent de service GKE les autorisations nécessaires pour analyser votre bucket Cloud Storage et gérer le cache rapide.

Remplacez les espaces réservés suivants lorsque vous exécutez les commandes de cette section :

  • GCS_PROJECT : ID du projet contenant votre bucket Cloud Storage.
  • PROJECT_NUMBER : numéro de projet de votre projet de cluster GKE.
  • BUCKET_NAME : nom du bucket Cloud Storage.

Choisissez l'une des options suivantes qui correspond à votre profil et à vos besoins d'utilisation.

Option A : Rôle personnalisé (recommandé)

Cette option est requise pour le profil Serving ou si Rapid Cache est utilisé. Si vous utilisez le profil de diffusion ou prévoyez d'activer manuellement Rapid Cache pour d'autres profils, vous devez accorder les autorisations nécessaires pour gérer ce cache.

  1. Créez un rôle IAM personnalisé qui permet d'analyser des objets et de créer des caches Rapid Cache :

    gcloud iam roles create gke.gcsfuse.profileUser \
  --project=GCS_PROJECT \
  --title="GKE GCSFuse Profile User" \
  --description="Allows scanning Cloud Storage buckets for objects, retrieving bucket metadata, and creating caches." \
  --permissions="storage.objects.list,storage.buckets.get,storage.anywhereCaches.create,storage.anywhereCaches.get,storage.anywhereCaches.list,storage.anywhereCaches.update"

  2. Associez le rôle personnalisé à l'agent de service GKE pour votre bucket spécifique :

    gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
  --project=GCS_PROJECT \
  --member="serviceAccount:service-PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com" \
  --role="projects/GCS_PROJECT/roles/gke.gcsfuse.profileUser"

Option B : Rôle standard pour les profils d'entraînement et de création de points de contrôle

Si vous n'utilisez que les profils "Training" (Entraînement) ou "Checkpointing" (Point de contrôle) et que vous ne prévoyez pas d'utiliser Rapid Cache, exécutez la commande suivante :

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --project=GCS_PROJECT \
    --member="serviceAccount:service-PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com" \
    --role="roles/storage.legacyBucketReader"

Déployer une charge de travail avec un profil Cloud Storage FUSE

Suivez ces étapes pour déployer une charge de travail avec un profil Cloud Storage FUSE.

  1. Créez un manifeste PersistentVolume (PV) qui fait référence à l'une des StorageClasses du profil Cloud Storage FUSE :

    apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: STORAGECLASS_NAME
  mountOptions:
    - only-dir=BUCKET_DIR_PATH # Optional
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME

    Remplacez les éléments suivants :

    • STORAGECLASS_NAME : nom StorageClass du profil que vous souhaitez utiliser. La valeur doit être gcsfusecsi-training, gcsfusecsi-checkpointing ou gcsfusecsi-serving.
    • BUCKET_DIR_PATH : (facultatif) chemin d'accès dans votre bucket Cloud Storage, si vous installez un répertoire spécifique. Si ce chemin est spécifié, GKE l'analyse pour l'optimisation. Si elle est omise, GKE analyse l'intégralité du bucket.
    • BUCKET_NAME : nom du bucket Cloud Storage que vous avez spécifié lors de la configuration de l'accès aux buckets Cloud Storage.

  2. Créez un PersistentVolumeClaim (PVC) qui demande la même StorageClass que votre PV :

    apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
  namespace: NAMESPACE
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  volumeName: my-pv
  storageClassName: STORAGECLASS_NAME

    Remplacez les éléments suivants :

    • NAMESPACE : espace de noms dans lequel vous souhaitez déployer votre pod.
    • STORAGECLASS_NAME : nom de la StorageClass tel qu'il figure dans votre PV.

  3. Utilisez la PVC dans votre déploiement :

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
  namespace: NAMESPACE
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
      annotations:
        gke-gcsfuse/volumes: "true"
    spec:
      serviceAccountName: KSA_NAME
      containers:
      - name: my-container
        image: busybox
        volumeMounts:
        - name: my-gcs-volume
          mountPath: "/data"
      volumes:
      - name: my-gcs-volume
        persistentVolumeClaim:
          claimName: my-pvc

    Remplacez les éléments suivants :

Une fois déployé, le pilote CSI calcule automatiquement les tailles de cache et les options de montage optimales en fonction des ressources de votre nœud, telles que les GPU ou les TPU, la mémoire, le SSD local, la taille du bucket ou du sous-répertoire, et les limites de ressources du side-car.

Vérifier l'optimisation automatisée

Les processus en arrière-plan GKE analysent automatiquement votre bucket et synchronisent le Rapid Cache (le cas échéant).

Vérifier l'état de l'analyse du bucket et du cache

Une fois le PV créé, suivez ces étapes pour vérifier l'état de l'analyse du bucket et du cache. Vous n'avez pas besoin d'attendre que le pod soit déployé.

  1. Vérifiez l'état de la validation :

    kubectl describe pv my-pv

  2. Dans le résultat, vérifiez que l'événement ScanOperationSucceeded apparaît. Le résultat ressemble à ce qui suit :

    Normal  ScanOperationSucceeded  gke-gcsfuse-scanner  Bucket scan completed successfully for bucket "my-bucket", directory "my-dir": "526893" objects, "57690897566" bytes

  3. Si vous utilisez le profil gcsfusecsi-serving, vérifiez que l'événement AnywhereCacheSyncSucceeded s'affiche une fois la couche de mise en cache prête. Le résultat ressemble à ce qui suit :

    Normal  AnywhereCacheSyncSucceeded  gke-gcsfuse-scanner  Anywhere Cache sync succeeded for PV "my-pv": us-central1-c:running

  4. Vérifiez que les annotations PV sont mises à jour avec le résultat de l'analyse :

    gke-gcsfuse/bucket-scan-status: completed
gke-gcsfuse/bucket-scan-num-objects: 526893
gke-gcsfuse/bucket-scan-total-size-bytes: 57690897566
gke-gcsfuse/bucket-scan-location-type: multi-region
gke-gcsfuse/bucket-scan-hns-enabled: true
gke-gcsfuse/bucket-scan-last-updated-time: 2025-12-10T22:48:38Z

Vérifier l'état du pod

Après avoir déployé le pod, exécutez la commande suivante :

kubectl get pods -n NAMESPACE

Remplacez NAMESPACE par l'espace de noms dans lequel vous avez déployé vos pods.

Vos composants devraient maintenant être à l'état RUNNING, avec les bonnes pratiques en termes de performances appliquées automatiquement. Si vos pods affichent l'état SchedulingGated, cela signifie que GKE est toujours en train d'analyser votre bucket ou votre sous-répertoire. Les pods restent dans cet état jusqu'à ce que le contrôleur CSI termine l'analyse et mette à jour le PV.

Pour comprendre les décisions d'ajustement spécifiques consignées par le pilote après le démarrage du pod, consultez Afficher les insights sur les recommandations.

Si vous rencontrez des erreurs, consultez la section Dépannage.

Documentation de référence sur la configuration de StorageClass

Cette section fournit les fichiers manifestes StorageClass pour les profils Cloud Storage FUSE préinstallés, ainsi qu'une référence détaillée pour les options de montage et les paramètres utilisés par les profils. Ces configurations permettent au pilote gcsfuse.csi.storage.gke.io d'automatiser l'optimisation des performances et la gestion des ressources pour vos charges de travail d'IA/de ML.

Formation

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-training
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-training
parameters:
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

Points de contrôle

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-checkpointing
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-checkpointing
  - read_ahead_kb=1024
parameters:
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

Diffusion

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-serving
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-serving
  - read_ahead_kb=131072
  - file-cache:max-size-mb:0
  - read:enable-buffered-read:true
  - read:global-max-blocks:80
parameters:
  anywhereCacheZones: "*"
  anywhereCacheAdmissionPolicy: "admit-on-first-miss"
  anywhereCacheTTL: "1h"
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

Les profils utilisent les options et paramètres de montage suivants pour le pilote gcsfuse.csi.storage.gke.io :

  • mountOptions :
    • profile : applique un ensemble prédéfini d'optimisations Cloud Storage FUSE adaptées aux charges de travail d'IA/ML. Les valeurs valides pour les profils préinstallés sont aiml-training, aiml-checkpointing et aiml-serving.
    • read_ahead_kb : spécifie la taille de la mémoire tampon de lecture anticipée en kilo-octets (Ko). Cette option permet à Cloud Storage FUSE de précharger les données depuis Cloud Storage, ce qui peut améliorer les performances de lecture pour les modèles d'accès séquentiels.
    • file-cache:max-size-mb : pour le profil de diffusion, spécifie la taille maximale en mébioctets (Mio) du cache de fichiers. Dans les charges de travail de diffusion, où les modèles sont généralement chargés dans la mémoire GPU ou TPU une seule fois, ce paramètre est défini sur 0 pour désactiver le cache de fichiers Cloud Storage FUSE local, ce qui permet d'éviter les E/S de disque redondantes et d'économiser de l'espace de stockage local.
    • read:enable-buffered-read : pour le profil de diffusion, permet à Cloud Storage FUSE de gérer ses propres tampons internes, ce qui contribue à réduire le nombre de petits appels système coûteux entre l'application et le noyau.
    • read:global-max-blocks : pour le profil de diffusion, limite le nombre total de blocs de mémoire simultanés utilisés pour les lectures mises en mémoire tampon. Cette option permet d'empêcher le processus FUSE de consommer toute la RAM disponible lors du traitement de plusieurs requêtes.
  • parameters :
    • skipCSIBucketAccessCheck : lorsque la valeur est définie sur "true", le pilote CSI ignore la vérification initiale de l'accès au bucket. Ce paramètre permet de réduire les appels au service de jetons de sécurité pour éviter d'éventuels problèmes de quota.
    • gcsfuseMetadataPrefetchOnMount : lorsqu'il est défini sur "true", il indique au pilote CSI de lancer le prefetching des métadonnées d'objet depuis Cloud Storage dans le cache local dès que le volume est monté. Ce paramètre peut accélérer le premier accès aux fichiers.
    • fuseFileCacheMediumPriority : définit l'ordre de priorité des supports de stockage utilisés par le cache de fichiers Cloud Storage FUSE. Il permet de spécifier différentes préférences pour les nœuds avec GPU, TPU ou nœuds à usage général. Les options de support incluent ram et lssd (SSD local, si disponible et activé).
    • fuseMemoryAllocatableFactor : spécifie, sous forme de chaîne, une fraction qui limite la mémoire maximale que les caches Cloud Storage FUSE peuvent consommer, par rapport à la mémoire totale allouable du nœud et à la limite de mémoire du side-car.
    • fuseEphemeralStorageAllocatableFactor : limite l'utilisation du cache Cloud Storage FUSE pour le stockage éphémère sur le nœud (tel que le SSD local pour la mise en cache des fichiers), par rapport au stockage éphémère allouable du nœud ou au stockage éphémère du side-car limité pour la mise en cache.
    • bucketScanResyncPeriod : définit l'intervalle de temps auquel le PV est réanalysé pour détecter les modifications apportées au bucket Cloud Storage.
    • bucketScanTimeout : durée maximale autorisée pour une opération d'analyse de bucket unique. Si l'analyse dépasse cette durée, des résultats partiels peuvent être utilisés.
    • anywhereCacheZones : spécifie une liste de zones compatibles séparées par une virgule dans lesquelles les caches Rapid Cache sont créés, par exemple "us-central1-a,us-central1-b". Pour utiliser toutes les zones disponibles pour le cluster, utilisez "*" comme valeur. Si vous définissez cette valeur sur "none" ou que vous ne la spécifiez pas, Rapid Cache est désactivé.
    • anywhereCacheTTL : valeur TTL (Time To Live) des données stockées dans le cache rapide, mesurée à partir du dernier accès. Si vous modifiez cette valeur, les instances de cache rapide existantes sont mises à jour avec la nouvelle valeur TTL.
    • anywhereCacheAdmissionPolicy : détermine quand les données doivent être admises dans le cache Rapid Cache après un échec de lecture (lorsque les données demandées ne sont pas trouvées dans le cache). Les options incluent "admit-on-first-miss", qui accepte les données lors du premier échec de lecture, ou "admit-on-second-miss", qui accepte les données uniquement lors du deuxième échec de lecture pour le même objet. Si vous modifiez cette valeur, les instances de cache rapide existantes sont mises à jour avec la nouvelle règle.

Facultatif : Affiner les configurations de profil

Vous pouvez personnaliser des paramètres spécifiques dans un profil tout en bénéficiant de sa configuration de base. Utilisez les options suivantes pour ajuster un profil sans créer de StorageClass.

Remplacer les options et les paramètres de montage

Pour modifier des comportements spécifiques, ajoutez des options de montage au champ spec.mountOptions ou des paramètres CSI au champ spec.csi.volumeAttributes de votre PV. GKE applique vos paramètres manuels en plus des paramètres par défaut du profil.

L'exemple suivant montre comment remplacer l'option de montage read_ahead_kb et désactiver le paramètre gcsfuseMetadataPrefetchOnMount dans le profil de diffusion.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv-override
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: gcsfusecsi-serving
  mountOptions:
  - read_ahead_kb=2048 # Overrides the profile's default.
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: my-gcs-bucket
    volumeAttributes:
      gcsfuseMetadataPrefetchOnMount: "false" # Overrides the profile's default.

Voici quelques cas d'utilisation courants :

  • Pour activer le cache rapide pour un profil d'entraînement, ajoutez le paramètre anywhereCacheZones directement à votre spécification PV.
  • Pour ajuster des comportements spécifiques de Cloud Storage FUSE, comme augmenter la taille de read_ahead_kb, afin de répondre aux exigences uniques d'une charge de travail particulière.

Lorsque vous configurez manuellement les tailles de cache, tenez compte des points suivants :

  • Si vous spécifiez une taille de cache manuelle, la taille dynamique automatique sera remplacée pour ce composant spécifique uniquement. Le dimensionnement dynamique se poursuit pour tous les autres composants au mieux, dans le budget de ressources restant.
  • Définir une option metadata-cache ou file-cache, telle que metadata-cache:stat-cache-max-size-mb, ne désactive pas le calcul automatique pour les autres types de cache.
  • Si vous spécifiez manuellement file-cache:max-size-mb, vous devez également configurer un volume de cache de lecture personnalisé. Cela permet de s'assurer qu'un support de stockage avec une capacité suffisante est explicitement défini pour la taille de votre cache personnalisé.

Ignorer l'analyse des buckets avec des annotations

Vous pouvez contourner le processus d'analyse automatique des buckets en fournissant vos propres métriques sur le nombre et la taille des objets à l'aide d'annotations. Le pilote CSI utilise ces valeurs pour calculer les configurations de performances optimales sans analyser le bucket.

L'exemple suivant montre comment ajouter l'annotation gke-gcsfuse/bucket-scan-status: "override" à votre PV, ainsi que les annotations de métriques spécifiques.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv-override
  annotations:
    gke-gcsfuse/bucket-scan-status: "override"
    gke-gcsfuse/bucket-scan-num-objects: 19238
    gke-gcsfuse/bucket-scan-total-size-bytes: 94837465
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: STORAGECLASS_NAME
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME

Voici quelques cas d'utilisation courants :

  • Si vous connaissez déjà la taille de votre bucket et le nombre d'objets, en particulier pour les charges de travail d'inférence où les données changent rarement, vous pouvez ignorer le temps d'analyse au démarrage.
  • Si l'API Cloud Storage est temporairement indisponible, ces annotations peuvent vous aider à maintenir les performances pendant que les services sous-jacents sont en cours de réparation.

Dépannage

Utilisez les informations suivantes pour surveiller l'état des profils Cloud Storage FUSE et résoudre les problèmes courants rencontrés lors de l'analyse des buckets et de la synchronisation du cache.

Paramètre de configuration non valide (InvalidArgument)

Les tâches d'optimisation en arrière-plan n'ont pas pu démarrer, car un ou plusieurs paramètres fournis dans votre fichier manifeste n'étaient pas valides.

Problème constaté

Le PV affiche un événement ScanOperationStartError ou AnywhereCacheSyncError avec un message contenant rpc error: code = InvalidArgument. Voici quelques exemples :

  • Bucket scan timeout configuration error: rpc error: code = InvalidArgument desc = invalid duration format for "INVALID_DURATION".
  • Anywhere Cache sync failed for PV "PV_NAME": rpc error: code = InvalidArgument desc = failed to get anywhere cache "CACHE_NAME" ... invalid anywhere cache "CACHE_NAME" provided.

Cause

Un ou plusieurs paramètres du champ spec.csi.volumeAttributes de votre PV sont mal formatés ou contiennent des valeurs que le système ne peut pas analyser.

Solution

Corrigez les valeurs de paramètres non valides dans votre fichier manifeste PV, puis redéployez le PV. Assurez-vous que toutes les valeurs de durée (comme bucketScanTimeout) utilisent le format correct (par exemple, 2m ou 10m) et que tous les paramètres spécifiques au profil correspondent aux valeurs valides acceptées.

Autorisation refusée lors de l'analyse du bucket Cloud Storage

GKE ne peut pas accéder au bucket Cloud Storage spécifié pour effectuer l'analyse des performances requise.

Problème constaté

La PV affiche un événement ScanOperationStartError avec un message Error 403: Forbidden indiquant que l'appelant n'a pas accès à storage.buckets.get.

Cause

L'agent de service GKE ne dispose pas des autorisations IAM requises ou le nom du bucket est incorrect.

Solution

  • Vérifiez que le nom du bucket dans le champ volumeHandle de votre PV est correct et que le bucket existe.
  • Assurez-vous que les autorisations de l'agent de service GKE sont accordées à l'identité service-PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com pour le bucket spécifique. Pour en savoir plus, consultez Configurer les autorisations IAM.

L'emplacement de Rapid Cache ne correspond pas

Impossible de créer le cache Rapid Cache, car la zone demandée n'est pas compatible avec l'emplacement du bucket.

Problème constaté

Le PV affiche un événement AnywhereCacheSyncWarning avec le message suivant : Invalid zone. Rapid Cache isn't available in the requested zone.

Cause

Les caches Rapid Cache doivent être créés dans des zones situées dans la région du bucket. Cette erreur se produit généralement lorsque votre cluster GKE et votre bucket Cloud Storage se trouvent dans des régions différentes.

Solution

Déplacez votre bucket Cloud Storage vers une région correspondant à l'emplacement de votre cluster GKE, puis redéployez le PV.

Expiration du délai d'analyse du bucket

L'analyse du bucket Cloud Storage a pris plus de temps que le délai d'attente configuré, ce qui a entraîné des résultats d'optimisation partiels.

Problème constaté

La PV affiche un événement ScanOperationTimedOut. La PV est annotée avec des résultats partiels pour le nombre d'objets et la taille totale.

Cause

Le bucket contient un nombre exceptionnellement élevé d'objets (généralement plusieurs millions) qui ne peuvent pas être entièrement listés dans le délai d'expiration par défaut de deux minutes.

Solution

  • Définissez une valeur plus élevée pour le champ bucketScanTimeout dans la section spec.csi.volumeAttributes de votre PV, par exemple 10m.
  • Si la taille du bucket est statique, contournez l'analyse en fournissant manuellement le nombre et la taille des objets.

Cache de métadonnées limité par le budget de mémoire

Le pilote a limité la taille du cache de métadonnées pour l'adapter aux ressources disponibles du nœud, ce qui peut réduire les performances.

Problème constaté

Les journaux contiennent un message indiquant que la taille du cache de statistiques de métadonnées requise a été limitée au budget de mémoire Cloud Storage FUSE disponible.

Cause

Le cache de métadonnées pour le nombre d'objets dans votre bucket dépasse la mémoire allouée au side-car Cloud Storage FUSE ou la mémoire disponible du nœud.

Solution

  • Utilisez l'option de montage only-dir pour limiter le volume à un sous-répertoire plus petit contenant moins d'objets.
  • Augmentez la limite de mémoire pour le conteneur side-car Cloud Storage FUSE.
    • Si les limites de sidecar sont déjà suffisantes, utilisez un type de nœud avec plus de mémoire allouable.

Cache de fichiers désactivé en raison de limites de ressources

GKE a désactivé le cache de fichiers local, car il n'a pas trouvé de support de stockage adapté avec suffisamment d'espace.

Problème constaté

Les journaux affichent l'avertissement suivant : No suitable file cache medium found or requirement exceeded limits for all options.

Cause

La taille du cache de fichiers calculée dépasse à la fois la RAM et l'espace de stockage SSD local disponibles sur le nœud.

Solution

  • Utilisez l'option de montage only-dir pour limiter le volume à un sous-répertoire plus petit contenant moins d'objets.
  • Augmentez les limites de ressources du side-car Cloud Storage FUSE.
  • Utilisez un type de nœud avec plus de mémoire ou activez les disques SSD locaux sur votre pool de nœuds.

Surveiller l'état à l'aide des événements PersistentVolume

GKE consigne les événements et les erreurs de configuration clés dans le PV. Pour vérifier ces événements, exécutez la commande suivante :

kubectl describe pv PV_NAME

Une fois l'analyse du bucket réussie, un événement ScanOperationSucceeded s'affiche. Si vous utilisez le profil gcsfusecsi-serving, un événement AnywhereCacheSyncSucceeded s'affiche une fois la couche de mise en cache opérationnelle.

Surveiller l'état à l'aide des journaux du pilote CSI

Le pilote CSI Cloud Storage FUSE enregistre des informations détaillées sur les décisions de configuration et les performances. Pour afficher ces journaux dans Cloud Logging, utilisez la requête suivante :

resource.type="k8s_container"
resource.labels.pod_name=~"gcsfusecsi-node-.*"

Afficher les insights sur les recommandations

Pour comprendre les signaux d'entrée spécifiques et les décisions prises par la logique de réglage automatique, recherchez la chaîne GCSFuseCSIRecommendation dans les journaux du pilote CSI. La charge utile JSON obtenue fournit des métriques détaillées, y compris les suivantes :

  • inputSignals : nombre d'objets du bucket, taille totale des données et ressources de nœud disponibles (RAM et stockage éphémère).
  • decision : tailles de cache finales calculées et support de stockage sélectionné (ram ou lssd).
{
  "insertId": "INSERT_ID",
  "jsonPayload": {
    "decision": {
      "fileCacheBytes": 300000000,
      "fileCacheMedium": "lssd",
      "metadataStatCacheBytes": 4500,
    },
    "target": {
      "nodeName": "NODE_NAME",
      "pvName": "PV_NAME",
      "podName": "POD_NAME"
    },
    "message": "GCSFuseCSIRecommendation: Recommended cache configs for PV PV_NAME and Pod POD_NAME: FileCache: 287MiB (lssd) | MetadataStatCache: 1MiB | Expand for full details",
    "inputSignals": {
      "requiredFileCacheBytes": 300000000,
      "fuseBudgetMemoryBytes": 187904819,
      "sidecarLimitMemoryBytes": 268435456,
      "nodeType": "gpu",
      "bucketTotalObjects": 3,
      "nodeAllocatableMemoryBytes": 191291998208,
      "bucketTotalDataSizeBytes": 300000000,
      "bucketLocationType": "multi-region",
      "bucketHNSEnabled": true,
      "sidecarLimitEphemeralStorageBytes": 0,
      "requiredMetadataStatCacheBytes": 4500,
      "nodeAllocatableEphemeralStorageBytes": 1317908854882,
      "nodeHasEphemeralStorageLSSD": true,
      "fuseBudgetEphemeralStorageBytes": 1120222526649
    }
  },
  ...
}

Effectuer un nettoyage

Pour éviter que les ressources créées dans ce guide ne soient facturées sur votre compte Google Cloud , procédez comme suit :

  1. Supprimez le déploiement :

    kubectl delete deployment my-deployment -n NAMESPACE

    Remplacez NAMESPACE par l'espace de noms Kubernetes dans lequel vous avez créé le déploiement.

  2. Supprimez le PersistentVolumeClaim :

    kubectl delete pvc my-pvc -n NAMESPACE

    Remplacez NAMESPACE par l'espace de noms Kubernetes dans lequel vous avez créé le PVC.

  3. Supprimez le PersistentVolume :

    kubectl delete pv my-pv

  4. Si vous avez utilisé le profil gcsfusecsi-serving ou activé manuellement le cache rapide, suivez les instructions pour désactiver un cache afin de ne plus être facturé pour les instances de cache.

Étapes suivantes