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^10
acl	set or ch	Objects	storage.objects.get
			storage.objects.getIamPolicy^10
			storage.objects.setIamPolicy^10
			storage.objects.update
ubla	set	Buckets	storage.buckets.get
			storage.buckets.update
ubla	get	Buckets	storage.buckets.get
cat		Objects	storage.objects.get
compose		Objects	storage.objects.get (for the source objects)
			storage.objects.create (for the destination bucket)
			storage.objects.delete^1 (for the destination bucket)
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^1 (for the destination bucket)
			storage.objects.getIamPolicy^3^,10 (for the source objects)
			storage.objects.setIamPolicy^3^,10 (for the destination bucket)
cp -n		Objects	storage.objects.list^2 (for the destination bucket)
			storage.objects.get (for the source objects and destination bucket)
			storage.objects.create (for the destination bucket)
			storage.objects.getIamPolicy^3^,10 (for the source objects)
			storage.objects.setIamPolicy^3^,10 (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
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
iam	get	Objects	storage.objects.get
			storage.objects.getIamPolicy^10
iam	set or ch	Objects	storage.objects.get
			storage.objects.getIamPolicy^10
			storage.objects.setIamPolicy^10
			storage.objects.update
kms	authorize	Projects	resourceManager.projects.get
			iam.serviceAccounts.create^4
			cloudkms.cryptoKey.setIamPolicy (for the 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^6^,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^1 (for the destination bucket)
			storage.objects.getIamPolicy^3^,10 (for the source objects)
			storage.objects.setIamPolicy^3^,10 (for the destination bucket)
mv -n		Objects	storage.objects.list^2 (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.getIamPolicy^3^,10 (for the source objects)
			storage.objects.setIamPolicy^3^,10 (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^1 (for the destination bucket)
			storage.objects.list (for the source and destination buckets)
			storage.objects.getIamPolicy^3^,10 (for the source objects)
			storage.objects.setIamPolicy^3^,10 (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.getIamPolicy^3^,10 (for the source objects)
			storage.objects.setIamPolicy^3^,10 (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.update
web	get	Buckets	storage.buckets.get
web	set	Buckets	storage.buckets.update

¹This permission is only required when the inserted 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 when using the -a or -p flags in the command.

⁴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 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 does not apply to buckets with uniform bucket-level access enabled.

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.

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.