Using the Filestore CSI driver


Google Kubernetes Engine (GKE) provides a way for you to automatically deploy and manage the Kubernetes Filestore CSI driver in your clusters.

The Filestore CSI driver version is tied to Kubernetes minor version numbers. The Filestore CSI driver version is typically the latest driver available at the time that the Kubernetes minor version is released. The drivers update automatically when the cluster is upgraded to the latest GKE patch.

Benefits

Using the Filestore CSI driver provides the following benefits:

  • You can use volume snapshots with the Filestore CSI driver. CSI volume snapshots can be used to create Filestore backups, which creates a differential copy of the file share, including all file data and metadata into separate storage. You can restore this copy to a new Filestore instance only. Restoring to an existing Filestore instance is not supported. You can use the CSI volume snapshot API to trigger Filestore backups, by adding a type:backup field in the volume snapshot class.
  • You can use volume expansion with the Filestore CSI driver. Volume expansion lets you resize your volume's capacity.
  • You can easily access existing Filestore instances by using pre-provisioned Filestore instances in Kubernetes workloads. You can also dynamically create or delete Filestore instances and use them in Kubernetes workloads with a StorageClass or a Deployment.

Requirements

To use the Filestore CSI driver, your clusters must use GKE version 1.21 or later. The Filestore CSI driver is supported for clusters using Linux.

Before you begin

Before you start, make sure you have performed the following tasks:

  • Ensure that you have enabled the Google Kubernetes Engine API.
  • Enable Google Kubernetes Engine API
  • Ensure that you have installed the Cloud SDK.
  • Set up default gcloud command-line tool settings for your project by using one of the following methods:
    • Use gcloud init, if you want to be walked through setting project defaults.
    • Use gcloud config, to individually set your project ID, zone, and region.

    gcloud init

    1. Run gcloud init and follow the directions:

      gcloud init

      If you are using SSH on a remote server, use the --console-only flag to prevent the command from launching a browser:

      gcloud init --console-only
    2. Follow the instructions to authorize the gcloud tool to use your Google Cloud account.
    3. Create a new configuration or select an existing one.
    4. Choose a Google Cloud project.
    5. Choose a default Compute Engine zone.
    6. Choose a default Compute Engine region.

    gcloud config

    1. Set your default project ID:
      gcloud config set project PROJECT_ID
    2. Set your default Compute Engine region (for example, us-central1):
      gcloud config set compute/region COMPUTE_REGION
    3. Set your default Compute Engine zone (for example, us-central1-c):
      gcloud config set compute/zone COMPUTE_ZONE
    4. Update gcloud to the latest version:
      gcloud components update

    By setting default locations, you can avoid errors in gcloud tool like the following: One of [--zone, --region] must be supplied: Please specify location.

Enabling the Filestore CSI driver on a new cluster

To enable the driver on cluster creation, use the gcloud command-line tool or the Google Cloud Console.

gcloud

gcloud container clusters create CLUSTER_NAME \
    --addons=GcpFilestoreCsiDriver \
    --cluster-version=VERSION

Replace the following:

  • CLUSTER_NAME: the name of your cluster.
  • VERSION: the GKE version number. You must select a version of 1.21 or higher to use this feature. Alternatively, you can use the --release-channel flag and specify a release channel.

Console

  1. Go to the Google Kubernetes Engine page in the Cloud Console.

    Go to Google Kubernetes Engine

  2. Click Create.

  3. Choose the Standard cluster mode, then click Configure.

  4. Configure the cluster as desired.

  5. From the navigation pane, under Cluster, click Features.

  6. Select the Enable Filestore CSI driver checkbox.

  7. Click Create.

After you enable the Filestore CSI driver, you can use the driver in Kubernetes volumes using the driver and provisioner name: filestore.csi.storage.gke.io.

Enabling the Filestore CSI driver on an existing cluster

To enable the Filestore CSI driver in existing clusters, use the gcloud command-line tool or the Google Cloud Console.

To enable the driver on an existing cluster, complete the following steps:

gcloud

gcloud container clusters update CLUSTER_NAME \
   --update-addons=GcpFilestoreCsiDriver=ENABLED

Replace CLUSTER_NAME with the name of the existing cluster.

Console

  1. Go to the Google Kubernetes Engine page in Cloud Console.

    Go to Google Kubernetes Engine

  2. In the cluster list, click the name of the cluster you want to modify.

  3. Under Features, next to the Filestore CSI driver field, click Edit Filestore CSI driver.

  4. Select the Enable Filestore CSI driver checkbox.

  5. Click Save Changes.

Disabling the Filestore CSI driver

You can disable the Filestore CSI driver on an existing cluster by using the gcloud command-line tool or the Google Cloud Console.

gcloud

gcloud container clusters update CLUSTER_NAME \
    --update-addons=GcpFilestoreCsiDriver=DISABLED

Replace CLUSTER_NAME with the name of the existing cluster.

Console

  1. In the Cloud Console, go to the Google Kubernetes Engine menu.

    Go to Google Kubernetes Engine

  2. In the cluster list, click the name of the cluster you want to modify.

  3. Under Features, next to the Filestore CSI driver field, click Edit Filestore CSI driver.

  4. Clear the Enable Filestore CSI driver checkbox.

  5. Click Save Changes.

Access a volume using the Filestore CSI driver

The following sections describe the typical process for using a Kubernetes volume backed by a Filestore CSI driver in GKE:

Create a StorageClass

After you enable the Filestore CSI driver, GKE automatically installs the following StorageClasses for provisioning Filestore instances:

  • standard-rwx, using the Basic HDD Filestore service tier
  • premium-rwx, using the Basic SSD Filestore service tier

You can find the name of your installed StorageClass by running the following command:

kubectl get sc

You can also install a different StorageClass that uses the Filestore CSI driver by adding filestore.csi.storage.gke.io in the provisioner field.

  1. Save the following manifest as filestore-example-class.yaml:

    apiVersion: storage.k8s.io/v1
    kind: StorageClass
    metadata:
      name: filestore-example
    provisioner: filestore.csi.storage.gke.io
    volumeBindingMode: WaitForFirstConsumer
    allowVolumeExpansion: true
    parameters:
      tier: standard
      network: default
    

    You might want to update the following parameters:

    • When volumeBindingMode is set to WaitForFirstConsumer, the PersistentVolume is not provisioned until a Pod referencing the PersistentVolumeClaim is scheduled. If volumeBindingMode is set to Immediate (or if it's omitted), a PersistentVolume backed by a persistent disk is provisioned after the PersistentVolumeClaim is created. For more information, see VolumeBindingMode.
    • Any tier can be specified in the tier parameter (for example, standard, premium, or enterprise).
    • The network parameter can be used when provisioning Filestore instances on non-default VPCs. Non-default VPCs require special firewall rules to be set up.
  2. To create a StorageClass resource based on the filestore-example-class.yaml manifest file, run the following command:

    kubectl create -f filestore-example-class.yaml
    

Use a PersistentVolumeClaim to access the volume

You can create a PersistentVolumeClaim resource that references the Filestore CSI driver's StorageClass.

You can use either a pre-installed or custom StorageClass.

The following example manifest file creates a PersistentVolumeClaim that references the StorageClass named filestore-example.

  1. Save the following manifest file as pvc-example.yaml:

    kind: PersistentVolumeClaim
    apiVersion: v1
    metadata:
      name: podpvc
    spec:
      accessModes:
      - ReadWriteMany
      storageClassName: filestore-example
      resources:
        requests:
          storage: 1Ti
    
  2. To create a PersistentVolume resource based on the pvc-example.yaml manifest file, run the following command:

    kubectl create -f pvc-example.yaml
    

Create a Deployment that consumes the volume

The following example Deployment manifest consumes the PersistentVolume resource named pvc-example.yaml.

Multiple Pods can share the same PersistentVolumeClaim resource.

  1. Save the following manifest as web-server-deployment.yaml:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: web-server-deployment
      labels:
        app: nginx
    spec:
      replicas: 3
      selector:
        matchLabels:
          app: nginx
      template:
        metadata:
          labels:
            app: nginx
        spec:
          containers:
          - name: nginx
            image: nginx
            volumeMounts:
            - mountPath: /usr/share/nginx/html
              name: mypvc
          volumes:
          - name: mypvc
            persistentVolumeClaim:
              claimName: podpvc
    ---
    kind: PersistentVolumeClaim
    apiVersion: v1
    metadata:
      name: podpvc
    spec:
      accessModes:
        - ReadWriteMany
      storageClassName: filestore-example
      resources:
        requests:
          storage: 1Ti
    
  2. To create a Deployment based on the filestore-example-deployment.yaml manifest file, run the following command:

    kubectl apply -f filestore-example-deployment.yaml
    

Labeling Filestore instances

You can use labels to group related instances and store metadata about an instance. A label is a key-value pair that helps you organize your Filestore instances. You can attach a label to each resource, then filter the resources based on their labels.

You can provide labels by using the labels key in StorageClass.parameters. A Filestore instance can be labeled with information about what PersistentVolumeClaim/PersistentVolume the instance was created for. Custom label keys and values must comply with the label naming convention. See the Kubernetes storage class example to apply custom labels to the Filestore instance.

Using fsgroup with Filestore volumes

Kubernetes uses fsGroup to change permissions and ownership of the volume to match a user-requested fsGroup in the Pod's SecurityContext. An fsGroup is a supplemental group that applies to all containers in a Pod. You can apply an fsgroup to volumes provisioned by the Filestore CSI driver.

What's next