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. Cloud IAM permissions are bundled together to make roles. You grant roles to users and groups.

See the sections below the table for additional commands that only apply to buckets with Uniform bucket-level access disabled, as well as notes on using wildcards, the -r flag, the -u flag, and the -m flag.

Command	Subcommand	Resource Acted On	Required Cloud IAM Permissions
cat		Objects	storage.objects.get
compose		Objects	storage.objects.get storage.objects.create storage.objects.delete^1
config			None
cors	get	Buckets	storage.buckets.get
cors	set	Buckets	storage.buckets.update
cp		Objects	storage.objects.list^2 (for the destination bucket) storage.objects.get (for the source objects) storage.objects.create (for the destination bucket) storage.objects.delete^3 (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.create^4 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.update
kms	encryption -k	Buckets, Projects^7	storage.buckets.get storage.buckets.update resourceManager.projects.get^7 cloudkms.cryptoKey.setIamPolicy^7
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.get^5 storage.buckets.getIamPolicy^6
ls		Buckets, Objects	storage.objects.list storage.objects.get^5 storage.objects.getIamPolicy^10
ls -b		Buckets	storage.buckets.get storage.buckets.getIamPolicy^6
mb		Buckets	storage.buckets.create
mv		Objects	storage.objects.list^2 (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.delete^3 (for the destination bucket)
notification	create	Buckets	storage.buckets.update pubsub.topics.get (for the project containing the Pub/Sub topic) pubsub.topics.create^8 (for the project containing the Pub/Sub topic) pubsub.topics.getIamPolicy (for Pub/Sub topic receiving notifications) pubsub.topics.setIamPolicy^8 (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.update
requesterpays	set off	Buckets	storage.buckets.get storage.buckets.update resourcemanager.projects.createBillingAssignment^9
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
rsync		Objects	storage.objects.get (for the source objects and destination bucket) storage.objects.create (for the destination bucket) storage.objects.delete^11 (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 affiliated with the request must have storage.objects.get.
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

¹This permission is only required if the composed object has the same name as an object that already exists in the bucket.

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

³This permission is only required if you don't use the -n flag and you insert an object that has the same name as an object that already exists in the bucket.

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

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

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

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

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

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

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

¹¹This permission is only required if you don't use the -d flag and you insert an object that has the same name as an object that already exists in the bucket.

Note: The permissions listed in the above table allow you to use the commands. Some commands set bucket configurations that won't work without additional permissions. For example, gsutil notification create requires only storage.buckets.update to use, but you must have additional permissions for the feature to work properly.

ACL-related methods

The following table lists the Cloud 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 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
cp -a or cp -p		Objects	storage.objects.list^a (for the destination bucket) storage.objects.get (for the source objects) storage.objects.create (for the destination bucket) storage.objects.delete^b (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.list^a (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.delete^b (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.delete^c (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 don't use the -n flag and you insert an object that has the same name as an object that already exists in the bucket.

^cThis permission is only required if you don't use the -d flag and you insert an object that has the same name as an object that already exists in the bucket.

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

• Learn how to use Cloud IAM permissions.
• For a list of roles and the permissions they contain, see Cloud IAM Roles for Cloud Storage.