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.getIamPolicy1
buckets get-iam-policy storage.buckets.get
storage.buckets.getIamPolicy
buckets list storage.buckets.list
storage.buckets.getIamPolicy1
buckets notifications create storage.buckets.get
storage.buckets.update
pubsub.topics.get (for the project containing the Pub/Sub topic)
pubsub.topics.create3 (for the project containing the Pub/Sub topic)
pubsub.topics.getIamPolicy (for Pub/Sub topic receiving notifications)
pubsub.topics.setIamPolicy3 (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.createBillingAssignment2
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.list13
cp storage.objects.get (for the source objects)
storage.buckets.get12 (for the destination bucket)
storage.objects.list4 (for the destination bucket)
storage.objects.create (for the destination bucket)
storage.objects.delete5 (for the destination bucket)
storageinsights.reportDetails.get15
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.getIamPolicy6
ls (for object listing) storage.objects.get7
storage.objects.list
storage.objects.getIamPolicy8
ls --buckets storage.buckets.get
storage.buckets.getIamPolicy6
mv storage.objects.list4 (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.delete5 (for the destination bucket)
objects compose storage.objects.get
storage.objects.create
storage.objects.delete9
objects describe storage.objects.get
storage.objects.getIamPolicy8
objects list storage.objects.list
storage.objects.getIamPolicy8
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.overrideUnlockedRetention11
operations cancel storage.bucketOperations.cancel
operations describe storage.bucketOperations.get
operations list storage.bucketOperations.list
restore storage.objects.create
storage.objects.delete9
storage.objects.restore
restore --async storage.objects.create
storage.objects.delete14
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.delete10 (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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

15This permission is only required for downloading inventory reports.

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