NFS volume mounts for services

This page shows how to mount an NFS file share as a volume in Cloud Run. You can use any NFS server, including your own NFS server hosted on-premises, or on a Compute Engine VM. If you don't already have an NFS server, we recommend Filestore, which is a fully managed NFS offering from Google Cloud.

If you are looking to use NDB, 9P, CIFS/Samba, and Ceph network file systems refer to using NDB, 9P, CIFS/Samba, and Ceph network file systems.

Limitations

  • In order to write to an NFS volume, your container must run as root. If your container only reads from the file system, it can run as any user.

  • Cloud Run does not support NFS locking. NFS volumes are automatically mounted in no-lock mode.

Before you begin

To mount an NFS server as a volume in Cloud Run, make sure you have the following:

  • A VPC Network where your NFS server or Filestore instance is running.
  • An NFS server running in a VPC network, with your Cloud Run service connected to that VPC network. If you don't already have an NFS server, create one by creating a Filestore instance.
  • Your Cloud Run service is attached to the VPC network where your NFS server is running. For best performance, use Direct VPC rather than VPC Connectors.
  • If you're using an existing project, make sure that your VPC Firewall configuration allows Cloud Run to reach your NFS server. (If you're starting from a new project, this is true by default.) If you're using Filestore as your NFS server, follow the Filestore documentation to create a Firewall egress rule to enable Cloud Run to reach Filestore.

Mount an NFS volume

You can mount multiple NFS servers, Filestore instances, or other volume types at different mount paths.

If you are using multiple containers, first specify the volume(s), then specify the volume mount(s) for each container.

Command line

Note: We show the gcloud beta run services update command but you can also use the gcloud beta run services deploy command with the same parameters as shown.

  • To add a volume and mount it:
gcloud beta run services update SERVICE \
--add-volume=name=VOLUME_NAME,type=nfs,location=IP_ADDRESS:NFS_PATH \
--add-volume-mount=volume=VOLUME_NAME,mount-path=MOUNT_PATH

Replace:

  • SERVICE with the name of your service.
  • VOLUME_NAME with the name you want to give your volume.
  • IP_ADDRESS with the location of the NFS file share.
  • NFS_PATH with the path to the NFS file share.
  • MOUNT_PATH with the relative path where you are mounting the volume, for example, /cache.
  • VOLUME_NAME with any name you want for your volume. The VOLUME_NAME value is used to map the volume to the volume mount.

  • To mount your volume as a read-only volume:

    --add-volume=name=VOLUME_NAME,type=nfs,location=IP_ADDRESS:NFS_PATH,readonly=true
  • If you are using multiple containers, first specify the volumes, then specify the volume mounts for each container:

    gcloud beta run services update SERVICE \
    --add-volume=name VOLUME_NAME,type=nfs,location=IP_ADDRESS:NFS_PATH \
    --container CONTAINER_1 \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH \
    --container CONTAINER_2 \
    --add-volume-mount volume= VOLUME_NAME,mount-path=MOUNT_PATH2

YAML

You can download and view existing service configurations using the gcloud run services describe --format export command, which yields cleaned results in YAML format. You can then modify the fields described below and upload the modified YAML using the gcloud run services replace command. Make sure you only modify fields as documented.

  1. To view and download the configuration:

    gcloud run services describe SERVICE --format export > service.yaml
  2. Update the MOUNT_PATH, VOLUME_NAME, IP_ADDRESS, and NFS_PATH as needed. If you have multiple volume mounts, you will have multiples of these attributes.

    apiVersion: run.googleapis.com/v1
    kind: Service
    metadata:
      name: SERVICE
        annotations:
          run.googleapis.com/launch-stage: BETA
    spec:
      template:
        metadata:
          annotations:
            run.googleapis.com/execution-environment: gen2
        spec:
          containers:
          - image: IMAGE_URL
            volumeMounts:
            - name: VOLUME_NAME
              mountPath: MOUNT_PATH
          volumes:
          - name: VOLUME_NAME
            nfs:
              server: IP_ADDRESS
              path: NFS_PATH
              readonly: IS_READ_ONLY

    Replace

    • SERVICE with the name of your Cloud Run service
    • MOUNT_PATH with the relative path where you are mounting the volume, for example, /cache.
    • VOLUME_NAME with any name you want for your volume. The VOLUME_NAME value is used to map the volume to the volume mount.
    • IP_ADDRESS with the address of the NFS file share.
    • NFS_PATH with the path to the NFS file share.
    • IS_READ_ONLY with True to make the volume read-only, or False to allow writes.
  3. Replace the service with its new configuration using the following command:

    gcloud beta run services replace service.yaml

Troubleshooting NFS

If you experience problems, check the following:

  • Your Cloud Run service is connected to the VPC network that the NFS server is on.
  • There are no firewall rules preventing Cloud Run from reaching the NFS server.
  • If your container writes to your NFS server, make sure it is running as root.