Configure an ephemeral disk for Cloud Run services

Cloud Run provides an ephemeral disk volume that persists only for the duration of your instance. This feature lets you specify the amount of disk you need and the location for mounting it. Cloud Run will then allocate that amount of disk to your resource.

Disks are automatically provisioned, pre-formatted to ext4, and encrypted with instance-specific keys at startup. Ephemeral disk creates your volume so that any user can read or write to it. Because the storage is ephemeral, all data is permanently deleted when the instance shuts down. This includes shutdowns caused by:

• Instance crashes
• Service scaling
• Traffic migration to a new revision

Disks are dedicated to a specific instance and are not shared across other instances or revisions. You have control over the file system structure with a configurable mount point for each volume.

Before shutting down an instance, Cloud Run sends a SIGTERM signal to all the containers in an instance, indicating the start of a 10-second period before the actual shutdown occurs, at which point Cloud Run sends a SIGKILL signal. You can use this 10-second window to perform cleanup operations such as doing a final round of copying disk content persistent storage.

Use cases

You can use ephemeral disk for the following:

• Data processing workloads: When processing large data files in Cloud Run, you typically store the entire file in memory or orchestrate splitting it up into smaller pieces. With ephemeral storage, you won't need to pay for large amounts of memory to make a temporary local copy of your data. You will also be able to process larger data sets.
• Caching: In web serving use cases, caching data on disk rather than fetching from remote storage can optimize your application's latency.

Storage and instance limits

The following limits apply:

• Instance storage limit: each instance is limited to 10 GB of total space by default. If necessary, request a quota increase.
• Instance volume limit: each instance is limited to a maximum of 10 volumes.
• Project limit: each project is limited to 100 GB per region by default. If necessary, request a quota increase.

Request a quota increase

Projects using a Cloud Run ephemeral disk in a region for the first time are automatically granted 10 GB per instance, per region limit and 100 GB per project, per region limit.

If you need additional capacity, you must request a quota increase for your Cloud Run service. Use the links provided in the following buttons to request the quota you need.

For more information on requesting quota increases, see How to increase quota.

Limitations

Disallowed paths

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

Supported regions

The ephemeral disk feature is available in the following regions:

• For non-GPU workloads, ephemeral disk is available in:
  • asia-northeast1 (Tokyo)
  • europe-west1 (Belgium) Low CO₂
  • northamerica-northeast1 (Montreal) Low CO₂
  • northamerica-northeast2 (Toronto) Low CO₂
  • us-central1 (Iowa) Low CO₂
  • us-east1 (South Carolina)
  • us-east4 (Northern Virginia)
  • us-west1 (Oregon) Low CO₂
• If you use GPUs, ephemeral disk is available in all regions that support GPUs.

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Install and initialize the gcloud CLI.
2. Update components:

   gcloud components update

3. Review the Cloud Run pricing page for CPU, memory, and network egress. The entire size of the provisioned disk and the lifetime of the instance that is using it contribute to your cost.

Required roles

To get the permissions that you need to configure an ephemeral disk, ask your administrator to grant you the following IAM roles:

• Cloud Run Developer (roles/run.developer) on the Cloud Run service
• Service Account User (roles/iam.serviceAccountUser) on the service identity

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 service 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.

Create and mount an ephemeral disk

You can create and mount an ephemeral disk using the Google Cloud console, Google Cloud CLI, or Terraform:

gcloud beta run services update SERVICE \
    --execution-environment=gen2 \
    --add-volume=name=VOLUME_NAME,type=ephemeral-disk,size=SIZE \
    --add-volume-mount=volume=VOLUME_NAME,mount-path=MOUNT_PATH

  resource "google_cloud_run_v2_service" "default" {
    name     = "SERVICE"
    location = "REGION"
    launch_stage = "BETA"
    deletion_protection =  "true"
    ingress = "INGRESS_TRAFFIC_ALL"

  template {
    containers {
        image = "IMAGE_URL"
        volume_mounts {
          name = "VOLUME_NAME"
          mount_path = "MOUNT_PATH"
        }
    }
    volumes {
        name = "VOLUME_NAME"
        empty_dir {
          medium = "DISK"
          size_limit = "SIZE"
        }
    }
  }
  lifecycle {
    ignore_changes = [
      launch_stage,
    ]
  }
}

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 service, run the following command:

gcloud run services update SERVICE \
    --clear-volumes
    --clear-volume-mounts

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

gcloud run services update SERVICE \
    --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 run services update SERVICE \
    --remove-volume VOLUME_NAME \
    --container=container1 \
    --remove-volume-mount MOUNT_PATH \
    --container=container2 \
    --remove-volume-mount MOUNT_PATH

Best practices

Adhere to the following best practices to effectively manage ephemeral data and optimize storage performance.

Copy to persistent storage

If you intend to copy the ephemeral disk contents to persistent storage, such as a Cloud Storage bucket, we recommend incrementally copying, rather than relying on the 10-second SIGTERM to SIGKILL grace period. See Container runtime contract for more information on instance shutdowns.

Cloud Run can read and write from Cloud Storage without any additional networking setup. To achieve optimal performance, we recommend routing traffic to and from Cloud Storage through a VPC network using Direct VPC.

This method works if you don't need the Cloud Run resource to access the internet. If you do need internet access, either set up Cloud NAT, or see Internal traffic to a Google API.

To configure Direct VPC egress with a service complete the following steps:

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

   Go to Cloud Run

2. Click Create Service if you are configuring a new service you are deploying to. If you are configuring and deploying an existing service, click the service, then click Edit and deploy new revision.

3. If you are configuring a new service, fill out the initial service settings page as needed, then click Containers, Networking, Security to expand the service configuration page.

4. Click the Networking tab.

5. Click Connect to a VPC for outbound traffic.

6. Click Send traffic directly to a VPC.

7. In the Network field, select the VPC network that you want to send traffic to.

8. In the Subnet field, select the subnet where your service receives IP addresses from. You can deploy multiple services on the same subnet.

9. For Traffic routing, select Route all traffic to the VPC to send all outbound traffic through the VPC network.

   1. Click Create or Deploy.

   2. To verify that your service is on your VPC network, click the service, then click the Networking tab. The network and subnet are listed in the VPC card.

      You can now send requests from your Cloud Run service to any resource on the VPC network, as allowed by your firewall rules.

   3. Enable Private Google Access on the subnet you connected to.

Troubleshoot

• If your container is running out of memory and you used the Google Cloud console to deploy a new revision of a service with ephemeral disk attached, the Google Cloud console likely converted your disk volume to an in-memory volume. This causes your disk writes to be written into memory, resulting in your container running out of memory. To fix this, redeploy your service using gcloud CLI again and make sure that your YAML file specifies medium: Disk under volumes.
• If you see slow network speeds when downloading a large amount of data to your ephemeral disk, follow the steps to turn on Direct VPC. If Direct VPC is not enabled, you will see slower network transfer speeds.