Configure in-memory volume mounts for worker pools

This page describes how to configure a dedicated in-memory volume you can use for file reads and writes using Cloud Run volume mounts. Note that this feature differs from the built-in in-memory file system provided by Cloud Run.

When you mount the in-memory volume in Cloud Run, the in-memory volume shows up as files in the container file system. After you mount the in-memory 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.

You can use in-memory volumes to do the following:

• Limit the size of the in-memory volume. When you limit the size of a volume, writes to a full volume will fail, which is preferable to having Cloud Run terminate instances due to the volume consuming too much memory.
• Share an in-memory volume between different containers in one Cloud Run instance. When Cloud Run scales out to multiple instances of a worker pool, each worker pool will have its own in-memory volume shared by all the containers on that worker pool. This volume is available to all the containers when Cloud Run scales out to handle traffic.

Behavior

When creating an in-memory volume, we recommend specifying a size limit. If the volume reaches its size limit, further writes will fail with an out-of-memory error. Your instance can handle this error and keep running.

Note that the size limit is just a limit: it does not allocate additional space for your in-memory volume. Rather, your in-memory volume consumes the memory you configured for your containers. If you deploy multiple containers, the memory used by each write to the volume counts as memory usage for the container that wrote the data.

If you don't specify a size limit, it is automatically set to half of the total size of all the containers in your job or service. For example, emptyDir volume size = [Memory (Container A) + Memory (Container B) + Memory (Container N)]/2. This default behavior can result in the size limit of the in-memory volume being higher than the memory allocated for some of your containers. This can lead to unexpected crashes if a single container exceeds its own allocated memory while trying to write more data to the volume, even though the volume size limit has not been reached.

Although setting a size limit is optional, we recommend setting one to protect your containers from running out-of-memory and crashing.

Disallowed paths

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

Required roles

For a list of IAM roles and permissions that are associated with Cloud Run, see Cloud Run IAM roles and Cloud Run IAM permissions. If your Cloud Run worker pool interfaces with Google Cloud APIs, such as Cloud Client Libraries, see the service identity configuration guide. For more information about granting roles, see deployment permissions and manage access.

Configure an in-memory volume

Any configuration change leads to the creation of a new revision. Subsequent revisions will also automatically get this configuration setting unless you make explicit updates to change it.

After you configure an in-memory volume for your Cloud Run service, an empty volume is created for every Cloud Run instance that is started, and the volume exists as long as that instance is running. When the instance stops running, the data in the volume is permanently deleted.

Configure an in-memory volume mount using the Google Cloud CLI when you create a new worker pool or deploy a new revision.

View environment variable configuration for the worker pool

1. In the Google Cloud console, go to Cloud Run:

   Go to Cloud Run

2. Click Worker pools to display the list of deployed worker pools.

3. Click the worker pool you want to examine to display its details pane.

4. Click the Containers tab to display worker pool container configuration.

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.

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

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

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

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

Clear and remove volumes and volume mounts

You can clear all volumes and mounts or you can remove individual volumes and volume mounts.

Clear all volumes and volume mounts

To clear all volumes and volume mounts from your single-container worker pool, run the following command:

gcloud beta run worker-pools update WORKER_POOL \
    --clear-volumes
    --clear-volume-mounts

If you have multiple containers, follow the sidecars CLI conventions to clear volumes and volume mounts:

gcloud beta run worker-pools update WORKER_POOL \
    --container=container1 \
    --clear-volumes
    -–clear-volume-mounts \
    --container=container2 \
    --clear-volumes \
    -–clear-volume-mounts

Remove individual volumes and volume mounts

In order to remove a volume, you must also remove all volume mounts using that volume.

To remove individual volumes or volume mounts, use the remove-volume and remove-volume-mount flags:

gcloud beta run worker-pools update WORKER_POOL \
    --remove-volume VOLUME_NAME \
    --container=container1 \
    --remove-volume-mount MOUNT_PATH \
    --container=container2 \
    --remove-volume-mount MOUNT_PATH