In-memory volume mounts for jobs

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 filesystem provided by Cloud Run.

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.

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 do not specify a size limit, it will be 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. In this situation, if your container keeps writing memory to the volume, it will exceed its allocated memory and crash before the volume size limit is reached.

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

Volume ownership differs by execution environment and deployment type

When you mount a volume, the identity owning the files and directories differs depending on the workload's execution environment and on whether the deployment consists of one or multiple containers.

In the first generation execution environment where you are deploying a single container, the volume is owned by the identity used for the container. In all other cases, the volume is owned by root. This includes:

First generation execution environment where you are deploying multiple containers
The second generation environment

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.

Command line

To add a volume and mount it:
```
gcloud beta run jobs update JOB \
--add-volume=name=VOLUME_NAME,type=in-memory,size=SIZE_LIMIT \
--add-volume-mount=volume=VOLUME_NAME,mount-path=MOUNT_PATH
```
Replace:
- JOB with the name of your job.
- VOLUME_NAME with any name you want for your volume. The VOLUME_NAME value is used to map the volume to the volume mount.
- MOUNT_PATH with the relative path within the container file system where you want to mount this volume, for example, /cache.
- SIZE_LIMIT with the memory limit you want to assign to the volume, in MiB or GiB (specified as Mi or Gi), for example, 500Mi. This limit must be less than the total memory specified for your containers.

If you are using multiple containers, first specify the volumes, then specify the volume mounts for each container:

gcloud beta run jobs update JOB \
--add-volume=name= VOLUME_NAME,type=in-memory,size=SIZE_LIMIT \
--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

Download and view existing job configuration using the gcloud run jobs describe --format export command, which yields cleaned results in YAML format. Then modify the fields described below and upload the modified YAML using the gcloud run jobs replace command. Make sure you only modify fields as documented.

To view and download the configuration:

gcloud run jobs describe JOB_NAME --format export > job.yaml

Configure the volumeMounts and volumes attributes as shown:
```
apiVersion: run.googleapis.com/v1
kind: Job
metadata:
  name: JOB_NAME
metadata:
 annotations:
  run.googleapis.com/launch-stage: BETA
spec:
  template:
    metadata:
    spec:
      containers:
      - image: IMAGE_URL
        volumeMounts:
        - mountPath: MOUNT_PATH
          name: VOLUME_NAME
      volumes:
      - name: VOLUME_NAME
        emptyDir:
          sizeLimit: SIZE_LIMIT
          medium: Memory
```
Replace:
- IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
- VOLUME_NAME with any name you want for your volume. The VOLUME_NAME value is used to map the volume to the volume mount.
- MOUNT_PATH with the relative path within the container file system where you want to mount this volume, for example, /cache.
- SIZE_LIMIT with the memory limit you want to assign to the volume, in MiB or GiB (specified as Mi or Gi), for example, 500Mi. This limit must be less than the total memory specified for your containers.
Replace the service with its new configuration using the following command:
```
gcloud beta run jobs replace job.yaml
```