IAM permissions for gcloud storage commands

The following table lists the Identity and Access Management (IAM) permissions required to run gcloud storage commands. IAM permissions are bundled together to make roles. You grant roles to principals.

See the sections below the table for notes on using wildcards, the --recursive flag, and the --billing-project flag.

Command	Flag	Required IAM Permissions
buckets add-iam-policy-binding		storage.buckets.get storage.buckets.getIamPolicy storage.buckets.setIamPolicy storage.buckets.update
buckets create		storage.buckets.create
buckets delete		storage.buckets.delete
buckets describe		storage.buckets.get storage.buckets.getIamPolicy^1
buckets get-iam-policy		storage.buckets.get storage.buckets.getIamPolicy
buckets list		storage.buckets.list storage.buckets.getIamPolicy^1
buckets notifications create		storage.buckets.get storage.buckets.update pubsub.topics.get (for the project containing the Pub/Sub topic) pubsub.topics.create^3 (for the project containing the Pub/Sub topic) pubsub.topics.getIamPolicy (for Pub/Sub topic receiving notifications) pubsub.topics.setIamPolicy^3 (for Pub/Sub topic receiving notifications)
buckets notifications create	--skip-topic-setup	storage.buckets.get storage.buckets.update
buckets notifications delete		storage.buckets.get storage.buckets.update
buckets notifications describe		storage.buckets.get
buckets notifications list		storage.buckets.get
buckets remove-iam-policy-binding		storage.buckets.get storage.buckets.getIamPolicy storage.buckets.setIamPolicy storage.buckets.update
buckets set-iam-policy		storage.buckets.setIamPolicy storage.buckets.update
buckets update		storage.buckets.update
buckets update	--no-requester-pays	storage.buckets.update resourcemanager.projects.createBillingAssignment^2
buckets update	--recovery-point-objective --rpo --[no-]uniform-bucket-level-access	storage.buckets.get storage.buckets.update
buckets update	--clear-pap --clear-public-access-prevention --[no-]pap --[no-]public-access-prevention	storage.buckets.get storage.buckets.update storage.buckets.setIamPolicy
cat		storage.objects.get storage.objects.list^13
cp		storage.objects.get (for the source objects) storage.buckets.get^12 (for the destination bucket) storage.objects.list^4 (for the destination bucket) storage.objects.create (for the destination bucket) storage.objects.delete^5 (for the destination bucket) storageinsights.reportDetails.get^15
du		storage.objects.list
folders create		storage.folders.create
folders delete		storage.folders.delete
folders describe		storage.folders.get
folders list		storage.folders.list
folders rename		storage.folders.rename (for the source bucket) storage.folders.create (for the destination bucket)
hash		storage.objects.get
hmac create		storage.hmacKeys.create
hmac delete		storage.hmacKeys.delete
hmac describe		storage.hmacKeys.get
hmac list		storage.hmacKeys.list
hmac update		storage.hmacKeys.update
insights inventory-reports create		storageinsights.reportConfigs.create
insights inventory-reports delete		storageinsights.reportConfigs.delete
insights inventory-reports details list		storageinsights.reportDetails.list
insights inventory-reports details describe		storageinsights.reportDetails.get
insights inventory-reports list		storageinsights.reportConfigs.list
insights inventory-reports update		storageinsights.reportConfigs.get storageinsights.reportConfigs.update
ls (for bucket listing)		storage.buckets.list storage.buckets.getIamPolicy^6
ls (for object listing)		storage.objects.get^7 storage.objects.list storage.objects.getIamPolicy^8
ls	--buckets	storage.buckets.get storage.buckets.getIamPolicy^6
mv		storage.objects.list^4 (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^5 (for the destination bucket)
objects compose		storage.objects.get storage.objects.create storage.objects.delete^9
objects describe		storage.objects.get storage.objects.getIamPolicy^8
objects list		storage.objects.list storage.objects.getIamPolicy^8
objects update		storage.objects.get storage.objects.list storage.objects.update
objects update	--storage-class --encryption-key --clear-encryption-key	storage.objects.get storage.objects.list storage.objects.create storage.objects.delete
objects update	--retention-mode --retain-until --clear-retention	storage.objects.get storage.objects.list storage.objects.update storage.objects.setRetention storage.objects.overrideUnlockedRetention^11
operations cancel		storage.bucketOperations.cancel
operations describe		storage.bucketOperations.get
operations list		storage.bucketOperations.list
restore		storage.objects.create storage.objects.delete^9 storage.objects.restore
restore	--async	storage.objects.create storage.objects.delete^14 storage.objects.restore storage.buckets.restore
rm		storage.buckets.delete storage.objects.delete storage.objects.list
rsync		storage.objects.get (for the source objects and destination bucket) storage.objects.create (for the destination bucket) storage.objects.delete^10 (for the destination bucket) storage.objects.list (for the source and destination buckets)
rsync	--dry-run	storage.objects.list (for the source and destination buckets)
service-agent		resourceManager.projects.get
sign-url		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.

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

²This permission is only required if you don't include a billing project in your request. See Requester Pays Use and access requirements for more information.

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

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

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

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

⁷This permission is only required if you use the --fetch-encrypted-object-hashes flag.

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

⁹This permission is only required if the operation creates an object with the same name as an object that already exists in the bucket.

¹⁰This permission is only required if you use the --delete-unmatched-destination-objects 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.

¹¹This permission is only required if the request also requires you to use the --override-unlocked-retention flag.

¹²This permission is required to perform parallel composite uploads if the gcloud CLI property storage/parallel_composite_upload_compatibility_check is set to True.

¹³This permission is only required if you want to use regular expressions to retrieve objects.

¹⁴This permission is only required if the request includes the --allow-overwrite flag and the operation creates an object with the same name as an object that already exists in the bucket.

¹⁵This permission is only required for downloading inventory reports.

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

The --billing-project top-level flag

If you use the --billing-project 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 --billing-project 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 flag, you must have storage.objects.list permission for the relevant bucket, in addition to the permissions required for the specific command you are using.

What's next

• Grant IAM roles at the project and bucket level.
• Review IAM roles that contain Cloud Storage permissions.