Managing access to Compute Engine resources

You can use Cloud IAM policies to manage access to your Compute Engine resources. Cloud IAM policies control who (identity) has what access (role) to which resources. No user can access a Google Cloud resource until they are granted a role with the appropriate permissions.

Users with permissions to change an IAM policy can do the following:

A predefined role is curated by Google and contains a set of related permissions. For example, the Compute Engine Instance Admin role (roles/compute.instanceAdmin) grants permissions related to virtual machine (VM) instance administration. For information about predefined roles that are specific to Compute Engine, see Compute Engine roles.

Users can also assign one of the primitive roles to another user: Project Owner, Project Editor, or Project Viewer. However, these primitive roles grant a wide range of permissions to many Google Cloud Services. When possible, we recommend using a predefined or custom role.

This guide describes how to grant permissions to individual Compute Engine resources by using IAM roles. For general information about how to grant, change, and revoke access to resources unrelated to Compute Engine, see the IAM documentation for Granting, changing, and revoking access to resources. For best practices, recommendations, and general IAM information, read the IAM overview.

This document does not describe how to grant access to an organization, project, or folder.

Before you begin

Supported resources

Compute Engine supports resource-level access control for the following resources:

Other Compute Engine resources do not support resource-level access control, so you must manage access to other types of resources at the project, folder, or organization levels. For information about organizations, folders, or projects, see Resource hierarchy.

Granting access to Compute Engine resources

Before you grant an IAM role to a user for a resource, check which roles are available to grant on a particular resource. For more information, see Viewing the grantable roles on resources.

To grant users permission to access specific Compute Engine resources, complete the following steps.

Console

  1. In the Google Cloud Console, go to the respective resource page for which you want to add permissions.
  2. Select the checkboxes next to the resources you want to update.
  3. Click Show info panel to expand the permissions column.
  4. In the Add members field, add one or more members.
  5. In the Select a role list, select one or more roles.
  6. Click Add to save your changes.

gcloud

To grant a role to a member on a resource, use the resource's add-iam-policy-binding subcommand with the --member and --role flags.

gcloud compute resource-type add-iam-policy-binding resource-name \
    --member='member' \
    --role='role'

Replace the following:

  • resource-type: The type of resource. Valid values include:
    • disks
    • images
    • instances
    • instance-templates
    • sole-tenancy node-groups
    • sole-tenancy node-templates
    • snapshots
  • resource-name: The name of the resource. For example, my_instance.
  • member: A valid identity to which you want to grant the role. Must be of the form user|group|serviceAccount:email or domain:domain. For example:
    • user:test-user@gmail.com
    • group:admins@example.com
    • serviceAccount:test123@example.domain.com
    • domain:example.domain.com
  • role: The role to assign this identity.

If you are granting access to a resource that is currently in beta, use a gcloud beta compute command instead.

API

To modify an IAM policy through the API, do the following:

  1. Read the existing policy with the resource's respective getIamPolicy method. For example, the following HTTP request reads the IAM policy of a VM:

    POST https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance:getIamPolicy

    Replace the following:

    • project-id: Project ID this VM belongs to.
    • zone: The zone of the VM. For regional or global resources, replace zones/zone with regions/region or global.
    • instance: The name of the VM instance.

    Compute Engine returns the current policy in the response.

  2. Edit the policy with a text editor to add or remove members and their associated roles. For example, to grant the compute.admin role to email@example.com, add the following new binding to policy:

    {
      "members": [
        "user:email@example.com"
      ],
      "role":"roles/compute.admin"
    }
    
  3. Write the updated policy with setIamPolicy():

    POST https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance:setIamPolicy

    Replace the following:

    • project-id: Project ID this VM belongs to.
    • zone: The zone of the VM. For regional or global resources, replace zones/zone with regions/region or global.
    • instance: The name of the VM instance.

    In the body of the request, provide the updated IAM policy from the previous step.

Revoking access to resources

As a best practice, after members no longer need access to your Compute Engine resources, revoke their access.

Console

  1. In the Google Cloud Console, go to the respective resource page for which you want to add permissions.
  2. Select the checkboxes next to the resources you want to update.
  3. Click Show info panel to expand the permissions column.
  4. Click the role card for the resource from which you want to remove members. This expands the card and shows members with that role for that resource.
  5. Click Deletedelete to remove a member from that role.

gcloud

To remove a role from a member for a resource, use the resource's remove-iam-policy-binding subcommand with the --member and --role flags.

gcloud compute resource-type remove-iam-policy-binding resource-name \
    --member='member' \
    --role='role'

Replace the following:

  • resource-type: Type of resource. Valid values include:
    • disks
    • images
    • instances
    • instance-templates
    • sole-tenancy node-groups
    • sole-tenancy node-templates
    • snapshots
  • resource-name: Name of the resource. For example, my_instance.
  • member: The identity you want to remove. Must be of the form user|group|serviceAccount:email or domain:domain. For example:
    • user:test-user@gmail.com
    • group:admins@example.com
    • serviceAccount:test123@example.domain.com
    • domain:example.domain.com
  • role: Role from which you want to remove the identity.

If you are revoking access to a resource that is currently in beta, use a gcloud beta compute command instead.

API

To modify an IAM policy directly through the API, do the following:

  1. Read the existing policy with the resource's respective getIamPolicy method. For example, the following HTTP request reads the IAM policy of a VM:

    POST https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance:getIamPolicy

    Replace the following:

    • project-id: The project ID for this VM instance.
    • zone: The zone of the VM. For regional or global resources, replace zones/zone with regions/region or global.
    • instance: The name of the VM instance.

    Compute Engine returns the current policy in the response.

  2. Edit the policy with a text editor to remove members from the associated roles. For example, remove email@example.com from the compute.admin role:

    {
      "members": [
        "user:owner@example.com"
      ],
      "role":"roles/compute.admin"
    }
    
  3. Write the updated policy with setIamPolicy():

    POST https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance:setIamPolicy

    Replace the following:

    • project-id: Project ID this VM belongs to.
    • zone: The zone of the VM. For regional or global resources, replace zones/zone with regions/region or global.
    • instance: The name of the VM instance.

    In the body of the request, provide the updated IAM policy from the previous step.

Testing whether a caller has permissions

If you don't know what permissions an identity has, use the testIamPermissions API method to check which permissions are available to an identity.

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

Typically, testIamPermissions is intended for integration with your proprietary software, such as a customized graphical user interface. You typically don't call testIamPermissions if you're using Google Cloud directly to manage permissions.

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:

  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"
      ]
    }
    

Modifying resource access for multiple members

If you want to modify access to Compute Engine resources for multiple members simultaneously, review recommendations on how to modify an IAM policy programmatically.

What's next