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.

You can currently grant access on the following Compute Engine resources.

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

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 (identities) that can be included in a Cloud IAM policy.

Before you begin

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 Platform 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

  1. 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. 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 (delete icon that resembles a trash can) 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 beta 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 beta 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, 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:test-user@gmail.com, group:admins@example.com, serviceAccount:test123@example.domain.com, 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

For example, to grant a member the Storage Admin role on a specific disk, use a command like:

gcloud compute disks add-iam-policy example-disk \
    --member='user:test-user@gmail.com' \
    --role='roles/compute.storageAdmin'

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.

  1. Retrieve the policy that you want to modify by executing the resource's get-iam-policy subcommand.

    gcloud beta [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 beta 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 all-devs@example.com and some-devs@other-place.com groups the roles/compute.imageUser role and grant bob@example.com the roles/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"
    }
    

  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 beta [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 beta disks set-iam-policy example-disk policy.json
    

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

  1. Retrieve the existing policy by calling the resource's getIamPolicy() method.

    For example, on a disk:

    GET https://www.googleapis.com/compute/beta/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: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"
          ]
        }
      ]
    }
    

  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 email2@gmail.com, the request will look similar to the following.

    POST https://www.googleapis.com/compute/beta/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" ] } ] }

  4. 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 has been added to instances, disks, images, and snapshots. It takes the resource URL and a set of permissions as input parameters, and returns the set of permissions that the caller is allowed.

You typically don't invoke testIamPermission if you're using GCP 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:

  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://www.googleapis.com/compute/beta/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. all- devs@example.com have 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 ubuntu-base-v1-0 image using the gcloud command line tool:

  1. Get the Cloud IAM policy.

    gcloud alpha compute images get-iam-policy ubuntu-base-v1-0 --format json > policy.json
    

  2. Modify policy.json in a text editor to grant all-devs@example.com the roles/compute.imageUser role:

    { "bindings": [ { "members": [ "group:all-devs@example.com" ], "role": "roles/compute.imageUser" } ], "etag": "ACAB" }

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

    gcloud alpha compute images set-iam-policy ubuntu-base-v1-0 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:

  1. Get the Cloud IAM policy.

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

  2. The request returns the policy.

    {
      "etag": "ACAB"
    }
    

  3. Apply the modified policy.

    POST https://www.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 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 GCP 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 beta compute instances get-iam-policy example-instance --format json > policy.json
    

  2. Modify policy.json in a text editor.

    {
      "bindings": [
        {
          "members": [
            "user:alice@example.com"
          ],
          "role": "roles/compute.instanceAdmin.v1"
        }
      ],
      "etag": "ACAB"
    }
    

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

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

  4. Grant alice@example.com 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:alice@example.com" \
        --role="roles/iam.serviceAccountUser"
    
    bindings:
    - members:
      - user:alice@example.com
      role: roles/iam.serviceAccountUser
    etag: BwVa42MC-aY=
    
    

  5. Grant alice@example.com the Compute Viewer role on the project

    gcloud projects add-iam-policy-binding [PROJECT_ID] \
        --member=user:alice@example.com \
        --role=roles/compute.viewer
    
    bindings:
    - members:
      - user:alice@example.com
      role: roles/iam.serviceAccountUser
    [...]
    etag: BwVa42MC-aY=
    
    

Now Alice can see the instance in the GCP 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

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

Compute Engine Documentation