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` `storage.buckets.setIpFilter`¹⁶
`buckets delete`		`storage.buckets.delete`
`buckets describe`		`storage.buckets.get` `storage.buckets.getIamPolicy`¹ `storage.buckets.getIpFilter`¹⁷
`buckets get-iam-policy`		`storage.buckets.get` `storage.buckets.getIamPolicy`
`buckets list`		`storage.buckets.list` `storage.buckets.getIamPolicy`¹
`buckets notifications create`		`storage.buckets.get` `storage.buckets.update` `pubsub.topics.get` (for the project containing the Pub/Sub topic) `pubsub.topics.create`³ (for the project containing the Pub/Sub topic) `pubsub.topics.getIamPolicy` (for Pub/Sub topic receiving notifications) `pubsub.topics.setIamPolicy`³ (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` `storage.buckets.setIpFilter`¹⁶
`buckets update`	`--no-requester-pays`	`storage.buckets.update` `resourcemanager.projects.createBillingAssignment`²
`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`¹³
`cp`		`storage.objects.get` (for the source objects) `storage.buckets.get`¹² (for the destination bucket) `storage.objects.list`⁴ (for the destination bucket) `storage.objects.create` (for the destination bucket) `storage.objects.delete`⁵ (for the destination bucket) `storageinsights.reportDetails.get`¹⁵
`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`⁶
`ls` (for object listing)		`storage.objects.get`⁷ `storage.objects.list` `storage.objects.getIamPolicy`⁸
`ls`	`--buckets`	`storage.buckets.get` `storage.buckets.getIamPolicy`⁶
`mv`		`storage.objects.list`⁴ (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`⁵ (for the destination bucket)
`objects compose`		`storage.objects.get` `storage.objects.create` `storage.objects.delete`⁹
`objects describe`		`storage.objects.get` `storage.objects.getIamPolicy`⁸
`objects list`		`storage.objects.list` `storage.objects.getIamPolicy`⁸
`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`¹¹
`operations cancel`		`storage.bucketOperations.cancel`
`operations describe`		`storage.bucketOperations.get`
`operations list`		`storage.bucketOperations.list`
`restore`		`storage.objects.create` `storage.objects.delete`⁹ `storage.objects.restore`
`restore`	`--async`	`storage.objects.create` `storage.objects.delete`¹⁴ `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`¹⁰ (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.

¹⁶This permission is only required if the request includes the flag --ip-filter-file to create, update or delete the IP filtering rules on a bucket.

¹⁷This permission is only required if the request includes the flag --format=default(ip_filter_config) to get the bucket's IP filter configuration as part of the response.

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.

IAM permissions for gcloud storage commands

The --billing-project top-level flag

Wildcards and recursive flags

What's next

The `--billing-project` top-level flag