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 :
Volumes éphémères CSI : vous spécifiez le bucket Cloud Storage conformément à la spécification du pod. Pour en savoir plus sur ce type de volume, consultez la présentation des volumes éphémères CSI dans la documentation Open Source de Kubernetes.
Provisionnement statique : vous créez une ressource PersistentVolume qui fait référence au bucket Cloud Storage. Votre pod peut alors référencer un objet PersistentVolumeClaim lié à cet objet PersistentVolume. Pour en savoir plus sur ce workflow, consultez la page Configurer un pod de façon à utiliser un PersistentVolume pour 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
etReadWriteOnce
. - 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
surRegion
et sélectionnez une région dans laquelle votre cluster GKE s'exécute.
Limites
- Le système de fichiers Cloud Storage FUSE présente des différences en termes de performances, de disponibilité, d'autorisation d'accès et de sémantique par rapport à un système de fichiers POSIX.
- Le pilote CSI Cloud Storage FUSE n'est pas compatible avec GKE Sandbox.
- Le pilote CSI Cloud Storage FUSE n'est pas compatible avec les instantanés de volume, le clonage de volume ou les extensions de volume.
- Consultez les problèmes connus dans le projet GitHub du pilote CSI Cloud Storage FUSE.
- Consultez les problèmes en cours dans le projet GitHub du pilote CSI Cloud Storage FUSE. Les problèmes sont en cours d'analyse et seront résolus dans les prochaines mises à jour.
Conditions requises
Pour utiliser le pilote CSI Cloud Storage FUSE, vos clusters doivent répondre aux exigences suivantes :
- Utilisez des clusters Linux exécutant la version 1.24 ou une version ultérieure de GKE.
- La fédération d'identité de charge de travail pour GKE doit être activée.
- Le serveur de métadonnées GKE doit être activé sur votre pool de nœuds.
- Assurez-vous d'avoir installé la dernière version de Google Cloud CLI.
- Pour utiliser l'image privée pour la fonctionnalité de conteneur side-car, la fonctionnalité de volume de mémoire tampon d'écriture personnalisé ou la configuration des demandes de ressources de conteneur side-car, assurez-vous que votre cluster utilise les versions suivantes de GKE : 1.25.16-gke.1360000, 1.26.13-gke.1052000, 1.27.10-gke.1055000, 1.28.6-gke.1369000, 1.29.1-gke.1575000, ou une version ultérieure.
- Pour utiliser la fonctionnalité de cache de fichiers ou les attributs de volume, assurez-vous que votre cluster utilise les versions suivantes de GKE : 1.25.16-gke.1759000, 1.26.15-gke.1158000, 1.27.12-gke.1190000, 1.28.8-gke.1175000, 1.29.3-gke.1093000 ou ultérieure.
- Pour utiliser des volumes Cloud Storage FUSE dans des conteneurs d'initialisation, assurez-vous que votre cluster utilise GKE version 1.29.3-gke.1093000 ou ultérieure et que tous les nœuds de votre cluster utilisent GKE version 1.29 ou ultérieure.
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 clusterVERSION
: 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 :
CLUSTER_NAME
: nom du clusterLOCATION
: emplacement Compute Engine du cluster.
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.
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.
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.
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.
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
).
- Pour les charges de travail en lecture seule, utilisez le rôle "Lecteur des objets de l'espace de stockage" (
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
).
- Pour les charges de travail en lecture seule, utilisez le rôle "Lecteur des objets de l'espace de stockage" (
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'annotationgke-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é :
Reportez-vous à cette page pour rechercher une image de conteneur side-car public compatible.
Extrayez-la dans votre environnement local et transférez-la vers votre registre de conteneurs privés.
Dans le fichier manifeste, spécifiez un conteneur nommé
gke-gcsfuse-sidecar
ne comportant que le champimage
. 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
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'annotationgke-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
: utilisezgcsfuse.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écifieztrue
si toutes les installations de volume sont en lecture seule.spec.containers[n].volumeMounts[m].readOnly
: Facultatif. Spécifieztrue
si une seule installation de volume spécifique est en lecture seule.
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
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 :
NAMESPACE
: espace de noms de votre charge de travail.KSA_NAME
: nom du compte de service Kubernetes, identique à celui défini à 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.BUCKET_NAME
: nom de votre bucket Cloud Storage.
Le fichier manifeste déploie un job qui utilise un bucket Cloud Storage FUSE via un volume éphémère CSI.
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
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
: utilisezgcsfuse.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.
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
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. LestorageClassName
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.
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
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 :
metadata.annotations
: l'annotationgke-gcsfuse/volumes: "true"
est obligatoire. Consultez la section Configurer des ressources pour le conteneur side-car pour obtenir des annotations facultatives.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.containers[n].volumeMounts[m].readOnly
: facultatif. Spécifieztrue
si seule l'installation de volume spécifique est en lecture seule.spec.volumes[n].persistentVolumeClaim.readOnly
: Facultatif. Spécifieztrue
si toutes les installations de volume sont en lecture seule.
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 :
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.
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 :
NAMESPACE
: espace de noms de votre charge de travail.KSA_NAME
: nom du compte de service Kubernetes indiqué à 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.BUCKET_NAME
: nom de votre bucket Cloud Storage.
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 principaldata-validator
lit tous les fichiers du bucket deux fois et consigne leur durée.Appliquez le fichier manifeste au cluster :
kubectl apply -f FILE_PATH
Remplacez
FILE_PATH
par le chemin d'accès au fichier YAML.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 manifestePersistentVolume
, 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
oudebug_gcs
, cette nouvelle configuration sera automatiquement définie surtrace
. Cet attribut de volume est traduit par le champ du fichier de configurationlogging: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é.
- Les valeurs de quantité, par exemple :
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 configurationmetadata-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.
- Les valeurs de quantité, par exemple :
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.
- Les valeurs de quantité, par exemple :
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
outype-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 configurationmetadata-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éesGet
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 manifestePersistentVolume
, 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
etreuse-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
etgid
. Vous devez également utiliser les options d'installationfile-mode
etdir-mode
pour définir les autorisations du système de fichiers. Notez que vous ne pouvez pas exécuter les commandeschmod
,chown
ouchgrp
sur un système de fichiers Cloud Storage FUSE. Ainsi, les options d'installationuid
,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'optiono=noexec
. Chaque option nécessite une option distincte, par exempleo=noexec,o=noatime
. Seules les options suivantes sont autorisées :exec
,noexec
,atime
,noatime
,sync
,async
etdirsync
. - Si vous devez résoudre des problèmes liés à Cloud Storage FUSE, définissez les options
debug_fuse
,debug_fs
etdebug_gcs
. Si l'une des trois options est spécifiée, l'attribut de volumegcsfuseLoggingSeverity
est automatiquement défini surtrace
. - 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 volumefileCacheCapacity
pour activer ou désactiver le mise en cache de fichiers. Pour remplacer le volumeemptyDir
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.