Set up Filestore agent volumes

Note: The Filestore agent volumes feature is available to all Google Cloud customers for evaluation and non-production use. To request access for your Google Cloud project, submit the Filestore agent volumes access request form. Production support is offered on an allow list basis under a limited GA program. To check your eligibility or to request production support, use the access form.

Before you create volume pools or provision volumes, you must configure Virtual Private Cloud (VPC) networking using Private Service Connect (PSC), enable the required APIs, and grant the appropriate IAM roles.

Create a project and enable APIs

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

Enable the Filestore APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

Verify that billing is enabled for your Google Cloud project.

Enable the Filestore APIs.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Required roles

To get the permissions that you need to set up Filestore agent volumes, ask your administrator to grant you the following IAM roles on your project:

• Configure Service Connection Policies and VPC networking: Compute Network Admin (roles/compute.networkAdmin)
• View and manage Filestore instances and related resources, including volume pools and agent volumes: Cloud Filestore Editor (roles/file.editor)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Initialize the service agent

If you haven't created a Filestore instance in your project, initialize the Filestore service agent by running the following command:

gcloud beta services identity create \
    --service=file.googleapis.com \
    --project=PROJECT_ID

Replace PROJECT_ID with the ID of your Google Cloud project.

Grant permissions to the service agent

To set up Filestore agent volumes, grant the Cloud Filestore Editor (roles/file.editor) role to the Filestore service agent:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:[e-mail]" \
    --role="roles/file.editor"

Replace the following:

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

Configure Private Service Connect networking

Filestore agent volumes use Private Service Connect to connect managed storage infrastructure directly to your VPC network. Private Service Connect ensures private, high-bandwidth, and low-latency communication without requiring public IP addresses or VPC Network Peering configurations.

To create a service connection policy, run the following command:

gcloud network-connectivity service-connection-policies create POLICY_NAME \
    --project=PROJECT_ID \
    --region=REGION \
    --network=projects/PROJECT_ID/global/networks/VPC_NETWORK \
    --subnets=SUBNET_NAME \
    --service-class=google-cloud-filestore

Replace the following:

• POLICY_NAME: a name for the service connection policy, such as filestore-agent-psc-policy.
• PROJECT_ID: the ID of your Google Cloud project.
• REGION: the region where the volume pool and workloads will reside, such as us-central1.
• VPC_NETWORK: the name of an existing VPC network.
• SUBNET_NAME: the name of a regular VPC subnet in the specified region where Private Service Connect endpoint IP addresses is to be allocated. An example can be the default subnet with the --purpose flag set to PRIVATE.

Create a volume pool and StorageClass

A volume pool provides the shared storage capacity and IOPS for agent volumes. To dynamically provision volumes from your volume pool in GKE, create the volume pool and then define a Kubernetes StorageClass that references it.

Create a volume pool

To create a sample volume pool, send an HTTP POST request to the volumePools.create endpoint:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d '{
      "description": "Sample volume pool for agent volumes",
      "network": "projects/PROJECT_ID/global/networks/VPC_NETWORK",
      "defaultVolumeQuotaMib": 2048,
    }' \
    "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools?volumePoolId=VOLUME_POOL_ID"

Replace the following:

• PROJECT_ID: the ID of your Google Cloud project.
• VPC_NETWORK: the name of your PSC-enabled VPC network.
• LOCATION: the region where the volume pool is deployed, such as us-central1.
• VOLUME_POOL_ID: an identifier for the volume pool, such as my-volume-pool.

For more information, see Create and manage volume pools.

Create a StorageClass

Create a StorageClass manifest named volume-pool-sc.yaml that references your volume pool:

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 the volume pool is deployed.
• VOLUME_POOL_ID: the identifier of your volume pool.

If you have an existing GKE cluster with the Filestore CSI driver installed, apply the StorageClass:

kubectl apply -f volume-pool-sc.yaml

Otherwise, apply this manifest after setting up your cluster in Set up GKE environment for Filestore agent volumes.

What's next

• Create and manage volume pools.
• Configure GKE environment for Filestore agent volumes.