Set up GKE environment for Filestore agent volumes

Filestore agent volumes integrate with Google Kubernetes Engine (GKE) to provide high-density, low-latency persistent file storage for stateful AI agent sandboxes, developer environments, and multi-agent workflows.

This guide walks you through the prerequisites needed to use Filestore agent volumes on GKE.

Before you begin

  1. Complete the initial setup in Set up Filestore agent volumes.

  2. Enable the GKE API:

    gcloud services enable container.googleapis.com \
    --project=PROJECT_ID

  3. Install the required components for gcloud:

    gcloud components install kubectl gke-gcloud-auth-plugin

Create a GKE cluster

Create a GKE cluster connected to your Private Service Connect.

gcloud container clusters create CLUSTER_NAME \
    --region=REGION \
    --project=PROJECT_ID \
    --network=projects/PROJECT_ID/global/networks/VPC_NETWORK \
    --subnetwork=SUBNET_NAME \
    --num-nodes=3 \
    --workload-pool=PROJECT_ID.svc.id.goog\
    --scopes=cloud-platform \
    --enable-agent-sandbox \
    --addons=GcpFilestoreCsiDriver=DISABLED \
    --cluster-version=1.36.0-gke.3302001

Replace the following:

  • CLUSTER_NAME: the name of the new cluster.
  • REGION: the region where your volume pool resides, such as us-central1.
  • PROJECT_ID: your Google Cloud project ID.
  • VPC_NETWORK: the name of your PSC-enabled VPC network.
  • SUBNET_NAME: the name of the subnet.

Set up Workload Identity Federation for GKE and IAM

Configure a Google Service Account (GSA) with permissions to provision Filestore volumes and bind it to the Kubernetes Service Account (KSA) used by the CSI driver.

  1. Create the Google Service Account:

    gcloud iam service-accounts create filestore-csi-gsa \
    --display-name="Filestore CSI Driver GSA" \
    --project=PROJECT_ID

  2. Grant the Cloud Filestore Editor (roles/file.editor) role to the service account:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:filestore-csi-gsa@PROJECT_ID.iam.iam.gserviceaccount.com" \
    --role="roles/file.editor"

  3. Grant the Cloud Filestore Editor (roles/file.editor) role to the Compute Engine default service account:

    PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID \
    --format="value(projectNumber)")
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.iam.gserviceaccount.com" \
    --role="roles/file.editor"

  4. Bind the KSA in the gcp-filestore-csi-driver namespace to the GSA:

    gcloud iam service-accounts add-iam-policy-binding \
    filestore-csi-gsa@PROJECT_ID.iam.iam.gserviceaccount.com \
    --role="roles/iam.workloadIdentityUser" \
    --member="serviceAccount:PROJECT_ID.svc.id.goog[gcp-filestore-csi-driver/gcp-filestore-csi-controller-sa]" \
    --project=PROJECT_ID

Deploy the Filestore CSI driver

  1. Get cluster credentials:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --region=REGION \
    --project=PROJECT_ID

  2. Clone the driver repository and apply the volumepool overlay:

    git clone https://github.com/kubernetes-sigs/gcp-filestore-csi-driver.git
cd gcp-filestore-csi-driver
kubectl apply -k deploy/kubernetes/overlays/volumepool

  3. Annotate the controller service account with the GSA:

    kubectl annotate serviceaccount gcp-filestore-csi-controller-sa \
    --namespace=gcp-filestore-csi-driver \
    --overwrite \
    iam.gke.io/gcp-service-account=filestore-csi-gsa@PROJECT_ID.iam.iam.gserviceaccount.com

  4. Verify that the CSI driver pods are running:

    kubectl get pods -n gcp-filestore-csi-driver

    The output is similar to the following:

    NAME                             READY   STATUS    RESTARTS   AGE
gcp-filestore-csi-controller-0   5/5     Running   0          2m
gcp-filestore-csi-node-abcde     3/3     Running   0          2m

Apply the StorageClass for your volume pool

To allow your GKE workloads to dynamically provision volumes from your volume pool, apply a Kubernetes StorageClass to your cluster.

If you already created the volume-pool-sc.yaml manifest in Set up Filestore agent volumes, skip to step 2.

  1. Create a file named volume-pool-sc.yaml with the following configuration:

    apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: volume-pool-sc
provisioner: filestore.csi.storage.gke.io
volumeBindingMode: Immediate
reclaimPolicy: Delete
allowVolumeExpansion: true
parameters:
  volume-pool: "projects/<var>PROJECT_ID</var>/locations/<var>LOCATION</var>/volumePools/<var>VOLUME_POOL_ID</var>"

    Replace the following:

    • PROJECT_ID: the ID of your Google Cloud project.
    • LOCATION: the region where your volume pool is deployed, such as us-central1.
    • VOLUME_POOL_ID: the identifier of your volume pool.

  2. Apply the manifest:

    kubectl apply -f volume-pool-sc.yaml

  3. Verify that the StorageClass is available:

    kubectl get storageclass volume-pool-sc

    The output is similar to the following:

    NAME             PROVISIONER                    RECLAIMPOLICY   VOLUMEBINDINGMODE   ALLOWVOLUMEEXPANSION   AGE
volume-pool-sc   filestore.csi.storage.gke.io   Delete          Immediate           true                   1m

After completing this guide, your GKE environment is ready to support Filestore agent volumes.

What's next

With your GKE cluster and storage class configured, you can deploy stateful AI agent workloads using any of the following orchestration patterns: