Using the Filestore CSI driver


Google Kubernetes Engine (GKE) provides a way for you to automatically deploy and manage the Kubernetes open source 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:

Set up default gcloud settings using one of the following methods:

  • Using gcloud init, if you want to be walked through setting defaults.
  • Using gcloud config, to individually set your project ID, zone, and region.

Using gcloud init

If you receive the error One of [--zone, --region] must be supplied: Please specify location, complete this section.

  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 gcloud 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 for zonal clusters or a region for regional or Autopilot clusters.

Using gcloud config

  • Set your default project ID:
    gcloud config set project PROJECT_ID
  • If you are working with zonal clusters, set your default compute zone:
    gcloud config set compute/zone COMPUTE_ZONE
  • If you are working with Autopilot or regional clusters, set your default compute region:
    gcloud config set compute/region COMPUTE_REGION
  • Update gcloud to the latest version:
    gcloud components update

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.

For example, you can define a StorageClass using the following manifest file named 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:

  • If volumeBindingMode: Immediate is used, a PersistentVolumeClaim is automatically created regardless of whether there is a Deployment using the PersistentVolumeClaim. See VolumeBindingMode for more information.
  • 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.

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.

The following manifest file, named pvc-example.yaml, uses the pre-installed standard-rwx StorageClass:

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: podpvc
spec:
  accessModes:
  - ReadWriteMany
  storageClassName: standard-rwx
  resources:
    requests:
      storage: 1Ti

To create a PersistentVolume resource based on the pvc-example.yaml manifest file, run the following command:

kubectl create -f pvc-example.yaml

In the pre-installed StorageClass (standard-rwx), volumeBindingMode is set to WaitForFirstConsumer. When volumeBindingMode is set to WaitForFirstConsumer, the PersistentVolume is not provisioned until a Pod referencing the PersistentVolumeClaim is scheduled. If volumeBindingMode in the StorageClass is set to Immediate (or it's omitted), a persistent-disk-backed PersistentVolume is provisioned after the PersistentVolumeClaim is created.

Create a Deployment that consumes the volume

The following example Deployment, named filestore-example-deployment.yaml consumes the volume that you created in the previous section. Multiple Pods can share the same PersistentVolumeClaim resource.

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: standard-rwx
  resources:
    requests:
      storage: 1Ti

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