Configure 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 NBD, 9P, CIFS/Samba, and Ceph network file systems, refer to using NBD, 9P, CIFS/Samba, and Ceph network file systems.

Mounting the NFS file share as a volume in Cloud Run presents the file share as files in the container file system. After you you mount the file share as a volume, you access it as if it were a directory on your local file system, using your programming language's file system operations and libraries.

Disallowed paths

Cloud Run does not allow you to mount a volume at /dev, /proc and /sys, or on their subdirectories.

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.

Console

In the Google Cloud console, go to Cloud Run:

Go to Cloud Run
Click Deploy container and select Service to configure a new service. If you are configuring an existing service, click the service, then click Edit and deploy new revision.
If you are configuring a new service, fill out the initial service settings page, then click Container(s), volumes, networking, security to expand the service configuration page.
Click the Volumes tab.
- Under Volumes:
  - Click Add volume.
  - In the Volume type drop-down, select NFS as the volume type.
  - In the Volume name field, enter the name you want to use for the volume.
  - In the NFS server field, enter the domain name or location (in the form IP_ADDRESS) of the NFS file share.
  - In the Path field, enter the path to the NFS server directory that you want to mount.
  - Click Done.
- Click the Container tab, then expand the container you are mounting the volume to, to edit the container.
- Click the Volume Mounts tab.
- Click Mount volume.
Click Create or Deploy.

gcloud

To add a volume and mount it:
```
gcloud 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 starting with a forward slash, for example /example-directory.
- MOUNT_PATH with the relative path where you are mounting the volume, for example, /mnt/my-volume.
- 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 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

If you are creating a new service, skip this step. If you are updating an existing service, download its YAML configuration:
```
gcloud run services describe SERVICE --format export > service.yaml
```
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
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, /mnt/my-volume.
- 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 starting with a forward slash, for example, /example-directory.
- IS_READ_ONLY with True to make the volume read-only, or False to allow writes.
Create or update the service using the following command:
```
gcloud run services replace service.yaml
```

Reading and writing to a volume

If you use the Cloud Run volume mount feature, you access a mounted volume using the same libraries in your programming language that you use to read and write files on your local file system.

This is especially useful if you're using an existing container that expects data to be stored on the local file system and uses regular file system operations to access it.

The following snippets assume a volume mount with a mountPath set to /mnt/my-volume.

Nodejs

Use the File System module to create a new file or append to an existing in the volume, /mnt/my-volume:

var fs = require('fs');
fs.appendFileSync('/mnt/my-volume/sample-logfile.txt', 'Hello logs!', { flag: 'a+' });

Python

Write to a file kept in the volume, /mnt/my-volume:

f = open("/mnt/my-volume/sample-logfile.txt", "a")

Go

Use the os package to create a new file kept in the volume, /mnt/my-volume

f, err := os.Create("/mnt/my-volume/sample-logfile.txt")

Java

Use the Java.io.File class to create a log file in the volume, /mnt/my-volume:

import java.io.File;
File f = new File("/mnt/my-volume/sample-logfile.txt");

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.

Container startup time and NFS volume mounts

Using NFS volume mounts can slightly increase your Cloud Run container cold start time because the volume mount is started prior to starting the container(s). Your container will start only if NFS is successfully mounted.

Note that NFS successfully mounts a volume only after establishing a connection to the server and fetching a filehandle. Any networking delays can have an impact on container startup time. If Cloud Run fails to establish a connection to the server, the Cloud Run service will fail to start. Also, if NFS takes longer than 30 seconds to mount, the Cloud Run service will fail to start because Cloud Run has a total timeout of 30 seconds to perform all mounts.

NFS performance characteristics

If you create more than one NFS volume, all volumes are mounted in parallel.

Because NFS is a network file system it is subject to bandwidth limits and access to the file system can be impacted by limited bandwidth.

When you write to your NFS volume, the write is stored in Cloud Run memory until the data is flushed. Data is flushed in the following circumstances:

Your application flushes file data explicitly using sync(2), msync(2), or fsync(3).
Your application closes a file with close(2).
Memory pressure forces reclamation of system memory resources.

For more information, see the Linux documentation on NFS.