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:
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
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 runmount /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
andmv
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 (preview)
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
Learn about Cloud Storage FUSE performance, such as how to control caching behavior or log activity.
Learn about directory semantics in Cloud Storage FUSE.