In-memory volumes (services)

This page describes how to configure a dedicated in-memory volume you can use for file reads and writes.

This feature differs from the built-in in-memory filesystem provided by Cloud Run, which does not limit the memory consumed by in-memory file writes. Using in-memory volumes, you can limit the amount of memory that can be consumed.

Behavior

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 exists as long as that instance is running. When the instance stops running, the data in the volume is permanently deleted.

If you specify a limit for an in-memory volume and then exceed that limit when writing to the volume, you will get an out of memory error, which you can handle, and the instance will keep running. If you don't specify a volume size limit and then exceed the instance memory limit when writing to the volume, the instance will crash.

Use cases

​ Use cases for an in-memory volume include allocating scratch space or checkpointing a long computation to prevent crashes.

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.

If you specify a memory size limit for the volume, the memory is allocated from the total instance memory. If you specify a larger in-memory volume size than the instance memory, the volume defaults to the maximum limit set for the Cloud Run instance.

If you don't specify a memory size limit for a volume, you can potentially exceed the instance memory limit and crash the instance.

If you use the in-memory volume as a shared volume in a multicontainer deployment without specifying a memory size limit, half of the total available instance memory is allocated for the shared volume. For example, emptyDir volume size = [Memory (Container A) + Memory (Container B) + Memory (Container N)]/2. Alternatively, if you do specify a memory limit for a shared in-memory volume, that is available uniformly across all containers.

Console

  1. Go to Cloud Run

  2. Click on the service you want to configure.

  3. Click the YAML tab.

  4. Configure the volumeMounts and volumes attributes as shown:

    apiVersion: serving.knative.dev/v1
      kind: Service
      metadata:
      annotations:
        run.googleapis.com/launch-stage: BETA
        name: SERVICE
      spec:
        template:
          metadata:
          spec:
            containers:
            - image: IMAGE_URL
              volumeMounts:
              - mountPath: PATH
                name: VOLUME_NAME
            volumes:
            - name: VOLUME_NAME
              emptyDir:
                sizeLimit: SIZE_LIMIT
                medium: Memory

    replace

    • SERVICE with the name of your Cloud Run service.
    • IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest
    • PATH with the relative path to the volume, for example, /cache.
    • VOLUME_NAME with the name you want to use for the in-memory volume.
    • 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 memory limit set for your instance.
  5. Click Save and Deploy new Revision.

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. Configure the volumeMounts and volumes attributes as shown:

    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
     annotations:
      run.googleapis.com/launch-stage: BETA
      name: SERVICE
    spec:
      template:
        metadata:
        spec:
          containers:
          - image: IMAGE_URL
            volumeMounts:
            - mountPath: PATH
              name: VOLUME_NAME
          volumes:
          - name: VOLUME_NAME
            emptyDir:
              sizeLimit: SIZE_LIMIT
              medium: Memory

    Replace:

    • SERVICE with the name of your Cloud Run service.
    • IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest
    • PATH with the relative path to the volume, for example, /cache.
    • VOLUME_NAME with the name you want to use for the in-memory volume.
    • 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 memory limit set for your instance.
  3. Replace the service with its new configuration using the following command:

    gcloud run services replace service.yaml