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

Give the Kubernetes ServiceAccount used by the CSI driver and the Compute Engine default service account permissions to provision Filestore volumes:

  1. Get your project number:

    gcloud projects describe PROJECT_ID \
    --format="value(projectNumber)"

    Replace PROJECT_ID with your project ID.

  2. Grant the Cloud Filestore Editor role (roles/file.editor) on the project to the Kubernetes ServiceAccount (gcp-filestore-csi-controller-sa) in the gcp-filestore-csi-driver namespace:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/gcp-filestore-csi-driver/sa/gcp-filestore-csi-controller-sa" \
    --role="roles/file.editor" \
    --condition=None

    Replace the following:

    • PROJECT_ID: your Google Cloud project ID.
    • PROJECT_NUMBER: your Google Cloud project number.

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

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
    --role="roles/file.editor" \
    --condition=None

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. 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
parameters:
  volume-pool: "projects/<var>PROJECT_ID</var>/locations/<var>LOCATION</var>/volumePools/<var>VOLUME_POOL_ID</var>"
mountOptions:
  - vers=3
  - proto=tcp
  - mountproto=tcp
  - port=2049
  - mountport=2050
volumeBindingMode: Immediate
reclaimPolicy: Delete

    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: