IAM permissions for gsutil commands

The following table lists the Identity and Access Management (IAM) permissions required to run each Cloud Storage gsutil command on a given resource. IAM permissions are bundled together to make roles. You grant roles to users and groups.

On this page, you can also find information about the following:

Command Subcommand Resource Acted On Required IAM Permissions
autoclass get Buckets storage.buckets.get
autoclass set Buckets storage.buckets.update
cat Objects storage.objects.get
compose Objects storage.objects.get
storage.objects.create
storage.objects.delete1
config None
cors get Buckets storage.buckets.get
cors set Buckets storage.buckets.update
cp Objects storage.objects.list2 (for the destination bucket)
storage.objects.get (for the source objects)
storage.objects.create (for the destination bucket)
storage.objects.delete3 (for the destination bucket)
defstorageclass get Buckets storage.buckets.get
defstorageclass set Buckets storage.buckets.update
du Objects storage.objects.get
hash Objects storage.objects.get
help None
hmacKeys create HMAC keys storage.hmacKeys.create
hmacKeys delete HMAC keys storage.hmacKeys.delete
hmacKeys get HMAC keys storage.hmacKeys.get
hmacKeys list HMAC keys storage.hmacKeys.list
hmacKeys update HMAC keys storage.hmacKeys.update
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
kms authorize Projects resourceManager.projects.get
iam.serviceAccounts.create4
cloudkms.cryptoKeys.setIamPolicy (for the Cloud KMS key being authorized)
kms encryption Buckets storage.buckets.get
kms encryption -d Buckets storage.buckets.get
storage.buckets.update
kms encryption -k Buckets, Projects5 storage.buckets.get
storage.buckets.update
resourceManager.projects.get5
cloudkms.cryptoKeys.setIamPolicy5
kms serviceaccount Projects resourceManager.projects.get
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.getIamPolicy6
ls Buckets, Objects storage.objects.list
storage.objects.getIamPolicy7
ls -b Buckets storage.buckets.get
storage.buckets.getIamPolicy6
mb Buckets storage.buckets.create
mv Objects storage.objects.list2 (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.delete3 (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.get
storage.buckets.update
notification list Buckets storage.buckets.get
notification watchbucket Buckets storage.buckets.update
notification stopchannel Buckets storage.buckets.update
pap get Buckets storage.buckets.get
pap set Buckets storage.buckets.get
storage.buckets.update
storage.buckets.setIamPolicy10
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.update
requesterpays set off Buckets storage.buckets.update
resourcemanager.projects.createBillingAssignment9
retention clear, event-default, lock, or set Buckets 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
storage.objects.list
rpo get Buckets storage.buckets.get
rpo set Buckets storage.buckets.get
storage.buckets.update
rsync Objects storage.objects.get (for the source objects and destination bucket)
storage.objects.create (for the destination bucket)
storage.objects.delete11 (for the destination bucket)
storage.objects.list (for the source and destination buckets)
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 whose key is used as part of this command must have permission to perform the request being encoded into the signed URL.
stat Objects storage.objects.get
test None
ubla set Buckets storage.buckets.get
storage.buckets.update
ubla get Buckets storage.buckets.get
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 if the composed object has the same name as an object that already exists in the bucket.

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

3This permission is only required if you use parallel composite uploads or if you don't use the -n flag but insert an object that has the same name as an object that already exists in the bucket.

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

5If 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.

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

7This permission is only required if you want IAM policies included in the details, and it does not apply to buckets with uniform bucket-level access enabled.

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

9This 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.

10This permission is not required if the command does not change the bucket setting.

11This permission is only required if you use the -d flag or if you insert an object that has the same name as, but different data than, an object that already exists in the bucket.

ACL-related methods

The following table lists the IAM permissions required to run gsutil commands that apply specifically to the management of ACLs. These commands only apply to buckets that have Uniform bucket-level access disabled.

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
cp -a or cp -p Objects storage.objects.lista (for the destination bucket)
storage.objects.get (for the source objects)
storage.objects.create (for the destination bucket)
storage.objects.deleteb (for the destination bucket)
storage.objects.getIamPolicy (for the source objects)
storage.objects.setIamPolicy (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
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
mv -a or mv -p Objects storage.objects.lista (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.deleteb (for the destination bucket)
storage.objects.getIamPolicy (for the source objects)
storage.objects.setIamPolicy (for the destination bucket)
rsync -a or rsync -p Objects storage.objects.get (for the source objects and destination bucket)
storage.objects.create (for the destination bucket)
storage.objects.deletec (for the destination bucket)
storage.objects.list (for the source and destination buckets)
storage.objects.getIamPolicy (for the source objects)
storage.objects.setIamPolicy (for the destination bucket)

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

bThis permission is only required if you use parallel composite uploads or if you don't use the -n flag but insert an object that has the same name as an object that already exists in the bucket.

cThis permission is only required if you use the -d flag or if you insert an object that has the same name as, but different data than, an object that already exists in the bucket.

The -u top-level flag

If you use the -u global 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 global 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