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, Projects7 | 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 |
1This permission is only required when the inserted object has the same name as an object that already exists in the bucket.
2 This permission is only required when the destination in the command contains an object path.
3This permission is only required when using the -a
or -p
flags
in the command.
4This permission is only required if you do not have an existing Cloud Storage service account associated with the project.
5This permission is only required when using the -L
or -l
flag
in the command.
6This permission is only required if you want Cloud IAM policies included in the details.
7If 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.
8These permissions are not required if the topic already exists and the relevant service account has access to it.
9This 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.
10This permission does not apply to buckets with uniform bucket-level access enabled.
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.