If you want to fine-tune specific behavior of the Cloud Storage FUSE CSI driver,
you can use volume attributes.
The following list describe the volume attributes that you can use.
disableMetrics
Description: Whether your workload should export metrics. This should be
set to "false" if you plan on using
Cloud Storage FUSE metrics.
Valid values:
Boolean values in string format: "true", "false".
Default value: "true"
fileCacheCapacity
Description: The maximum size that the file cache can use. If a non-zero
value presents, this volume attribute enables file caching in Cloud Storage FUSE.
This volume attribute is translated to the configuration file field
file-cache:max-size-mb. We recommend that you use mount options to set this field.
"-1": to use the cache volume's entire available capacity.
"0": the file cache is disabled.
Default value: "0".
fileCacheForRangeRead
Description: Whether the full object should be downloaded asynchronously
and stored in the Cloud Storage FUSE cache directory when the first read is done
from a non-zero offset. This should be set to "true" if you plan on performing
several random reads or partial reads.
This volume attribute is translated to the configuration file field
file-cache:cache-file-for-range-read. We recommend that you use mount options to set this field.
Valid values:
Boolean values in string format: "true", "false".
Default value: "false".
gcsfuseLoggingSeverity
Description: The severity of logs you want Cloud Storage FUSE to generate,
expressed as an enum.
This volume attribute is translated to the configuration file field
logging:severity. We recommend that you use mount options to set this field.
Valid values (ordered from lowest severity to highest severity):
Description: The maximum size that the stat cache can use.
The stat cache is always entirely kept in memory.
If you are already using stat-cache-capacity mount option,
the value will still be honored and will be appropriately translated to this new configuration.
This volume attribute is translated to the configuration file field
metadata-cache:stat-cache-max-size-mb. We recommend that you use mount options to set this field.
"-1": to let the stat cache use as much memory as needed.
"0": the stat cache is disabled.
Use the default value of 32Mi if your workload involves up to 20,000 files.
If your workload is larger than 20,000 files, increase the size by values
of 10 MiB for every additional 6,000 files, an average of ~1,500 bytes per file.
Default value: 32Mi.
metadataTypeCacheCapacity
Description: The maximum size per directory that the type cache can use.
The type cache is always entirely kept in memory.
This volume attribute is translated to the configuration file field
metadata-cache:type-cache-max-size-mb. We recommend that you use mount options to set this field.
"-1": to let the type cache use as much memory as needed.
"0": the type cache is disabled.
Use the default value of 4Mi if the maximum number of files within a
single directory from the bucket you're mounting contains 20,000 files or less.
If the maximum number of files within a single directory that you're mounting
contains more than 20,000 files, increase the size by 1 MiB for every 5,000 files,
an average of ~200 bytes per file.
Default value: 4Mi.
metadataCacheTTLSeconds
Description: The time to live (TTL), in seconds, of cached metadata entries.
If you are already using the stat-cache-ttl or type-cache-ttl mount options,
the values will still be honored and will be appropriately translated to this new configuration.
This volume attribute is translated to the configuration file field
metadata-cache:ttl-secs. We recommend that you use mount options to set this field.
Valid values:
Integer values in string format, for example: "600".
"-1": bypass a TTL expiration and serve the file from the cache whenever it's available.
"0": ensure that the most up to date file is read. Using
a value of 0 issues a Get metadata call to make sure that the object
generation for the file in the cache matches what's stored in Cloud Storage.
Default value: "60".
skipCSIBucketAccessCheck
Description: Directs the CSI driver to skip redundant access control checks
for the Cloud Storage bucket, when set to "true". This reduces the
overhead of redundant Kubernetes Service API, Security Token Service, and IAM
calls. When the flag is set, the Cloud Storage FUSE process, running as part of
the sidecar container in the Pod, handles the bucket access control checks.
Valid values:
Boolean values in string format: "true", "false".
Default value: "false".
hostNetworkPodKSA
Description: Supported after Standard GKE cluster version TODO. Set this to "true" to configure your host network (hostNetwork: true) Pods to use their own Kubernetes Service Account (KSA) for authentication when accessing Cloud Storage using Cloud Storage FUSE. We recommend this security practice as it aligns with the principle of least privilege, providing granular access control.
If you omit this field or set it to "false", hostNetwork Pods will default to routing requests from Pods running on the host network to the Compute Engine metadata server using the broader permissions of the node's default Service Account. In such a case, ensure that the node's default Service Account has sufficient permissions to access the bucket.
Valid values:
Boolean values in string format: "true", "false".
Default value: "false".
identityProvider
Description: Supported after Standard GKE cluster version TODO. Provide the full URL of your GKE cluster's Workload Identity issuer. This attribute is required if you manually manage the Cloud Storage FUSE sidecars for your hostNetwork: true Pods and want to enable those Pods to use their own Kubernetes Service Account (KSA) for authentication when accessing Cloud Storage.
Valid values:
URL in the format: https://container.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_NAME.
Replace the following:
PROJECT_ID: your Google Cloud project ID.
LOCATION: the location of your cluster.
CLUSTER_NAME: the name of your Standard GKE cluster.
Default value: None. Explicitly provide a value when using private or custom sidecars to enable authentication for your hostNetwork: true Pods.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[],[],null,["# Cloud Storage FUSE CSI driver volume attributes\n\n*** ** * ** ***\n\n[Cloud Storage FUSE CSI driver](/kubernetes-engine/docs/concepts/cloud-storage-fuse-csi-driver)\nprovides an abstraction layer for [Cloud Storage FUSE](/storage/docs/cloud-storage-fuse/overview)\nto ensure consistency, stability, and security for GKE users.\n| **Note:** We recommend that you use [mount options](/kubernetes-engine/docs/how-to/cloud-storage-fuse-csi-driver-perf#mount-options) if you want to configure how Cloud Storage buckets are mounted on the local file system.\n\nIf you want to fine-tune specific behavior of the Cloud Storage FUSE CSI driver,\nyou can [use volume attributes](/kubernetes-engine/docs/how-to/cloud-storage-fuse-csi-driver-perf#volume-attributes).\n\nThe following list describe the volume attributes that you can use.\n\n- **`disableMetrics`**\n\n - **Description** : Whether your workload should export metrics. This should be\n set to \"false\" if you plan on using\n [Cloud Storage FUSE metrics](/kubernetes-engine/docs/how-to/cloud-storage-fuse-csi-driver-perf#cloud-storage-fuse-metrics).\n\n - **Valid values**:\n\n - Boolean values in string format: \"true\", \"false\".\n - **Default value**: \"true\"\n\n- **`fileCacheCapacity`**\n\n - **Description** : The maximum size that the file cache can use. If a non-zero\n value presents, this volume attribute enables file caching in Cloud Storage FUSE.\n This volume attribute is translated to the configuration file field\n `file-cache:max-size-mb`. We recommend that you use [mount options](/kubernetes-engine/docs/how-to/cloud-storage-fuse-csi-driver-perf#mount-options) to set this field.\n\n - **Valid values**:\n\n - [Quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/) values, for example: `500Mi`, `10Gi`.\n - \"-1\": to use the cache volume's entire available capacity.\n - \"0\": the file cache is disabled.\n - **Default value**: \"0\".\n\n- **`fileCacheForRangeRead`**\n\n - **Description** : Whether the full object should be downloaded asynchronously\n and stored in the Cloud Storage FUSE cache directory when the first read is done\n from a non-zero offset. This should be set to \"true\" if you plan on performing\n several random reads or partial reads.\n This volume attribute is translated to the configuration file field\n `file-cache:cache-file-for-range-read`. We recommend that you use [mount options](/kubernetes-engine/docs/how-to/cloud-storage-fuse-csi-driver-perf#mount-options) to set this field.\n\n - **Valid values**:\n\n - Boolean values in string format: \"true\", \"false\".\n - **Default value**: \"false\".\n\n- **`gcsfuseLoggingSeverity`**\n\n - **Description** : The severity of logs you want Cloud Storage FUSE to generate,\n expressed as an enum.\n This volume attribute is translated to the configuration file field\n `logging:severity`. We recommend that you use [mount options](/kubernetes-engine/docs/how-to/cloud-storage-fuse-csi-driver-perf#mount-options) to set this field.\n\n - **Valid values** (ordered from lowest severity to highest severity):\n\n - `trace`\n - `debug`\n - `info`\n - `warning`\n - `error`\n - **Default value** : `info`.\n\n- **`gcsfuseMetadataPrefetchOnMount`**\n\n - **Description** : Enable the prefetch of the metadata caches for a\n specified volume. To learn more, see\n [Use metadata prefetch to pre-populate the metadata cache](/kubernetes-engine/docs/how-to/cloud-storage-fuse-csi-driver-perf#metadata-prefetch).\n\n - **Valid values**:\n\n - Boolean values in string format: \"true\", \"false\".\n - **Default value**: \"false\".\n\n- **`metadataStatCacheCapacity`**\n\n - **Description** : The maximum size that the stat cache can use.\n The stat cache is always entirely kept in memory.\n If you are already using `stat-cache-capacity` mount option,\n the value will still be honored and will be appropriately translated to this new configuration.\n This volume attribute is translated to the configuration file field\n `metadata-cache:stat-cache-max-size-mb`. We recommend that you use [mount options](/kubernetes-engine/docs/how-to/cloud-storage-fuse-csi-driver-perf#mount-options) to set this field.\n\n - **Valid values**:\n\n - [Quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/) values, for example: `500Mi`, `1Gi`.\n - \"-1\": to let the stat cache use as much memory as needed.\n - \"0\": the stat cache is disabled.\n - Use the default value of `32Mi` if your workload involves up to 20,000 files. If your workload is larger than 20,000 files, increase the size by values of 10 MiB for every additional 6,000 files, an average of \\~1,500 bytes per file.\n - **Default value** : `32Mi`.\n\n- **`metadataTypeCacheCapacity`**\n\n - **Description** : The maximum size per directory that the type cache can use.\n The type cache is always entirely kept in memory.\n This volume attribute is translated to the configuration file field\n `metadata-cache:type-cache-max-size-mb`. We recommend that you use [mount options](/kubernetes-engine/docs/how-to/cloud-storage-fuse-csi-driver-perf#mount-options) to set this field.\n\n - **Valid values**:\n\n - [Quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/) values, for example: `500Mi`, `1Gi`.\n - \"-1\": to let the type cache use as much memory as needed.\n - \"0\": the type cache is disabled.\n - Use the default value of `4Mi` if the maximum number of files within a single directory from the bucket you're mounting contains 20,000 files or less. If the maximum number of files within a single directory that you're mounting contains more than 20,000 files, increase the size by 1 MiB for every 5,000 files, an average of \\~200 bytes per file.\n - **Default value** : `4Mi`.\n\n- **`metadataCacheTTLSeconds`**\n\n - **Description** : The time to live (TTL), in seconds, of cached metadata entries.\n If you are already using the `stat-cache-ttl` or `type-cache-ttl` mount options,\n the values will still be honored and will be appropriately translated to this new configuration.\n This volume attribute is translated to the configuration file field\n `metadata-cache:ttl-secs`. We recommend that you use [mount options](/kubernetes-engine/docs/how-to/cloud-storage-fuse-csi-driver-perf#mount-options) to set this field.\n\n - **Valid values**:\n\n - Integer values in string format, for example: \"600\".\n - \"-1\": bypass a TTL expiration and serve the file from the cache whenever it's available.\n - \"0\": ensure that the most up to date file is read. Using a value of `0` issues a `Get` metadata call to make sure that the object generation for the file in the cache matches what's stored in Cloud Storage.\n - **Default value**: \"60\".\n\n- **`skipCSIBucketAccessCheck`**\n\n - **Description**: Directs the CSI driver to skip redundant access control checks\n for the Cloud Storage bucket, when set to \"true\". This reduces the\n overhead of redundant Kubernetes Service API, Security Token Service, and IAM\n calls. When the flag is set, the Cloud Storage FUSE process, running as part of\n the sidecar container in the Pod, handles the bucket access control checks.\n\n - **Valid values**:\n\n - Boolean values in string format: \"true\", \"false\".\n - **Default value**: \"false\".\n\n- **`hostNetworkPodKSA`**\n\n - **Description** : Supported after Standard GKE cluster version TODO. Set this to `\"true\"` to configure your [host network](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#hosts-namespaces) (`hostNetwork: true`) Pods to use their own Kubernetes Service Account (KSA) for authentication when accessing Cloud Storage using Cloud Storage FUSE. We recommend this security practice as it aligns with the principle of least privilege, providing granular access control.\n\n If you omit this field or set it to `\"false\"`, `hostNetwork` Pods will default to routing requests from Pods running on the host network to the Compute Engine metadata server using the broader permissions of the node's default Service Account. In such a case, ensure that the node's default Service Account has sufficient permissions to access the bucket.\n - **Valid values**:\n\n - Boolean values in string format: \"true\", \"false\".\n - **Default value**: \"false\".\n\n- **`identityProvider`**\n\n - **Description** : Supported after Standard GKE cluster version TODO. Provide the full URL of your GKE cluster's Workload Identity issuer. This attribute is required if you [manually manage the Cloud Storage FUSE sidecars](/kubernetes-engine/docs/how-to/cloud-storage-fuse-csi-driver-setup#private_sidecars) for your `hostNetwork: true` Pods and want to enable those Pods to use their own Kubernetes Service Account (KSA) for authentication when accessing Cloud Storage.\n\n - **Valid values**:\n\n - URL in the format: `https://container.googleapis.com/v1/projects/`\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e`/locations/`\u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e`/clusters/`\u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e.\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: your Google Cloud project ID.\n - \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e: the location of your cluster.\n - \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e: the name of your Standard GKE cluster.\n - **Default value** : None. Explicitly provide a value when using private or custom sidecars to enable authentication for your `hostNetwork: true` Pods."]]
