[Video](https://www.youtube.com/watch?v=8pu2fVQbbNs)

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. After you mount the bucket
as a volume, you access the bucket as if it were a directory on your local file
system, using your programming language's file system operations and libraries
instead of using Google API Client Libraries.

You can mount your volume as read-only and you can also specify
[mount options](https://docs.cloud.google.com/run/docs/configuring/services/cloud-storage-volume-mounts.md.txt#volume-mount-options) for your volume.

> [!IMPORTANT]
> **Important:** You don't need to install Cloud Storage FUSE in your container or modify the container in any way to use this feature.

## Memory requirements

Cloud Storage volume mounts use the Cloud Run [container memory](https://docs.cloud.google.com/run/docs/configuring/services/memory-limits.md.txt) for the following activities:

<br />

- For all Cloud Storage FUSE caching, Cloud Run uses the stat
  cache setting with a [Time-to-live (TTL)](https://en.wikipedia.org/wiki/Time_to_live)
  of 60 seconds by default.
  The default maximum size of the stat cache is 32 MB, the default maximum
  size of the type cache is 4 MiB.

- When reading from Cloud Storage, Cloud Storage FUSE makes API calls to read an
  object directly, without downloading the whole file to a local directory.
  Cloud Storage FUSE establishes a TCP connection, and reads back the entire Cloud Storage
  object, or just portions of the file you specify in your application or the operating
  system through an offset. When reading,
  Cloud Storage FUSE also consumes memory other than stat and type caches,
  such as a 1 MiB array for every file it reads, and for `goroutines`.

- When writing to Cloud Storage, Cloud Storage FUSE supports `streaming-writes`, a
  write path, by default. Cloud Storage FUSE uploads data directly to Cloud Storage
  without fully staging the file. Each file you open for streaming writes
  consumes approximately 64 MiB of memory during the upload process. This reduces
  both latency and disk space usage, making it particularly beneficial for
  large, sequential writes.

> [!NOTE]
> **Note:** For background information on caching, see the Cloud Storage FUSE [Read/Write](https://github.com/GoogleCloudPlatform/gcsfuse/blob/master/docs/semantics.md) page.

## Limitations

Since Cloud Run uses [Cloud Storage FUSE](https://docs.cloud.google.com/storage/docs/gcs-fuse) for
this volume mount, 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](https://docs.cloud.google.com/storage/docs/gcs-fuse).

### Disallowed paths

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

## Before you begin

You need a [Cloud Storage bucket](https://docs.cloud.google.com/storage/docs/creating-buckets.md.txt) to mount as the volume.

For optimal read/write performance to Cloud Storage, see [Optimizing Cloud Storage FUSE network bandwidth performance](https://docs.cloud.google.com/run/docs/configuring/services/cloud-storage-volume-mounts.md.txt#network-bandwidth).

### Required roles


To get the permissions that
you need to configure Cloud Storage volume mounts,

ask your administrator to grant you the
following IAM roles:

- [Cloud Run Developer](https://docs.cloud.google.com/iam/docs/roles-permissions/run.md.txt#run.developer) (`roles/run.developer`) on the Cloud Run service
- [Service Account User](https://docs.cloud.google.com/iam/docs/roles-permissions/iam.md.txt#iam.serviceAccountUser) (`roles/iam.serviceAccountUser`) on the service identity


To get the permissions that your [service identity](https://docs.cloud.google.com/run/docs/configuring/services/service-identity.md.txt)
needs to access the file and Cloud Storage bucket, ask your administrator
to grant the service identity the
[Storage Object Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/storage.md.txt#storage.objectViewer)
(`roles/storage.objectViewer`) role. If the service identity needs to also
perform write operations in a bucket, grant the
[Storage Object User](https://docs.cloud.google.com/iam/docs/roles-permissions/storage.md.txt#storage.objectUser)
(`roles/storage.objectUser`) role instead.

For more details on Cloud Storage roles and permissions, see
[IAM for Cloud Storage](https://docs.cloud.google.com/storage/docs/access-control/iam.md.txt).

For a list of IAM roles and permissions that are associated with
Cloud Run, see
[Cloud Run IAM roles](https://docs.cloud.google.com/run/docs/reference/iam/roles.md.txt)
and [Cloud Run IAM permissions](https://docs.cloud.google.com/run/docs/reference/iam/permissions.md.txt).
If your Cloud Run service interfaces with
Google Cloud APIs, such as Cloud Client Libraries, see the
[service identity configuration guide](https://docs.cloud.google.com/run/docs/configuring/services/service-identity.md.txt).
For more information about granting roles, see
[deployment permissions](https://docs.cloud.google.com/run/docs/reference/iam/roles.md.txt#additional-configuration)
and [manage access](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).

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

<br />

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


Volume mounts require the second generation [execution environment](https://docs.cloud.google.com/run/docs/about-execution-environments).
Cloud Run automatically selects the second generation execution environment for your service if no execution environment is explicitly [configured](https://docs.cloud.google.com/run/docs/configuring/execution-environments.md.txt).

### Console

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

   [Go to Cloud Run](https://console.cloud.google.com/run)
2. Select **Services** from the Cloud Run navigation menu:

   1. If you are configuring a new service, click **Deploy container** and
      fill out the initial service settings page. Then click
      **Containers, Networking, Security** to expand the service configuration page,
      and click **Volumes**.

   2. If you are configuring an existing service, click the service, then
      click the **Containers** tab.

3. Click **Mount volume**.

4. Select **Cloud Storage bucket** as the volume type.

5. In the **Mount path** field, enter the path where you want to mount the
   volume.

6. Browse and select the Cloud Storage bucket or a specific directory to be
   used for the volume. Optionally, create a new bucket.

7. If you want to make the bucket read-only, select the **Read-only**
   checkbox.

8. Optionally, expand **Mount options** to specify mount options.

9. Click **Save**.

10. Click **Create** for a new service. Click **View diff \& redeploy** , then **Deploy changes** for an existing service.

### gcloud

- To add a volume and mount it:

  ```bash
  gcloud run deploy SERVICE \
    --image IMAGE_URL \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,readonly=READ_ONLY
  ```

  Replace the following:
  - <var translate="no">SERVICE</var>: the name of your service.
  - `IMAGE_URL`: a reference to the container image, for example, `us-docker.pkg.dev/cloudrun/container/hello:latest`. If you use Artifact Registry, the [repository](https://docs.cloud.google.com/artifact-registry/docs/repositories/create-repos.md.txt#docker) <var translate="no">REPO_NAME</var> must already be created. The URL follows the format of `LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG`
  - <var translate="no">MOUNT_PATH</var>: the relative path where you are mounting the volume---for example, `/mnt/my-volume`.
  - <var translate="no">BUCKET_NAME</var>: the name of your Cloud Storage bucket.
  - <var translate="no">READ_ONLY</var>: `true` to make the volume read-only, or `false` to allow writes.
- If you are using multiple containers, first specify your volume(s), then
  specify the volume mount(s) for each container:

  ```bash
  gcloud 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

1. If you are creating a new service, skip this step.
   If you are updating an existing service, download its [YAML configuration](https://docs.cloud.google.com/run/docs/reference/yaml/v1.md.txt):

   ```bash
   gcloud run services describe SERVICE --format export > service.yaml
   ```
2. Update as needed.

   ```yaml
   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: SERVICE
   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
   ```

   <br />

   Replace the following:
   - `IMAGE_URL`: a reference to the container image, for example, `us-docker.pkg.dev/cloudrun/container/hello:latest`. If you use Artifact Registry, the [repository](https://docs.cloud.google.com/artifact-registry/docs/repositories/create-repos.md.txt#docker) <var translate="no">REPO_NAME</var> must already be created. The URL follows the format of `LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG` .
   - <var translate="no">MOUNT_PATH</var>: the relative path where you are mounting the volume---for example, `/mnt/my-volume`.
   - <var translate="no">VOLUME_NAME</var>: any name you want for your volume. The <var translate="no">VOLUME_NAME</var> value is used to map the volume to the volume mount.
   - <var translate="no">IS_READ_ONLY</var>: `True` to make the volume read-only, or `False` to allow writes.
   - <var translate="no">BUCKET_NAME</var>: the name of the Cloud Storage bucket.
3. Create or update the service using the following command:

   ```bash
   gcloud run services replace service.yaml
   ```

   The `gcloud run services replace` command defaults to using `service.yaml` file if present.

### Terraform

To learn how to apply or remove a Terraform configuration, see
[Basic Terraform commands](https://docs.cloud.google.com/docs/terraform/basic-commands.md.txt).
Add the following to a [`google_cloud_run_v2_service`](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service) resource in your Terraform configuration:  

```terraform
  resource "google_cloud_run_v2_service" "default" {
    name     = "SERVICE"
    location = "REGION"

    template {
      containers {
        image = "IMAGE_URL"
        volume_mounts {
          name = "VOLUME_NAME"
          mount_path = "MOUNT_PATH"
        }
      }

      volumes {
        name = "VOLUME_NAME"
        gcs {
          bucket = google_storage_bucket.default.name
          read_only = IS_READ_ONLY
        }
      }
    }
  }

  resource "google_storage_bucket" "default" {
    name     = "BUCKET_NAME"
    location = "REGION"
  }
```

Replace the following:

- <var translate="no">SERVICE</var>: the name of your Cloud Run service.
- <var translate="no">REGION</var>: the Google Cloud region.
- `IMAGE_URL`: a reference to the container image, for example, `us-docker.pkg.dev/cloudrun/container/hello:latest`. If you use Artifact Registry, the [repository](https://docs.cloud.google.com/artifact-registry/docs/repositories/create-repos.md.txt#docker) <var translate="no">REPO_NAME</var> must already be created. The URL follows the format of `LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG` .
- <var translate="no">VOLUME_NAME</var>: any name you want for your volume. The <var translate="no">VOLUME_NAME</var> value is used to map the volume to the volume mount.
- <var translate="no">MOUNT_PATH</var>: the relative path where you are mounting the volume---for example, `/mnt/my-volume`.
- <var translate="no">IS_READ_ONLY</var>: `True` to make the volume read-only, or `False` to allow writes.
- <var translate="no">BUCKET_NAME</var>: the name of the Cloud Storage bucket.

### Compose

To specify volume mounts in your `compose.yaml` file, add the `volumes`
attribute to your service definition. Top-level `volumes` or `configs` are
mapped to Cloud Storage buckets.

```yaml
  services:
    web:
      image: IMAGE
      volumes:
        - VOLUME_NAME:MOUNT_PATH
  volumes:
    VOLUME_NAME:
```

Replace the following:

- <var translate="no">IMAGE</var>: the URL of your container image.
- <var translate="no">VOLUME_NAME</var>: the name of the volume.
- <var translate="no">MOUNT_PATH</var>: the path where you want to mount the volume.

**Deploy the services**

1. To deploy the services, run the `gcloud run compose up` command:

   ```yaml
   gcloud run compose up compose.yaml
   ```
2. Respond `y` to any prompts to install required components or to enable
   APIs.

3. Optional: [Make your service public](https://docs.cloud.google.com/run/docs/authenticating/public.md.txt)
   if you want to allow unauthenticated access to the service.

After deployment, the Cloud Run service URL is displayed. Copy
this URL and paste it into your browser to view the running container. You can
disable the default authentication from the Google Cloud console.

## 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`.

### Nodejs


Use the File System module to create a new file or append to an existing file
in the volume, `/mnt/my-volume`:

```
var fs = require('fs');
fs.appendFileSync('/mnt/my-volume/sample-logfile.txt', 'Hello logs!', { flag: 'a+' });
```

<br />

### Python


Write to a file kept in the volume, `/mnt/my-volume`:

```
f = open("/mnt/my-volume/sample-logfile.txt", "a")
```

<br />

### Go


Use the `os` package to create a new file kept in the volume, `/mnt/my-volume`:

```
f, err := os.Create("/mnt/my-volume/sample-logfile.txt")
```

<br />

### Java


Use the `Java.io.File` class to create a log file in the volume, `/mnt/my-volume`:

```
import java.io.File;
File f = new File("/mnt/my-volume/sample-logfile.txt");
```

<br />

## Volume configuration using mount options

You can optionally use mount options to configure various properties of your volume mount. The
[available mount options](https://docs.cloud.google.com/run/docs/configuring/services/cloud-storage-volume-mounts.md.txt#available-options) allow you to configure cache
settings, mount a specific directory, enable debug logging, and other
behaviors.

### Specify mount options

You can specify [mount options](https://docs.cloud.google.com/run/docs/configuring/services/cloud-storage-volume-mounts.md.txt#available-options) using the Google Cloud console, the Google Cloud CLI, YAML, or Terraform. The mount options are separated by semicolons (`;`) in Google Cloud CLI and are separated by commas in YAML, as shown in the following tabs:

### Console


To specify mount options for an existing volume:

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

   [Go to Cloud Run](https://console.cloud.google.com/run/services)
2. Click the service to open the service details page.

3. Click the **Containers** tab.

   1. Click the edit icon next to the volume you want to edit.
   2. Expand **Mount options**.
   3. Configure mount options by updating the appropriate fields or by adding [mount options manually](https://docs.cloud.google.com/run/docs/configuring/services/cloud-storage-volume-mounts.md.txt#common-mount-options).
   4. Click **Save**.
4. Click **View diff \& redeploy** , then **Deploy changes**.

### gcloud


To add a volume and mount it with mount options:

```bash
  gcloud run deploy SERVICE \
      --image IMAGE_URL \
      --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,readonly=READ_ONLY,mount-options="OPTION_1=VALUE_1;OPTION_N=VALUE_N"
```

Replace the following:

- <var translate="no">SERVICE</var>: the name of your service.
- `IMAGE_URL`: a reference to the container image, for example, `us-docker.pkg.dev/cloudrun/container/hello:latest`. If you use Artifact Registry, the [repository](https://docs.cloud.google.com/artifact-registry/docs/repositories/create-repos.md.txt#docker) <var translate="no">REPO_NAME</var> must already be created. The URL follows the format of `LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG`
- <var translate="no">MOUNT_PATH</var>: the relative path where you are mounting the volume---for example, `/cache`.
- <var translate="no">BUCKET_NAME</var>: the name of your Cloud Storage bucket.
- <var translate="no">READ_ONLY</var>: `true` to make the volume read-only, or `false` to allow writes.
- <var translate="no">OPTION_1</var>: the first mount option. Note that you can specify as many mount options as you need, with each mount option and value pair separated by a semicolon.
- <var translate="no">VALUE_1</var>: the setting you want for the first mount option.
- <var translate="no">OPTION_N</var>: the next mount option.
- <var translate="no">VALUE_N</var>: the setting for the next mount option.

### YAML

1. If you are creating a new service, skip this step.
   If you are updating an existing service, download its [YAML configuration](https://docs.cloud.google.com/run/docs/reference/yaml/v1.md.txt):

   ```bash
   gcloud run services describe SERVICE --format export > service.yaml
   ```
2. Update as needed.

   ```yaml
   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: SERVICE
   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
               mountOptions: OPTION_1=VALUE_1,OPTION_N=VALUE_N
   ```

   <br />

   Replace the following:
   - `IMAGE_URL`: a reference to the container image, for example, `us-docker.pkg.dev/cloudrun/container/hello:latest`. If you use Artifact Registry, the [repository](https://docs.cloud.google.com/artifact-registry/docs/repositories/create-repos.md.txt#docker) <var translate="no">REPO_NAME</var> must already be created. The URL follows the format of `LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG`
   - <var translate="no">MOUNT_PATH</var>: the relative path where you are mounting the volume---for example, `/cache`.
   - <var translate="no">VOLUME_NAME</var>: any name you want for your volume. The <var translate="no">VOLUME_NAME</var> value is used to map the volume to the volume mount.
   - <var translate="no">IS_READ_ONLY</var>: `True` to make the volume read-only, or `False` to allow writes.
   - <var translate="no">BUCKET_NAME</var>: the name of the Cloud Storage bucket.
   - <var translate="no">OPTION_1</var>: the first mount option. Note that you can specify as many mount options as you need, with each mount option and value pair separated by a comma.
   - <var translate="no">VALUE_1</var>: the setting you want for the first mount option.
   - <var translate="no">OPTION_N</var>: the next mount option.
   - <var translate="no">VALUE_N</var>: the setting for the next mount option.
3. Create or update the service using the following command:

   ```bash
   gcloud run services replace service.yaml
   ```

   The `gcloud run services replace` command defaults to using `service.yaml` file if present.

### Terraform

<br />

To learn how to apply or remove a Terraform configuration, see
[Basic Terraform commands](https://docs.cloud.google.com/docs/terraform/basic-commands.md.txt).
Add the following to a [`google_cloud_run_v2_service`](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service) resource in your Terraform configuration:  

<br />

```terraform
  resource "google_cloud_run_v2_service" "default" {
    name     = "SERVICE"
    location = "REGION"

    template {
      containers {
        image = "IMAGE_URL"
        volume_mounts {
          name = "VOLUME_NAME"
          mount_path = "MOUNT_PATH"
        }
      }

      volumes {
        name = "VOLUME_NAME"
        gcs {
            bucket = google_storage_bucket.default.name
            read_only = IS_READ_ONLY
            mount_options = ["OPTION_1=VALUE_1", "OPTION_N=VALUE_N", "OPTION_O"]
        }
      }
    }
  }
```

Replace the following:

- <var translate="no">SERVICE</var>: the name of your Cloud Run service.
- <var translate="no">REGION</var>: the Google Cloud region.
- `IMAGE_URL`: a reference to the container image that contains the worker pool, such as `us-docker.pkg.dev/cloudrun/container/worker-pool:latest`
- <var translate="no">VOLUME_NAME</var>: any name you want for your volume. The <var translate="no">VOLUME_NAME</var> value is used to map the volume to the volume mount.
- <var translate="no">MOUNT_PATH</var>: the relative path where you are mounting the volume---for example, `/mnt/my-volume`.
- <var translate="no">IS_READ_ONLY</var>: `True` to make the volume read-only, or `False` to allow writes.
- <var translate="no">BUCKET_NAME</var>: the name of the Cloud Storage bucket.
- <var translate="no">OPTION_1</var>: the first mount option. Note that you can specify as many mount options as you need, with each mount option and value pair separated by a comma.
- <var translate="no">VALUE_1</var>: the setting you want for the first mount option.
- <var translate="no">OPTION_N</var>: the second mount option, if applicable.
- <var translate="no">VALUE_N</var>: the setting for the second mount option.
- <var translate="no">OPTION_O</var>: the third mount option, if applicable. Some mount options don't have a value.

### Commonly used mount options

Mount options are commonly used to:

- Configure cache settings
- Mount only a specific directory from the Cloud Storage bucket
- Configure the ownership of the volume (`uid`, `gid`)
- Turn off implicit directories
- Specify debug logging levels.

#### Configure caching settings

> [!NOTE]
> **Note:** Refer to the [Cloud Storage FUSE caching documentation](https://docs.cloud.google.com/storage/docs/gcsfuse-cache) for more information on cache options.

You can change the caching settings for your volume by setting the
caching-related mount options. The following table lists the settings, along
with the default Cloud Run values:

| Cache setting | Description | Default |
|---|---|---|
| `cache-dir` | The in-memory volume name to use as the underlying directory to persist files from your Cloud Storage bucket in the format `cr-volume:{volume name}`. For example, if you have an in-memory volume named `in-memory-1` that you want to use as the cache directory, specify `cr-volume:in-memory-1`. For instructions on setting up in-memory volumes, see [Configure in-memory volume mounts for services](https://docs.cloud.google.com/run/docs/configuring/services/in-memory-volume-mounts.md.txt). When you enable these features, Cloud Run changes the resource accounting of the Cloud Storage FUSE process and counts this towards the container memory limits. To increase the container memory limit, see [Configure memory limits for services](https://docs.cloud.google.com/run/docs/configuring/services/memory-limits.md.txt#configure-services). |   |
| `file-cache-download-chunk-size-mb` | Specifies the size of each read request in MiB that each goroutine makes to Cloud Storage when downloading the object into the file cache. | 200 |
| `file-cache-enable-parallel-downloads` | Accelerates reads of large files by using the file cache directory as a prefetch buffer using multiple workers to download multiple parts of a file in parallel. | true |
| `file-cache-max-parallel-downloads` | The maximum number of goroutines that can be spawned at any given time across all the download jobs of files. | Twice the number of CPU cores on your machine or 16, whichever is higher. |
| `file-cache-parallel-downloads-per-file` | The number of concurrent download requests per file. | 16 |
| `file-cache-cache-file-for-range-read` | Determines whether the full object should be downloaded asynchronously and stored in the Cloud Storage FUSE cache directory when the first read is completed from a non-zero offset. | false |
| `stat-cache-max-size-mb` | Maximum size in mebibytes (MiB) that the stat cache can use. The stat cache is always entirely kept in memory, impacting memory consumption. Specify a value of `32` if your workload involves up to 20,000 files. If your workload uses more than 20,000 files, increase the size by values of `10` for every additional 6,000 files, where the stat cache uses an average of 1,500 bytes per file. To let the stat cache use as much memory as needed, specify a value of `-1`. To disable the stat cache, specify a value of `0`. | 32 |
| `type-cache-max-size-mb` | The maximum size in MiB per directory that the type cache can use. The type cache is always entirely kept in memory, impacting memory consumption. Specify a value of `4` if the maximum number of files within a single directory from the bucket you're mounting contains 20,000 files or less. If the maximum number of files within a single directory that you're mounting contains more than 20,000 files, increase the value by `1` for every 5,000 files, which is an average of around 200 bytes per file. To let the type cache use as much memory as needed, specify a value of `-1`. To disable the type cache, specify a value of `0`. | 4 |

The following Google Cloud CLI command sets the `metadata-cache-ttl-secs` to 120 seconds and increases the stat and type cache capacity to `52` and `7` MiB, respectively:

```bash
gcloud run services update SERVICE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="metadata-cache-ttl-secs=120;stat-cache-max-size-mb=52;type-cache-max-size-mb=7"
    
```

Replace the following:

- <var translate="no">SERVICE</var>: the name of your service.
- <var translate="no">BUCKET_NAME</var>: the name of your Cloud Storage bucket.
- <var translate="no">MOUNT_PATH</var>: the relative path where you are mounting the volume---for example, `/cache`.

#### Enable debug logging

By default, Cloud Storage FUSE logs events that have `Info` or higher. You can change the logging settings using any of the following log-severity levels, listed
in order from lowest to highest:

- `trace`
- `debug`
- `info`
- `warning`
- `error`
- To turn off all logging, specify the value `off`.

When you specify a severity level, Cloud Storage FUSE generates logs for
events that have a severity level equal to or higher than the specified severity. For example, when you specify the `warning` level, Cloud Storage FUSE generates logs for warnings
and errors.

Setting log severity to levels higher than `info` can impact performance and generate a large amount of logging data, so we recommend doing this only as needed. For compatibility with cloud logging, the log format is `text` format, and `json` format is not supported.

The following command line turns on debug logging:

```bash
gcloud run services update SERVICE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="log-severity=debug"
```

Replace the following:

- <var translate="no">SERVICE</var>: the name of your service.
- <var translate="no">BUCKET_NAME</var>: the name of your Cloud Storage bucket.
- <var translate="no">MOUNT_PATH</var>: the relative path where you are mounting the volume---for example, `/cache`.

#### Disable implicit directories

To make Cloud Storage appear more like a standard file system, Cloud Run enables implicit directories by default when mounting a Cloud Storage bucket. You can turn implicit directories off using the `implicit-dirs` mount option. Disabling implicit directories can improve performance and cost, but comes with compatibility tradeoffs.

The implicit directories feature enables Cloud Run to recognize pre-existing Cloud Storage files whose filenames mimic a directory structure, such as `/mydir/myfile.txt`. If you disable implicit directories, Cloud Run won't be able to list or read such files.

Turning off implicit directories reduces the number of requests to Cloud Storage, which might improve your application performance and cost. Read the Cloud Storage FUSE [Files and directories](https://github.com/GoogleCloudPlatform/gcsfuse/blob/master/docs/semantics.md#files-and-directories) documentation to learn more.

The following command line disables implicit directories:

```bash
gcloud run services update SERVICE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="implicit-dirs=false"
```

Replace the following:

- <var translate="no">SERVICE</var>: the name of your service.
- <var translate="no">BUCKET_NAME</var>: the name of your Cloud Storage bucket.
- <var translate="no">MOUNT_PATH</var>: the relative path where you are mounting the volume---for example, `/cache`.

#### Mount a specific directory inside your Cloud Storage bucket

By default, Cloud Run mounts the entire Cloud Storage bucket, which
gives Cloud Run services access to all its contents. In some cases
you might want to mount only a specific directory. For example, in the case where
the bucket contains a large number of files, mounting a specific directory can
improve performance.

You can also implement this for isolation purposes where you need different services
to have access to different directories in the storage bucket.

The following command line specifies the directory to mount:

```bash
gcloud run services update SERVICE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="only-dir=images"
```

Replace the following:

- <var translate="no">SERVICE</var>: the name of your service.
- <var translate="no">BUCKET_NAME</var>: the name of your Cloud Storage bucket.
- <var translate="no">MOUNT_PATH</var>: the relative path where you are mounting the volume---for example, `/cache`.

#### Set the volume `UID` and `GID`

Use the `uid` and `gid` mount options to change the User Identifier and Group Identifier for the volume. This is useful if you want to set ownership of the
file to a specific user or group matching the identity of one or multiple running containers. By default, volumes are owned by root.

The following command line sets `uid` and `gid`:

```bash
gcloud run services update SERVICE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="uid=UID;gid=GID"
```

Replace the following:

- <var translate="no">SERVICE</var>: the name of your service.
- <var translate="no">MOUNT_PATH</var>: the relative path where you are mounting the volume---for example, `/cache`.
- <var translate="no">BUCKET_NAME</var>: the name of your Cloud Storage bucket.
- <var translate="no">UID</var>: user ID to mount the volume as.
- <var translate="no">GID</var>: group ID to mount the volume as.

### Set other mount options

The following is the complete list of all of the mount options supported by Cloud Run.

**Directory**

- `implicit-dirs`
- `only-dir`
- `rename-dir-limit`

**Debug**

- `debug_fuse_errors`
- `debug_fuse`
- `debug_gcs`
- `debug-invariants`
- `debug_mutex`

**Cache**

- `stat-cache-capacity`
- `stat-cache-ttl`
- `type-cache-ttl`
- `enable-nonexistent-type-cache`

**Permissions**

- `uid`
- `gid`
- `file-mode`
- `dir-mode`

**Other**

- `billing-project`
- `client-protocol`
- `experimental-enable-json-read`
- `experimental-opentelemetry-collector-address`
- `http-client-timeout`
- `limit-bytes-per-sec`
- `limit-ops-per-sec`
- `max-conns-per-host`
- `max-idle-conns-per-host`
- `max-retry-sleep`
- `-o`
- `retry-multiplier`
- `sequential-read-size-mb`
- `stackdriver-export-interval`

For detailed descriptions of these options, see
[Cloud Storage FUSE command line mount options](https://docs.cloud.google.com/storage/docs/gcsfuse-cli#options). The Cloud Storage FUSE page lists all available FUSE options, some of which are not supported by Cloud Run.

## View Volume mounts settings

### Console

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

   [Go to Cloud Run](https://console.cloud.google.com/run/services)
2. In the services list, click the service you are interested in to open
   the service details page.

3. Click the **Containers** tab to see the volume details.

### gcloud

1. To view volume mount settings, run the following command:

   ```bash
   gcloud run services describe SERVICE_NAME
   ```
2. Locate the Volume mounts setting in the returned
   output.

## Optimize Cloud Storage FUSE network bandwidth performance

For better read and write performance, connect your Cloud Run
service to a VPC network using Direct VPC and route all outbound traffic
through your VPC network. You can do this using any of the following options:

- Enable [Private Google Access](https://docs.cloud.google.com/vpc/docs/configure-private-google-access.md.txt), making sure to set the `vpc-egress` parameter to `all-traffic`.
- Use one of the options described in the networking best practices page, in the section [Internal traffic to a Google API](https://docs.cloud.google.com/run/docs/configuring/networking-best-practices.md.txt#internal-vpc-throughput).

## Container startup time and Cloud Storage FUSE mounts

Using Cloud Storage FUSE can slightly increase your Cloud Run container
cold start time because Cloud Run starts the volume mount prior to starting the
container(s). Your container will start only if Cloud Storage FUSE is successfully mounted.

Note that Cloud Storage FUSE successfully mounts a volume only after establishing a
connection to Cloud Storage. Any networking delays can have an impact
on container startup time. Correspondingly, if the connection attempt fails, Cloud Storage
FUSE will fail to mount and the Cloud Run service will fail to start.
Also, if Cloud Storage FUSE takes longer than 30 seconds to mount, the
Cloud Run service will fail to start because Cloud Run has a
total timeout of 30 seconds to perform all mounts.

## Cloud Storage FUSE performance characteristics

If you define two volumes, each pointing to a different bucket, two
Cloud Storage FUSE processes will be started. The mounts and processes occur
in parallel.

Operations using Cloud Storage FUSE are impacted by network bandwidth
because Cloud Storage FUSE communicates with Cloud Storage using the
Cloud Storage API. Some operations such as listing the contents of a bucket can be slow if the
network bandwidth is low. Similarly, reading a large file can take time as
this is also limited by network bandwidth.

When you write to a bucket, Cloud Storage FUSE fully stages the object in memory.
This means that writing large files is limited by the amount of memory available
to the container instance (the maximum container memory limit is 32 GiB).

The write is flushed to the bucket only when you perform a `close` or
an `fsync`: the full object is then uploaded to the bucket. The
only exception to an object being entirely re-uploaded to the bucket is in the
case of a file with appended content when the file is 2 MiB or more.

For more information, see the following resources:

- [Cloud Storage FUSE documentation](https://docs.cloud.google.com/storage/docs/gcs-fuse#expandable-1)
- [Cloud Storage FUSE performance](https://docs.cloud.google.com/storage/docs/gcsfuse-performance)
- [Cloud Storage FUSE semantics](https://github.com/GoogleCloudPlatform/gcsfuse/blob/master/docs/semantics.md)

## 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:

```bash
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:

<br />

```bash
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:

```bash
gcloud run services update SERVICE \
    --remove-volume VOLUME_NAME \
    --container=container1 \
    --remove-volume-mount MOUNT_PATH \
    --container=container2 \
    --remove-volume-mount MOUNT_PATH
```