IAM permissions for gsutil commands

The following table lists the Identity and Access Management (IAM) permissions required to run each Google Cloud Storage gsutil command on a given resource. See the sections below the table for notes on using wildcards, the -r flag and the -m flag.

Command Subcommand Resource Acted On Required IAM Permissions
acl get Buckets storage.buckets.get
storage.buckets.getIamPolicy
acl set or ch Buckets storage.buckets.get
storage.buckets.getIamPolicy
storage.buckets.setIamPolicy
storage.buckets.update
acl get Objects storage.objects.get
storage.objects.getIamPolicy
acl set or ch Objects storage.objects.get
storage.objects.getIamPolicy
storage.objects.setIamPolicy
storage.objects.update
cat Objects storage.objects.get
compose Objects storage.objects.get (for the source objects)
storage.objects.create (for the destination bucket)
storage.objects.delete1 (for the destination bucket)
config None
cors get Buckets storage.buckets.get
cors set Buckets storage.buckets.update
cp Objects storage.objects.get (for the source objects)3
storage.objects.create (for the destination bucket)
storage.objects.delete1,2 (for the destination bucket)
storage.objects.getIamPolicy4 (for the source objects)
storage.objects.setIamPolicy4 (for the destination bucket)
defacl get Buckets storage.buckets.get
storage.buckets.getIamPolicy
defacl set or ch Buckets storage.buckets.get
storage.buckets.getIamPolicy
storage.buckets.setIamPolicy
storage.buckets.update
defstorageclass get Buckets storage.buckets.get
defstorageclass set Buckets storage.buckets.update
du Objects storage.objects.get
hash Objects storage.objects.get
help None
iam get Buckets storage.buckets.get
storage.buckets.getIamPolicy
iam set or ch Buckets storage.buckets.get
storage.buckets.getIamPolicy
storage.buckets.setIamPolicy
storage.buckets.update
iam get Objects storage.objects.get
storage.objects.getIamPolicy
iam set or ch Objects storage.objects.get
storage.objects.getIamPolicy
storage.objects.setIamPolicy
storage.objects.update
label get Buckets storage.buckets.get
label set/ch Buckets storage.buckets.update
lifecycle get Buckets storage.buckets.get
lifecycle set/ch Buckets storage.buckets.update
logging get Buckets storage.buckets.get
logging set Buckets storage.buckets.update
ls Projects storage.buckets.list
storage.buckets.get5
storage.buckets.getIamPolicy6
ls -b Buckets storage.buckets.get
storage.buckets.getIamPolicy6
ls Buckets storage.objects.list
storage.objects.get5
storage.objects.getIamPolicy6
ls Objects storage.objects.list
storage.objects.get5
storage.objects.getIamPolicy6
mb Buckets storage.buckets.create
mv Objects storage.objects.get (for the source objects)3
storage.objects.create (for the destination bucket)
storage.objects.delete (for the source bucket)
storage.objects.delete1,2 (for the destination bucket)
storage.objects.getIamPolicy4 (for the source objects)
storage.objects.setIamPolicy4 (for the destination bucket)
notification create Buckets storage.buckets.update
notification delete Buckets storage.buckets.update
notification list Buckets storage.buckets.get
notification watchbucket Buckets storage.buckets.update
notification stopchannel Buckets storage.buckets.update
perfdiag Buckets storage.buckets.get
storage.objects.create
storage.objects.delete
storage.objects.list
storage.objects.get
rb Buckets storage.buckets.delete
rewrite Objects storage.objects.list
storage.objects.get
storage.objects.create
storage.objects.delete
storage.objects.update7
rm Buckets storage.buckets.delete
storage.objects.delete
storage.objects.list
rm Objects storage.objects.delete
rsync8 Objects storage.objects.get (for the source objects and destination bucket)
storage.objects.create (for the destination bucket)
storage.objects.delete1,9 (for the destination bucket)
storage.objects.list (for the source and destination buckets)
storage.objects.getIamPolicy4 (for the source objects)
storage.objects.setIamPolicy4 (for the destination bucket)
setmeta Objects storage.objects.get
storage.objects.list
storage.objects.update
signurl None; however, the service account affiliated with the request must have storage.objects.get.
stat Objects storage.objects.get
test None
update None
version None
versioning get Buckets storage.buckets.get
versioning set Buckets storage.buckets.update
web get Buckets storage.buckets.get
web set Buckets storage.buckets.update

1This permission is only required when the inserted object has the same name as an object that already exists in the bucket.

2This permission is not required if the -n flag is used in the command.

3This permission is also required for the destination bucket if the -n flag is used in the command.

4This permission is only required when using the -a or -p flags in the command.

5This permission is only required when using the -L or -l flag in the command.

6This permission is only required if you want IAM policies included in the details.

7This permission is only required when using the -k or -s flag in the command.

8If you use the -n flag with rsync, the only permission you need is storage.objects.list.

9This permission is required if the -d flag is used in the command.

Wildcards and recursive flags

If you use URI wildcards to select multiple objects in a command, you must have storage.objects.list permission for the bucket containing the objects. Similarly, if you use URI wildcards to select multiple buckets in a command, you must have storage.buckets.list permission for the project(s) containing the buckets.

If you use the recursive flags (-r and -R), you must have storage.objects.list permission for the relevant bucket, in addition to the permissions required for the specific command you are using.

The -m top-level flag

Normally, if you use a gsutil command that acts over multiple objects or buckets, the command fails at the first error. However, when you use the -m top-level flag, gsutil records any errors it encounters and continues with the operation.

For example, say you try to perform an acl set command on a series of objects, but you only have permission to do so on some of the objects. If you do not use the -m flag, gsutil applies the ACLs successfully until it reaches an object you do not have permission to apply an ACL to. At that point, gsutil fails. If you use the -m flag, gsutil records the errors that arise when it attempts to apply an ACL to an object for which you don't have permission, but otherwise continues with the operation.

Send feedback about...

Cloud Storage Documentation