Cloud IAM policies for Compute Engine resources allow you to grant access to specific resources, such as VM instances, disks, and images, by managing Cloud IAM roles on those resources. This gives you flexibility to apply the principle of least privilege, for example, to grant collaborators permissions only to the specific resources that they need to do their work.
Resources also inherit the policies of their parent resources. The effective policy for a resource is the union of the policy set at that resource and the policy inherited from higher up in the resource hierarchy.
When you bind a member to a resource or set the policy on a resource, members won't receive an invite email. Instead, access for each member is updated directly.
See the Cloud IAM documentation for more information about the types of members (such as users or groups) that can be included in a Cloud IAM policy.
Before you begin
- If you want to use the command-line examples in this guide:
- Install or update to the latest version of the gcloud command-line tool.
- Set a default region and zone.
- If you want to use the API examples in this guide, set up API access.
- Read the Access control overview.
- Familiarize yourself with Cloud IAM roles for Compute Engine .
Supported resources
You can currently grant access on the following Compute Engine resources:
You can also grant access to the following resources, but granting access to
these resources is currently in beta so you must use associated
gcloud beta
or
beta API commands:
subnetworks
(beta)
Adding and removing member bindings on a resource
A Cloud IAM binding on a resource grants a specific role to a member on
that resource. You can add and remove Cloud IAM bindings on instances,
disks, images, and snapshots using the Google Cloud Console and the gcloud
command-line tool.
To update the Cloud IAM policy for all members on a resource, see Getting and setting a resource's policy.
Console
- Go to the respective resource page for which you want to add permissions.
- For instances, go to the VM instances page.
- For disks, go to the Disks page.
- For snapshots, go to the Snapshots page.
- For images, go to the Images page.
- Select the checkboxes next to the resources you want to update.
- Click Show info panel to expand the permissions column.
- To add members:
- In the Add members field, add one or more members.
- In the Select a role dropdown menu, select one or more roles.
- Click Add to save your changes.
- To remove members:
- If the resource has policy bindings for one or more roles, those roles appear as exandable cards. Click on the role card for which you want to remove one or more members.
- Click the delete icon (
) to remove each role.
gcloud
To grant a role to a member on a resource, use the resource's
add-iam-policy-binding
subcommand with --member
and --role
flags.
gcloud compute [RESOURCE_TYPE] add-iam-policy-binding [RESOURCE_NAME] \
--member='[MEMBER]' \
--role='[ROLE]'
Or, to remove a policy binding, use the resource's
remove-iam-policy-binding
sub command with --member
and --role
flags.
gcloud compute [RESOURCE_TYPE] remove-iam-policy-binding [RESOURCE_NAME] \
--member='[MEMBER]' \
--role='[ROLE]'
where:
[RESOURCE_TYPE]
is the type of resource:disks
,images
,instances
,instance-templates
,sole-tenancy node-groups
,sole-tenancy node-templates
orsnapshots
.[RESOURCE_NAME]
is the name of the resource. For example,my_instance
.[MEMBER]
is member to add the binding for.- Should be of the form
user|group|serviceAccount:email
ordomain:domain
. For example,user:test-user@gmail.com
,group:admins@example.com
,serviceAccount:test123@example.domain.com
, ordomain:example.domain.com
. - Can also be one of the following special values:
allUsers
: anyone who is on the internet, with or without a Google Account.allAuthenticatedUsers
: anyone who is authenticated with a Google Account or a service account.
- Should be of the form
[ROLE]
is the role to add for that member
If you are granting access to a resource that is currently in beta, use
a gcloud beta compute
command instead.
Getting and setting a resource's policy
The Cloud IAM policy for a resource is a collection of statements that defines who has been granted access to that resource.
You can update the policy for a resource using the Read-Modify-Write pattern, where the current Cloud IAM policy for a resource is first retrieved, then updated, and finally set. See the Cloud IAM documentation for more information about this pattern.
gcloud
You can use either JSON or YAML files when executing gcloud
commands to
get or set a resource's policy. The examples in this section use JSON.
Retrieve the policy that you want to modify by executing the resource's
get-iam-policy
subcommand.gcloud compute [RESOURCE_TYPE] get-iam-policy [RESOURCE_NAME] --format json > policy.json
where:
[RESOURCE_TYPE]
is the type of resource:disks
,images
,instances
,instance-templates
, orsnapshots
.[RESOURCE_NAME]
is the name of the resource.
For example, to retrieve the Cloud IAM policy for a disk named
example-disk
, run:gcloud compute disks get-iam-policy example-disk --format json > policy.json
An empty JSON policy file will look similar to the following. The
etag
property is used to verify if the policy has changed since the last request.{ "etag": "ACAB" }
Using a text editor, update the JSON file. Construct a
bindings
object that contains an array. Each object in the array has an array ofmembers
and an associated role for those members. For example, to grantall-devs@example.com
andsome-devs@other-place.com
groups theroles/compute.imageUser
role and grantbob@example.com
theroles/compute.storageAdmin
role:{ "bindings": [ { "members": [ "group:all-devs@example.com", "group:other-devs@other-place.com" ], "role": "roles/compute.imageUser" }, { "members": [ "user:bob@example.com" ], "role": "roles/compute.storageAdmin" } ], "etag": "ACAB" }
Update the policy by executing the resource's
set-iam-policy
subcommand and providing the path to the JSON file that contains the new policy. The command can succeed only if theetag
value in the JSON file matches the resource's currentetag
value.gcloud compute [RESOURCE_TYPE] set-iam-policy [RESOURCE_NAME] policy.json
For example, to set the Cloud IAM policy for a disk named
example-disk
, run:gcloud compute disks set-iam-policy example-disk policy.json
The command outputs the updated policy, which includes an updated
etag
value.bindings: - members: - user:bob@example.com role: roles/compute.storageAdmin - members: - group:all-devs@example.com - group:other-devs@other-place.com role: roles/compute.imageUser etag: BwUjMhXbSPU=
API
To modify an existing policy:
Retrieve the existing policy by calling the resource's
getIamPolicy()
method.For example, on a disk:
GET https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/disks/[DISK_NAME]/getIamPolicy
The request returns the policy, including an array of
bindings
(if any bindings exist) and anetag
value. Theetag
property is used to verify if the policy has changed since the last request.{ "etag": "BwVvzaUs8EY=", "bindings":[ { "role":"roles/compute.storageAdmin", "members":[ "user:bob@example.com", "serviceAccount:service-account@my-project.iam.gserviceaccount.com" ] }, { "role":"roles/compute.imageUser", "members":[ "user:email1@gmail.com", "user:email2@gmail.com", "user:email3@gmail.com" ] } ] }
Modify the policy as needed then set the updated policy by calling
setIamPolicy()
.For example, if you want to revoke the
compute.imageUser
role foremail2@gmail.com
, the request will look similar to the following.POST https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/disks/[DISK_NAME]/setIamPolicy
{ "etag": "BwVvzaUs8EY=", "bindings":[ { "role":"roles/compute.storageAdmin", "members":[ "user:bob@example.com", "serviceAccount:service-account@my-project.iam.gserviceaccount.com" ] }, { "role":"roles/compute.imageUser", "members":[ "user:email1@gmail.com", "user:email3@gmail.com" ] } ] }
The response shows the updated policy, which includes an updated
etag
value.{ "etag": "BwVwGgz7Arg=", "bindings":[ { "role":"roles/compute.storageAdmin", "members":[ "user:bob@example.com", "serviceAccount:service-account@my-project.iam.gserviceaccount.com" ] }, { "role":"roles/compute.imageUser", "members":[ "user:email1@gmail.com", "user:email3@gmail.com" ] } ] }
Testing whether a caller has permissions
The testIamPermissions
API method takes a resource URL and a set of
permissions as input parameters, and returns the set of permissions that the
caller is allowed. You can use this method on any of the
supported resources.
You typically don't invoke testIamPermission
if you're using
Google Cloud directly to manage permissions. testIamPermissions
is
intended for integration with your proprietary software such as a customized
graphical user interface. For example, if you are building a GUI on top of the
Compute Engine API and your GUI has a "start" button that starts an instance,
you could call compute.instances.testIamPermissions()
to determine whether the
button should be enabled or disabled.
To test whether a caller has specific permissions on a resource:
Send a request to the resource and include in the request body a list of permissions to check for.
For example, on an instance, you might check for
compute.instances.start
,compute.instances.stop
, andcompute.instances.delete
.POST https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]/setIamPolicy
{ "permissions": [ "compute.instances.start", "compute.instances.stop", "compute.instances.delete" ] }
The request returns the permissions that are enabled for the caller.
{ "permissions": [ "compute.instances.start", "compute.instances.stop" ] }
Scenarios
Sharing specific images within an organization
Consider a company that has a set of IT-certified machine images and wants to grant certain teams access to certain images. Without Cloud IAM policies for Compute Engine resources, the company would either need to grant everyone access to all images or store the images in multiple projects. With Cloud IAM policies for Compute Engine resources, the company can keep all images in a single project for easier management and grant teams access only to the subset of images that they need for their jobs.
In the example below, there are multiple images in images-project
.
The all-devs@example.com
group has access to use the ubuntu-base-v1-0
image, but not the ubuntu-v1-1-test
image or the mysql-v1
image.
Additionally, the db-admins@example.com
group only has access to use the mysql-v1
image. You can
configure this setup by setting a Cloud IAM policy on the
ubuntu-base-v1-0
image that grants all-devs@example.com
the
Image User role and setting a
Cloud IAM policy on mysql-v1
that grants db-admin@example.com
the
Image User role.
To grant all-devs@example.com
permission to use the shared-image
image
using the gcloud
command line tool:
Get the Cloud IAM policy:
gcloud compute images get-iam-policy shared-image --format json > policy.json
Modify
policy.json
in a text editor to grantall-devs@example.com
theroles/compute.imageUser
role:{ "bindings": [ { "members": [ "group:all-devs@example.com" ], "role": "roles/compute.imageUser" } ], "etag": "ACAB" }
Apply the modified
policy.json
to the image.gcloud compute images set-iam-policy shared-image policy.json
Sharing specific images with the public
Suppose that you are a Google partner who publishes images for Compute Engine users. You can set a Cloud IAM policy on an image to share it with all authenticated users on Compute Engine.
To make shared-image
available to all Compute Engine users using the
Compute Engine API:
Get the Cloud IAM policy.
GET https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/images/shared-image/getIamPolicy
The request returns the policy.
{ "etag": "ACAB" }
Apply the modified policy.
POST https://compute.googleapis.com/compute/alpha/projects/[PROJECT_ID]/zones/[ZONE]/images/shared-image/setIamPolicy { "bindings": [ { "members": [ "allAuthenticatedUsers" ], "role": "roles/compute.imageUser" } ], "etag": "ACAB" }
The request returns the updated policy.
{ "etag": "BwVa45js9SQ=", "bindings": [ { "role": "roles/compute.imageUser", "members": [ "allAuthenticatedUsers" ] } ] }
Granting a teammate access to an instance to debug an issue
Suppose that you created an instance and want alice@example.com
to help debug
an issue. Grant alice@example.com
the
Compute Instance Admin (v1) role
on the instance by modifying the instance's Cloud IAM policy.
If the instance is configured to run as a service account and you want Alice to
be able to connect using SSH, set metadata, or attach a disk, grant
alice@example.com
the
Service Account User role
on the instance's service account. Granting this role on the service account
is necessary because those three operations allow Alice run commands on its
behalf. See Service account permissions
for more information about treating service accounts as a resource.
If you want Alice to manage the instance through the Cloud Console,
then grant her a role that has the compute.projects.get
permission. For
example, you can grant the
Compute Viewer role to Alice,
which contains this permission. This role can also view all
Compute Engine resources in the project, but it cannot read data from disks,
images, or snapshots. Alternatively, you can
create a custom role with the necessary
permissions.
Here's how to do this with gcloud
.
Get the Cloud IAM policy for the instance.
gcloud compute instances get-iam-policy example-instance --format json > policy.json
Modify
policy.json
in a text editor.{ "bindings": [ { "members": [ "user:alice@example.com" ], "role": "roles/compute.instanceAdmin.v1" } ], "etag": "ACAB" }
Apply the modified
policy.json
to the instance.gcloud compute instances set-iam-policy example-instance policy.json
Grant
alice@example.com
the Service Account User role on the instance's service account. Suppose that the instance's service account isdata-reader-service-account@[PROJECT_ID].iam.gserviceaccount.com
.gcloud iam service-accounts add-iam-policy-binding \ data-reader-service-account@[PROJECT_ID].iam.gserviceaccount.com \ --member="user:alice@example.com" \ --role="roles/iam.serviceAccountUser"
gcloud
returns the following:bindings: - members: - user:alice@example.com role: roles/iam.serviceAccountUser etag: BwVa42MC-aY=
Grant
alice@example.com
the Compute Viewer role on the projectgcloud projects add-iam-policy-binding [PROJECT_ID] \ --member=user:alice@example.com \ --role=roles/compute.viewer
gcloud
returns the following:bindings: - members: - user:alice@example.com role: roles/iam.serviceAccountUser [...] etag: BwVa42MC-aY=
Now Alice can see the instance in the Cloud Console and has permission to call any method on the instance. If Alice needs permissions on additional resources (for example, subnetworks or firewalls), then you need to grant her the appropriate predefined role (for example, Network User).
What's next
- Learn more about Service Accounts.
- Learn more about Compute Engine Cloud IAM Roles.
- Learn more about the permissions that are included in predefined Compute Engine roles.
- Learn how to create custom roles