Cloud IAM permissions for gsutil commands

The following table lists the Cloud Identity and Access Management (Cloud IAM) permissions required to run each 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 Cloud 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.setIamPolicy2
storage.buckets.update
cp Objects storage.objects.list3 (for the destination bucket)
storage.objects.get (for the source objects)
storage.objects.create (for the destination bucket)
storage.objects.delete1 (for the destination bucket)
storage.objects.getIamPolicy4 (for the source objects)
storage.objects.setIamPolicy4 (for the destination bucket)
cp -n Objects storage.objects.list3 (for the destination bucket)
storage.objects.get (for the source objects and destination bucket)
storage.objects.create (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.setIamPolicy2
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
kms authorize Projects resourceManager.projects.get
iam.serviceAccounts.create7
cloudkms.cryptoKey.setIamPolicy (for the Cloud KMS key being authorized)
kms encryption Buckets storage.buckets.get
kms encryption -d Buckets storage.buckets.get
storage.buckets.setIamPolicy2
storage.buckets.update
kms encryption -k Buckets, Projects9 storage.buckets.get
storage.buckets.setIamPolicy2
storage.buckets.update
resourceManager.projects.get9
cloudkms.cryptoKey.setIamPolicy9
kms serviceaccount Projects resourceManager.projects.get
label get Buckets storage.buckets.get
label set/ch Buckets storage.buckets.setIamPolicy2
storage.buckets.update
lifecycle get Buckets storage.buckets.get
lifecycle set/ch Buckets storage.buckets.setIamPolicy2
storage.buckets.update
logging get Buckets storage.buckets.get
logging set Buckets storage.buckets.setIamPolicy2
storage.buckets.update
ls Projects storage.buckets.list
storage.buckets.get5
storage.buckets.getIamPolicy6
ls Buckets, Objects storage.objects.list
storage.objects.get5
storage.objects.getIamPolicy6
ls -b Buckets storage.buckets.get
storage.buckets.getIamPolicy6
mb Buckets storage.buckets.create
mv Objects storage.objects.list3 (for the destination bucket)
storage.objects.get (for the source objects)
storage.objects.create (for the destination bucket)
storage.objects.delete (for the source bucket)
storage.objects.delete1 (for the destination bucket)
storage.objects.getIamPolicy4 (for the source objects)
storage.objects.setIamPolicy4 (for the destination bucket)
mv -n Objects storage.objects.list3 (for the destination bucket)
storage.objects.get (for the source objects and destination bucket)
storage.objects.create (for the destination bucket)
storage.objects.delete (for the source bucket)
storage.objects.getIamPolicy4 (for the source objects)
storage.objects.setIamPolicy4 (for the destination bucket)
notification create Buckets storage.buckets.update
pubsub.topics.get (for the project containing the Pub/Sub topic)
pubsub.topics.create8 (for the project containing the Pub/Sub topic)
pubsub.topics.getIamPolicy (for Pub/Sub topic receiving notifications)
pubsub.topics.setIamPolicy8 (for Pub/Sub topic receiving notifications)
notification create -s 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
requesterpays get Buckets storage.buckets.get
requesterpays set on Buckets storage.buckets.get
storage.buckets.setIamPolicy2
storage.buckets.update
requesterpays set off Buckets storage.buckets.get
storage.buckets.setIamPolicy2
storage.buckets.update
resourcemanager.projects.createBillingAssignment10
retention clear, event-default, lock, or set Buckets storage.buckets.setIamPolicy2
storage.buckets.update
retention event or temp Objects storage.objects.get
storage.objects.list
storage.objects.update
retention get Buckets storage.buckets.get
rewrite -k Objects storage.objects.list
storage.objects.get
storage.objects.create
storage.objects.delete
rewrite -s Objects storage.objects.list
storage.objects.get
storage.objects.create
storage.objects.delete
storage.objects.update
rm Buckets storage.buckets.delete
storage.objects.delete
storage.objects.list
rm Objects storage.objects.delete
rsync Objects storage.objects.get (for the source objects and destination bucket)
storage.objects.create (for the destination bucket)
storage.objects.delete1 (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)
rsync -d Objects storage.objects.get (for the source objects and destination bucket)
storage.objects.create (for the destination bucket)
storage.objects.delete (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)
rsync -n Objects storage.objects.list (for the source and destination buckets)
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.setIamPolicy2
storage.buckets.update
web get Buckets storage.buckets.get
web set Buckets storage.buckets.setIamPolicy2
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 only required if you have the storage.buckets.getIamPolicy permission.

3 This permission is only required when the destination in the command contains an object path.

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 Cloud IAM policies included in the details.

7This permission is only required if you do not have an existing Cloud Storage service account associated with the project.

8These permissions are not required if the topic already exists and the relevant service account has access to it.

9If you use gsutil kms encryption -k and your project's service account does not have permission to access the requested Cloud KMS key, gsutil runs gsutil kms authorize in order to grant your service account the required permission.

10This permission is only required if you do not include a billing project in your request. See Requester Pays Use and access requirements for more information.

The -u top-level flag

If you use the -u top-level flag to specify a project that should be billed for your request, you must have serviceusage.services.use permission for the project you specify. The -u flag is used, for example, when accessing a bucket with Requester Pays enabled.

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.

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Storage
Need help? Visit our support page.