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
andvolumes
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 shapeLOCATION-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.
- IMAGE_URL with a reference to the container image, for
example,
Replace the service with its new configuration using the following command:
gcloud beta run jobs replace job.yaml