Cloud Storage volume mounts for services

This page shows how to mount a Cloud Storage bucket as a storage volume, using Cloud Run volume mounts.

Mounting the bucket as a volume in Cloud Run presents the bucket content as files in the container file system, which allows use of standard file system operations and libraries to access that file system.

Limitations

Cloud Run uses Cloud Storage FUSE for this volume mount. So there are a few things to keep in mind when mounting a Cloud Storage bucket as a volume:

  • Cloud Storage FUSE does not provide concurrency control for multiple writes (file locking) to the same file. When multiple writes try to replace a file, the last write wins and all previous writes are lost.
  • Cloud Storage FUSE is not a fully POSIX-compliant file system. For more details, refer to the Cloud Storage FUSE documentation.

Before you begin

You need a Cloud Storage bucket to mount as the volume.

Mount a Cloud Storage volume

You can mount multiple buckets at different mount paths. You can also mount a volume to more than one container using the same or different mount paths across containers.

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

Command line

Note: we show the gcloud beta run services update command but you can also use the the gcloud beta run deploy command with the same parameters as shown.

  • To add a volume and mount it:

    gcloud beta run services update SERVICE \
    --execution-environment gen2 \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

    Replace:

    • SERVICE with the name of your service.
    • MOUNT_PATH with the relative path where you are mounting the volume, for example, /cache.
    • VOLUME_NAME with any name you want for your volume. The VOLUME_NAME value is used to map the volume to the volume mount.
    • BUCKET_NAME with the name of your Cloud Storage bucket.
  • To mount your volume as a read-only volume:

--add-volume=name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,readonly=true
  • If you are using multiple containers, first specify your volume(s), then specify the volume mount(s) for each container:

    gcloud beta run services update SERVICE \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME \
    --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

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. Update as needed.

    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
      name: SERVICE
      annotations:
        run.googleapis.com/launch-stage: BETA
    spec:
      template:
        metadata:
          annotations:
            run.googleapis.com/execution-environment: gen2
        spec:
          containers:
          - image: IMAGE_URL
            volumeMounts:
            - name: VOLUME_NAME
              mountPath: MOUNT_PATH
          volumes:
          - name: VOLUME_NAME
            csi:
              driver: gcsfuse.run.googleapis.com
              readOnly: IS_READ_ONLY
              volumeAttributes:
                bucketName: BUCKET_NAME

    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 REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • MOUNT_PATH with the relative path where you are mounting the volume, for example, /cache.
    • VOLUME_NAME with any name you want for your volume. The VOLUME_NAME value is used to map the volume to the volume mount.
    • IS_READ_ONLY with True to make the volume read-only, or False to allow writes.
    • BUCKET_NAME with the name of the Cloud Storage bucket.
  3. Replace the service with its new configuration using the following command:

    gcloud run services replace service.yaml