Granting access to Compute Engine resources

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:
  1. Install or update to the latest version of the gcloud command-line tool.
  2. 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:

• disks
• images
• instances
• instanceTemplates
• nodeGroups
• nodeTemplates
• snapshots

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.

Permissions required for this task

To perform this task, you must have the following permissions.

• compute.[RESOURCE_TYPE].getIamPolicy for the [RESOURCE_TYPE] to view the current Cloud IAM policy on the resource.
• compute.[RESOURCE_TYPE].setIamPolicy for the [RESOURCE_TYPE] to update the Cloud IAM policy on the resource.

Console

1. 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.
2. Select the checkboxes next to the resources you want to update.
3. Click Show info panel to expand the permissions column.
4. To add members:
   1. In the Add members field, add one or more members.
   2. In the Select a role dropdown menu, select one or more roles.
   3. Click Add to save your changes.
5. To remove members:
   1. 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.
   2. 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 or snapshots.
• [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 or domain:domain. For example, user:[e-mail], group:[e-mail], serviceAccount:[e-mail], or domain: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.
• [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.

Permissions required for this task

To perform this task, you must have the following permissions.

• compute.[RESOURCE_TYPE].getIamPolicy for the [RESOURCE_TYPE] to view the current Cloud IAM policy on the resource.
• compute.[RESOURCE_TYPE].setIamPolicy for the [RESOURCE_TYPE] to update the Cloud IAM policy on the resource.

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.

1. 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, or snapshots.
   • [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
   

2. 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"
   }
   

3. Using a text editor, update the JSON file. Construct a bindings object that contains an array. Each object in the array has an array of members and an associated role for those members. For example, to grant [e-mail] and [e-mail] groups the roles/compute.imageUser role and grant [e-mail] the roles/compute.storageAdmin role:

   {
     "bindings": [
       {
         "members": [
           "group:[e-mail]",
           "group:[e-mail]"
         ],
         "role": "roles/compute.imageUser"
       },
       {
         "members": [
           "user:[e-mail]"
         ],
         "role": "roles/compute.storageAdmin"
       }
     ],
     "etag": "ACAB"
   }
   

4. 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 the etag value in the JSON file matches the resource's current etag 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
   

5. The command outputs the updated policy, which includes an updated etag value.

   bindings:
   - members:
     - user:[e-mail]
       role: roles/compute.storageAdmin
   - members:
     - group:[e-mail]
     - group:[e-mail]
       role: roles/compute.imageUser
   etag: BwUjMhXbSPU=
   

API

To modify an existing policy:

1. 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
   

2. The request returns the policy, including an array of bindings (if any bindings exist) and an etag value. The etag property is used to verify if the policy has changed since the last request.

   {
     "etag": "BwVvzaUs8EY=",
     "bindings":[
       {
         "role":"roles/compute.storageAdmin",
         "members":[
           "user:[e-mail]",
           "serviceAccount:[e-mail]"
         ]
       },
       {
         "role":"roles/compute.imageUser",
         "members":[
           "user:[e-mail]",
           "user:[e-mail]",
           "user:[e-mail]"
         ]
       }
     ]
   }
   

3. Modify the policy as needed then set the updated policy by calling setIamPolicy().

   For example, if you want to revoke the compute.imageUser role for [e-mail], 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:[e-mail]",
           "serviceAccount:[e-mail]"
         ]
       },
       {
         "role":"roles/compute.imageUser",
         "members":[
           "user:[e-mail]",
           "user:[e-mail]"
         ]
       }
     ]
   }
   

4. The response shows the updated policy, which includes an updated etag value.

   {
     "etag": "BwVwGgz7Arg=",
     "bindings":[
       {
         "role":"roles/compute.storageAdmin",
         "members":[
           "user:[e-mail]",
           "serviceAccount:[e-mail]"
         ]
       },
       {
         "role":"roles/compute.imageUser",
         "members":[
           "user:[e-mail]",
           "user:[e-mail]"
         ]
       }
     ]
   }
   

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.

Permissions required for this task

To perform this task, you must have the following permissions.

• compute.[RESOURCE_TYPE].getIamPolicy for the [RESOURCE_TYPE] to view the current Cloud IAM policy on the resource.

To test whether a caller has specific permissions on a resource:

1. 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, and compute.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"
      ]
   }
   

2. 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 [e-mail] 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 [e-mail] 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 [e-mail] the Image User role and setting a Cloud IAM policy on mysql-v1 that grants [e-mail] the Image User role.

To grant [e-mail] permission to use the shared-image image using the gcloud command line tool:

1. Get the Cloud IAM policy:

   gcloud compute images get-iam-policy shared-image --format json > policy.json
   

2. Modify policy.json in a text editor to grant [e-mail] the roles/compute.imageUser role:

   {
     "bindings": [
       {
         "members": [
           "group:[e-mail]"
         ],
         "role": "roles/compute.imageUser"
       }
     ],
     "etag": "ACAB"
   }
   

3. 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.

Note: Granting a role to all authenticated users is not allowed on a project-level Cloud IAM policy. This reduces the chance of an organization accidentally making their entire project readable by anyone.

To make shared-image available to all Compute Engine users using the Compute Engine API:

1. Get the Cloud IAM policy.

   GET https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/images/shared-image/getIamPolicy
   

2. The request returns the policy.

   {
    "etag": "ACAB"
   }
   

3. 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"
   }
   

4. 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 [e-mail] to help debug an issue. Grant [e-mail] 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 [e-mail] 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.

1. Get the Cloud IAM policy for the instance.

   gcloud compute instances get-iam-policy example-instance --format json > policy.json
   

2. Modify policy.json in a text editor.

   {
     "bindings": [
       {
         "members": [
           "user:[e-mail]"
         ],
         "role": "roles/compute.instanceAdmin.v1"
       }
     ],
     "etag": "ACAB"
   }
   

3. Apply the modified policy.json to the instance.

   gcloud compute instances set-iam-policy example-instance policy.json
   

4. Grant [e-mail] the Service Account User role on the instance's service account. Suppose that the instance's service account is data-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:[e-mail]" \
        --role="roles/iam.serviceAccountUser"
   

   gcloud returns the following:

    bindings:
    - members:
      - user:[e-mail]
      role: roles/iam.serviceAccountUser
    etag: BwVa42MC-aY=
   

5. Grant [e-mail] the Compute Viewer role on the project

   gcloud projects add-iam-policy-binding [PROJECT_ID] \
       --member=user:[e-mail] \
       --role=roles/compute.viewer
   

   gcloud returns the following:

   bindings:
   - members:
     - user:[e-mail]
     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