Mount Cloud Storage buckets by using Cloud Storage FUSE

Mount options

This page describes several ways to mount Cloud Storage buckets to your local file system by using Cloud Storage FUSE.

Before you begin

To mount buckets, you must first complete the following tasks.

Get required roles

To mount a bucket, ask the bucket owner to grant you the Storage Object Viewer (roles/storage.objectViewer) role on the bucket. Note that if you created the bucket, you likely already have the Storage Admin (roles/storage.admin) role on the bucket and don't need the Storage Object Viewer role.

The Storage Object Viewer predefined role contains the permission required to mount a bucket. To see the exact permission that's required, expand the Required permissions section:

Required permissions

  • storage.objects.list

You might also be able to get this permission with custom roles or other predefined roles.

For instructions on granting roles on buckets, see Use IAM with buckets.

Install Cloud Storage FUSE

If you haven't already, install Cloud Storage FUSE.

Authenticate Cloud Storage FUSE requests

To authenticate Cloud Storage FUSE requests to Cloud Storage, you must set up Application Default Credentials. By default, Cloud Storage FUSE automatically loads existing Application Default Credentials without any further configuration.

To use the Google Cloud CLI to set up Application Default Credentials, complete the following steps:

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command: 

    gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

When you create a Compute Engine virtual machine (VM), its service account can also be used to authenticate access to Cloud Storage FUSE.

Mount a bucket

To mount buckets to your local file system, use the following command:

gcsfuse GLOBAL_OPTIONS BUCKET_NAME MOUNT_POINT

Where:

  • GLOBAL_OPTIONS are the options you can include to control how the mount is set up. For more information about options and how to use them, see Cloud Storage FUSE CLI options.

  • BUCKET_NAME is the name of the bucket you want to mount. For example, my-bucket. If you want to perform dynamic mounting, exclude a bucket name from the command.

  • MOUNT_POINT is the local directory where the bucket gets mounted. For example, /path/to/mount/point.

After Cloud Storage FUSE exits, you can access your mounted buckets by running ls on the bucket mount point. If you'd prefer Cloud Storage FUSE to stay in the foreground (for example, for debug logging), you can run the gcsfuse command with the --foreground flag.

Examples of mounting

This section describes different example commands for mounting buckets.

Static mounting

Static mounting refers to mounting a specific bucket. For example, to mount a bucket named my-bucket to the directory /path/to/mount/point, run the following commands:

mkdir /path/to/mount/point
gcsfuse my-bucket /path/to/mount/point

Dynamic mounting

Dynamic mounting refers to mounting all buckets a user has access to as subdirectories.

When you perform dynamic mounting, you exclude bucket names from the command. For example, say you have access to buckets named my-bucket-1, my-bucket-2, and my-bucket-3. To mount all buckets to the directory /path/to/mount/point, run the following commands:

mkdir /path/to/mount/point
gcsfuse /path/to/mount/point

You can then access the buckets as subdirectories:

ls /path/to/mount/point/my-bucket-1/
ls /path/to/mount/point/my-bucket-2/
ls /path/to/mount/point/my-bucket-3/

Dynamically mounted buckets cannot be listed from the root mount point. Instead, the bucket name must be specified as part of the list operation.

Mounting a bucket as read-only

To mount a bucket as read-only, pass the -o ro option to your gcsfuse command. For example, to mount a bucket named my-bucket as read-only to the directory /path/to/mount/point, run the following command:

gcsfuse -o ro my-bucket  /path/to/mount/point

Mount a directory within a bucket

By default, Cloud Storage FUSE mounts buckets in entirety, which includes all the bucket's contents and directory structures. To mount a specific directory within a bucket, pass the --only-dir option to your gcsfuse command. For example, to mount the directory my-bucket/a/b to the directory /path/to/mount/point, run the following command:

gcsfuse --only-dir a/b my-bucket /path/to/mount/point

Mount by using the Linux mount command

The Cloud Storage FUSE install includes a helper that's understood by the Linux mount command, which lets you use the mount command to mount buckets. The mount command must be run from root if you're using Linux. For example, the following command mounts a bucket named my-bucket to the path /path/to/mount/point:

sudo mount -t gcsfuse -o rw,user my-bucket /path/to/mount/point

When mounting by using the Linux mount command, Cloud Storage FUSE CLI options can be passed as an argument to the -o flag, but hyphens (-) in them should be replaced with underscores (_). For example, implicit_dirs instead of implicit-dirs.

sudo mount -t gcsfuse -o implicit_dirs my-bucket /path/to/mount/point

Persistent mounting

The Cloud Storage FUSE installation includes a helper that's installed to your system at the path /sbin/mount.gcsfuse. This helper lets you create mount points by using the /etc/fstab file, so you can persist your mounts.

For example, when added to your /etc/fstab file, the following line defines a mount point for a bucket named my-bucket at the path /mount/point:

my-bucket /mount/point gcsfuse rw,noauto,user

Where:

  • The rw option specifies that the mount point be created with read and write permissions.

  • The noauto option specifies that the file system shouldn't be mounted at boot time.

  • The user option allows anybody to create the mount point specified in the /etc/fstab file. After the sample line is added to the /etc/fstab file, you can run mount /mount/point as a non-root user.

If you want to mount the bucket automatically at boot, you might need to include the x-systemd.requires=network-online.target option or the _netdev option in your /etc/fstab entry, to ensure that Cloud Storage FUSE waits for the network system to be ready prior to mounting. For example:

my-bucket /mount/point gcsfuse rw,x-systemd.requires=network-online.target,user

You can mount a bucket automatically as a specific non-root user by including the options uid, gid, or both in your /etc/fstab entry. For example:

my-bucket /mount/point gcsfuse rw,_netdev,allow_other,uid=1001,gid=1001

Similar to linux mount command, the flags used for mounting in the /etc/fstab file must use underscores (_) instead of hyphens (-). For example, implicit_dirs instead of implicit-dirs.

Mount a bucket with folders

You can mount buckets with multiple folder types.

Mount a bucket with managed folders

To mount a bucket including its managed folders, include the --implicit-dirs option in your command.

For example, to mount a bucket named my-bucket and its managed folders to the directory /path/to/mount/point, run the following commands:

gcsfuse my-bucket /path/to/mount/point --implicit-dirs

When mounting a bucket with managed folders, keep the following limitations and considerations in mind:

  • Empty managed folders don't appear in mounted buckets.

  • You cannot set or manage IAM permissions on a managed folder by using Cloud Storage FUSE. To set or manage IAM permissions on a managed folder, see Use IAM with managed folders.

  • You can copy and move a managed folder in a mounted bucket by using the cp and mv commands. When you copy or move a managed folder, the IAM policies on the original managed folder don't persist onto the new managed folder. You must set new IAM policies on the new managed folder.

Mount a bucket with implicitly defined folders

You can mount implicitly defined folders using the --implicit-dirs flag in your Cloud Storage FUSE command. Implicitly defined folders are folders that aren't explicitly created as objects in Cloud Storage. The --implicit-dirs flag lets you see folders when mounting a bucket.

For example, to mount a bucket named my-bucket to the directory /path/to/mount/point with implicitly defined folders, run the following command:

gcsfuse my-bucket /path/to/mount/point --implicit-dirs

Mount a hierarchical namespace-enabled bucket with folders

You can mount a bucket with hierarchical namespace enabled, including its folders. When mounting a bucket with hierarchical namespace, you don't need to specify the --implicit-dirs flag in order for the folders to appear in your mounted bucket.

For example, to mount a bucket named my-bucket with folders to the directory /path/to/mount/point, run the following command:

gcsfuse my-bucket /path/to/mount/point

Control access permissions to the mount point

By default, Cloud Storage FUSE creates bucket mount points with permissions that only allow the invoking user to access the contents of the mounted buckets. This is a security measure that's implemented within the FUSE kernel.

To mount a bucket and allow others to access the bucket mount point, you can run the command mount as root with the option -o allow_other:

mount -t gcsfuse -o allow_other my-bucket /path/to/mount/point

If you want to avoid mounting the bucket as root, you must add user_allow_other to the /etc/fuse.conf file to allow others to access the bucket mount point.

To access a mounted bucket, other users besides the invoking user must have the required IAM permissions.

Required roles for accessing a mounted bucket

To read from and write to a mounted bucket, ask the bucket owner to grant you the Storage Object User (roles/storage.objectUser) role on the bucket.

This predefined role contains the permissions required to read from a mounted bucket and write to a mounted bucket. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

  • storage.objects.create
  • storage.objects.delete
  • storage.objects.get
  • storage.objects.list
  • storage.objects.update

You might also be able to get these permissions with custom roles or other predefined roles.

For instructions on granting roles on buckets, see Use IAM with buckets.

Unmount a bucket

To unmount a bucket, use the fusermount tool:

fusermount -u /path/to/mount/point

What's next