Using ephemeral disks on Cloud Run for temporary storage
Writing files to disk on Cloud Run has a catch: by default, the entire writable container filesystem lives in memory, so every byte you write inside the container counts directly against its memory limit. If your app downloads a 1 GiB video file before transcoding it, a container instance with 512 MiB RAM runs out of memory and gets shut down. Cloud Run's ephemeral disks feature (generally available as of November 2026) solves this with dedicated local storage that doesn't consume container memory.
Below, I'll show you how to mount an
ephemeral disk volume
at /tmp on a Cloud Run service, verify how it behaves compared to the
container's in-memory root filesystem, and check the quotas and pricing.
Prerequisites
First, set your Google Cloud project ID and target region in your shell:
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="europe-west1"
Next, enable the Cloud Run Admin API along with the Cloud OS Login API required by
Cloud Run SSH
(used only in this demo to inspect the container's filesystems; ephemeral disks
themselves don't require SSH or oslogin.googleapis.com):
gcloud services enable \
run.googleapis.com \
oslogin.googleapis.com \
--project="$PROJECT_ID"
Operation "operations/acat.p2-123456789012-ffbbba2c-ecc4-4aee-8acb-09a45672ee69" finished successfully.
Deploy a service with an ephemeral disk
With both APIs enabled, deploy a service called disk-demo with a 10 GiB
ephemeral disk mounted at /tmp. Rather than building a custom image for
this demo, I use the public nginx image from Docker Hub because it can be
deployed as a Cloud Run service and includes standard Linux commands (df
and dd) for testing the disk over SSH:
gcloud beta run deploy disk-demo \
--image=nginx \
--port=80 \
--memory=512Mi \
--max=10 \
--add-volume=name=tmp-disk,type=ephemeral-disk,size=10Gi \
--add-volume-mount=volume=tmp-disk,mount-path=/tmp \
--ssh \
--region="$REGION" \
--project="$PROJECT_ID" \
--quiet
Deploying container to Cloud Run service [disk-demo] in project [YOUR_PROJECT_ID] region [europe-west1]
Deploying new service...
Creating Revision...done
Routing traffic...done
Done.
Service [disk-demo] revision [disk-demo-00001-58s] has been deployed and is serving 100 percent of traffic.
Service URL: https://disk-demo-123456789012.europe-west1.run.app
Proxy locally with: gcloud run services proxy disk-demo --region europe-west1 --project YOUR_PROJECT_ID
-
--add-volumeand--add-volume-mountcreate a 10 GiBephemeral-diskvolume namedtmp-diskand mount it at/tmpinside the container. -
--port=80points Cloud Run's startup check at port80, where NGINX listens by default, instead of Cloud Run's default port8080. -
--max=10caps the service at 10 instances so10 GiB * 10 instancesfits within a project's default 100 GiB regional ephemeral disk quota. -
--sshenables Cloud Run SSH (in preview as of November 2026), which is why this command usesgcloud beta; ephemeral disks work with standardgcloud run deploy. --quietskips the interactive prompts.
Mounting an ephemeral disk at /tmp routes temporary files straight to local
disk without changing application code. Any library or CLI tool that writes to
/tmp by default (such as Python's tempfile or
ffmpeg) uses the disk automatically.
As of November 2026, you can attach ephemeral disks to Cloud Run services, jobs, and
worker pools using the same --add-volume and
--add-volume-mount flags (Cloud Run instances
don't support ephemeral disks yet).
Inspect and test both filesystems over SSH
To see how /tmp and the root filesystem handle large writes, connect to
disk-demo using SSH, check both mounts with df, and write a 1
GiB file first to /tmp and then to /.
Start by opening an SSH session to a running instance of the service
disk-demo (Cloud Run starts an instance if none is running), which drops
you into a root@localhost shell:
gcloud beta run services ssh disk-demo \
--region="$REGION" \
--project="$PROJECT_ID"
Project: YOUR_PROJECT_ID
Region: europe-west1
Service: disk-demo
Revision: disk-demo-00001-58s
Instance: 00e8a408bdd9...
Container: nginx-1
Image: mirror.gcr.io/library/nginx@sha256:5cb45c657131...
root@localhost:~#
Inside that shell, run df -hT to compare the container's root directory
(/) and the mounted ephemeral disk (/tmp):
df -hT / /tmp
Filesystem Type Size Used Avail Use% Mounted on
none overlay 512M 36K 512M 1% /
/dev/mapper/md0 ext4 9.8G 2.1M 9.3G 1% /tmp
The root directory (/) is an overlay filesystem capped at
512M (matching --memory=512Mi), while /tmp is a
separate ext4 block device (/dev/mapper/md0) with
9.8G of formatted space.
Verify that writes to /tmp stay out of memory by writing 1 GiB of zeros
(twice the container's 512 MiB memory limit) to /tmp/test.bin:
dd if=/dev/zero of=/tmp/test.bin bs=1M count=1024
1024+0 records in
1024+0 records out
1073741824 bytes (1.1 GB, 1.0 GiB) copied, 3.11281 s, 345 MB/s
dd writes all 1 GiB to /tmp/test.bin in about three seconds
(your elapsed time and throughput will vary), and the 512 MiB container stays up because
the file lands on the ephemeral disk. Re-run df -hT to check space usage on
both mounts:
df -hT / /tmp
Filesystem Type Size Used Avail Use% Mounted on
none overlay 512M 36K 512M 1% /
/dev/mapper/md0 ext4 9.8G 1.1G 8.3G 11% /tmp
Used space on /tmp grew from 2.1M to 1.1G, while
/ stayed at 36K. Now run that same 1 GiB write against
/test.bin on the root filesystem (this command is expected to fail and
disconnect your SSH session once the write exhausts the container's memory):
dd if=/dev/zero of=/test.bin bs=1M count=1024
ERROR: (gcloud.beta.run.start-iap-tunnel) Unexpected error while reconnecting. Check logs for more details.
Connection to cloud-run-default closed by remote host.
Connection to cloud-run-default closed.
client_loop: send disconnect: Broken pipe
ERROR: (gcloud.beta.run.services.ssh) [/usr/local/bin/ssh] exited with return code [255].
Partway through the write, /test.bin fills the container's remaining memory
above 512 MiB, shutting down the instance and returning you to your local shell. Query
the Cloud Run system logs for the service disk-demo to confirm the cause:
gcloud logging read 'resource.type="cloud_run_revision" '\
'AND resource.labels.service_name="disk-demo" '\
'AND logName=~"run\.googleapis\.com%2F.*system$"' \
--project="$PROJECT_ID" \
--limit=10 \
--format="table(timestamp, textPayload)"
TIMESTAMP TEXT_PAYLOAD
2026-11-16T20:37:51.311016Z Container terminated on signal 9.
2026-11-16T20:37:51.259534Z Out-of-memory event detected in container
...
Filtering logName on Cloud Run's system log streams shows
Out-of-memory event detected in container right before Cloud Run stops the
container with signal 9 (SIGKILL).
Compare ephemeral disks and the root filesystem
The diagram below compares those two writes on a 512 MiB instance with a 10 GiB
ephemeral disk at /tmp. Writing to /tmp (left) stores the 1
GiB file on the local ext4 disk without using container RAM, leaving
roughly 9 GiB free. Writing outside /tmp (right) stores the file in the
RAM-backed overlay filesystem alongside application and system memory,
exceeding 512 MiB and shutting down the instance:

If a write to /tmp ever exceeds the 10Gi disk itself, Linux
returns a standard No space left on device (ENOSPC) error that
your code can catch instead of crashing the instance. Cloud Run formats each volume as
ext4 and mounts it with 0777 (drwxrwxrwx)
permissions so non-root USER containers can read and write without
permission changes.
Disks are isolated to one Cloud Run instance
Each ephemeral disk is isolated to a single instance: Cloud Run creates a fresh volume
when an instance starts and permanently deletes it when the instance stops or crashes
(on normal shutdowns, containers receive SIGTERM and have 10 seconds before
SIGKILL to upload any final output to persistent storage such as Cloud
Storage).
A Cloud Run instance is a microVM that can run more than one container (a main container and one or more sidecars). Multiple containers in the same instance can mount the same ephemeral disk volume and both read from and write to it to share files.
Export the YAML configuration
To see how Cloud Run represents the volume and mount in the service manifest, export the
YAML configuration for the service disk-demo:
gcloud run services describe disk-demo \
--region="$REGION" \
--project="$PROJECT_ID" \
--format=export
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
# ...
name: disk-demo
spec:
template:
metadata:
annotations:
# ...
run.googleapis.com/execution-environment: gen2
spec:
# ...
containers:
- image: nginx
# ...
volumeMounts:
- mountPath: /tmp
name: tmp-disk
volumes:
- emptyDir:
medium: Disk
sizeLimit: 10Gi
name: tmp-disk
Under spec.template.spec, volumes declares a temporary
emptyDir volume named tmp-disk backed by local disk (medium: Disk) and capped at 10Gi (sizeLimit: 10Gi), while
volumeMounts mounts that volume at /tmp inside the
nginx container.
Quotas and limits
Ephemeral disks are generally available across all Cloud Run regions, with a few limits to keep in mind:
- Ephemeral disks require Cloud Run's second-generation execution environment, which Cloud Run selects automatically when you deploy a new service with an ephemeral disk (and always uses for jobs and worker pools).
-
You can mount ephemeral disks at any directory path except
/(root) and/dev,/proc,/sys, or their subdirectories. -
Under Cloud Run's
storage and instance limits, each volume can be sized from
1Gito100Gi, and each instance can mount up to 10 ephemeral disk volumes. By default, total ephemeral disk capacity is capped at 10 GiB per instance unless you request a quota increase.
Comparing ephemeral disk and memory pricing
Without an ephemeral disk, holding large temporary files in container memory means provisioning extra RAM, which costs roughly 65 to 80 times more per GiB than ephemeral disk storage. Because Cloud Run caps memory at 4 GiB per vCPU, adding 10 GiB of RAM to a 1-vCPU instance also forces you to step up to 4 vCPUs and pay for CPU capacity your workload doesn't need.
Cloud Run bills ephemeral disks for the full provisioned size while an instance is
running (dropping to $0 when scaled to zero, with no monthly free tier).
Based on the
Cloud Run pricing page
for europe-west1 as of November 2026 ($0.08 per GiB-month),
keeping a 10 GiB ephemeral disk active for 100 instance-hours costs about
$0.11, compared to $7.20 to $9.00 for 10 GiB of
RAM before counting extra vCPUs (example calculations could contain mistakes; check the
pricing page for current regional rates).
Clean up
Delete the service disk-demo when you're finished testing (passing
--quiet to skip the confirmation prompt):
gcloud run services delete disk-demo \
--region="$REGION" \
--project="$PROJECT_ID" \
--quiet
Deleting [disk-demo]...done.
Deleted service [disk-demo].