Managing access to Compute Engine resources

This page describes how you can exercise the principle of least privilege bygranting access to specific Compute Engineresources instead of granting access to a parent resource such as aproject, folder, or organization.

You grant access to a resource by setting anIdentity and Access Management (IAM) policyon the resource. The policy binds one or more members, such as a user or aservice account, to one or moreroles. Each rolecontains a list of permissions that let the member interact with the resource.

If you grant access to aparent resource(for example, to a project), you implicitly grant access to all its childresources (for example, to all VMs in that project). To limit access toresources, set IAM policies on lower-level resources whenpossible, instead of at the project level or above.

For general information about how to grant, change, and revoke access toresources unrelated to Compute Engine, for example, to grant access toa Google Cloud project, see the IAM documentation forGranting, changing, and revoking access to resources.

Before you begin

Required roles

To get the permissions that you need to manage access to Compute Engine resources, ask your administrator to grant you theCompute Admin (roles/compute.admin) IAM role on the resource. For more information about granting roles, seeManage access to projects, folders, and organizations.

This predefined role contains the permissions required to manage access to Compute Engine resources. To see the exact permissions that are required, expand theRequired permissions section:

Required permissions

The following permissions are required to manage access to Compute Engine resources:

  • To grant or revoke access to resources:
    • compute.projects.get on the project
    • compute.RESOURCE_TYPE.get on the resource
    • compute.RESOURCE_TYPE.getIamPolicy on the resource
    • compute.RESOURCE_TYPE.setIamPolicy on the resource
  • To test caller permissions:compute.RESOURCE_TYPE.getIamPolicy on the resource

    ReplaceRESOURCE_TYPE with the resource that you want to manage access to. For exampleinstances,instanceTemplates, orimages.

You might also be able to get these permissions withcustom roles or otherpredefined roles.

Supported resources

To view a list of Compute Engine resources that support resource-levelaccess control, seeResource types that accept IAM policiesand filter forCompute Engine.

For other Compute Engine resources that don't support resource-levelaccess control, you must manage access to those resources at the project,folder, or organization levels. For information about organizations, folders,or projects, seeResource hierarchy.

Granting access to Compute Engine resources

Aprincipal, such as a user or service account, can access Compute Engineresources. Anidentity is a property of a principal. A principal'sidentity is typically represented by an email address associated with the account.

Before you grant an IAM role to a principal for a resource,check which roles are available to grant on a particular resource. For moreinformation, seeViewing the grantable roles on resources.

To grant permission to access specific Compute Engine resources,set anIAM policy on the resource.

Note: When managing access for users inexternal identity providers, replace instances of Google Account principal identifiers—likeuser:kiran@example.com,group:support@example.com, anddomain:example.com—with appropriateWorkforce Identity Federation principal identifiers.

Console

  1. In the Google Cloud console, go to the respective resource page for whichyou want to add permissions.
  2. Select the checkboxes next to the resources you want to update.
  3. Complete the following steps based on the resource page.
    • For VM instances, clickPermissions.
    • For all other resources, complete the following:
      1. Check if the info panel is visible. If it is not visible, clickShow info panel.
      2. Select thePermissions tab.
  4. ClickAdd principal.
  5. Add the identity for the principal and select the required role.
  6. To save your changes, clickSave.

gcloud

To grant a role to a principal on a resource, use that resource'sadd-iam-policy-binding sub-command with the--member and--role flags.

gcloud computeRESOURCE_TYPE add-iam-policy-bindingRESOURCE_NAME \    --member='PRINCIPAL' \    --role='ROLE'

Replace the following:

  • RESOURCE_TYPE: the type of resource. Valid valuesinclude:
    • disks
    • images
    • instances
    • instance-templates
    • machine-images
    • reservations
    • sole-tenancy node-groups
    • sole-tenancy node-templates
    • snapshots
  • RESOURCE_NAME: the name of the resource. Forexample,my_instance.
  • PRINCIPAL: a valid identity for the principalthat you want to grant the role. Must be of the formuser|group|serviceAccount:EMAIL_ADDRESS ordomain:DOMAIN_ADDRESS. 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 principal.

If you are granting access to a resource that is in preview, useagcloud beta compute command instead.

REST

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

  1. Read the existing policy with the resource's respectivegetIamPolicy 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/VM_NAME:getIamPolicy

    Replace the following:

    • PROJECT_ID: the project ID of the projectthis VM belongs to.
    • ZONE: the zone of the VM. For regional orglobal resources, replacezones/ZONE withregions/REGION orglobal.
    • VM_NAME: 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 principals and their associated roles. For example, to grant thecompute.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 withsetIamPolicy():

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME:setIamPolicy

    Replace the following:

    • PROJECT_ID: the project ID of the projectthis VM belongs to.
    • ZONE: the zone of the VM. For regional orglobal resources, replacezones/ZONE withregions/REGION orglobal.
    • VM_NAME: the name of the VM instance.

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

Revoking access to resources

As a best practice, after principals no longer need access to yourCompute Engine resources, revoke their access.

Console

  1. In the Google Cloud console, go to the respective resource page for whichyou want to add permissions.
  2. Select the checkboxes next to the resources you want to update.
  3. Complete the following steps based on the resource page.
    • For VM instances, clickPermissions.
    • For all other resources, complete the following:
      1. Check if the info panel is visible. If it is not visible, clickShow info panel.
      2. Select thePermissions tab.
  4. Click the role card from which you want to remove principals. This expandsthe card and shows users with that role for that resource.
  5. To remove a principal from that role,clickDelete.

gcloud

To remove a role from a principal for a resource, use the resource'sremove-iam-policy-binding sub-command with the--member and--roleflags.

gcloud computeRESOURCE_TYPE remove-iam-policy-bindingRESOURCE_NAME \    --member='MEMBER' \    --role='ROLE'

Replace the following:

  • RESOURCE_TYPE: type of resource. Valid valuesinclude:
    • disks
    • images
    • instances
    • instance-templates
    • machine-images
    • reservations
    • sole-tenancy node-groups
    • sole-tenancy node-templates
    • snapshots
  • RESOURCE_NAME: name of the resource.For example,my_instance.
  • PRINCIPAL: a valid identity for the principal.Must be of the formuser|group|serviceAccount:EMAIL_ADDRESS ordomain:DOMAIN_ADDRESS. 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 removethe principal.

If you are revoking access to a resource that is in preview, useagcloud beta compute command instead.

REST

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

  1. Read the existing policy with the resource's respectivegetIamPolicy 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/VM_NAME:getIamPolicy

    Replace the following:

    • PROJECT_ID: the project ID of the projectthis VM belongs to.
    • ZONE: the zone of the VM. For regional orglobal resources, replacezones/ZONEwithregions/REGION orglobal.
    • VM_NAME: 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 thecompute.admin role:

    {  "members": [    "user:owner@example.com"  ],  "role":"roles/compute.admin"}

  3. Write the updated policy withsetIamPolicy():

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME:setIamPolicy

    Replace the following:

    • PROJECT_ID: the project ID of the projectthis VM belongs to.
    • ZONE: the zone of the VM. For regional orglobal resources, replacezones/ZONE withregions/REGION orglobal.
    • VM_NAME: the name of the VM instance.

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

Testing whether a caller has permissions

If you don't know what permissions an identity has, use thetestIamPermissions API method to check which permissions are available toan 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 thismethod on any of thesupported resources.

Typically,testIamPermissions is intended for integration with yourproprietary software, such as a customized graphical user interface. Youtypically don't calltestIamPermissions if you're using Google Clouddirectly to manage permissions.

For example, if you are building a GUI on top of the Compute Engine API andyour GUI has a "start" button that starts an instance, you could callcompute.instances.testIamPermissions() to determine whether the button shouldbe 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 ofpermissions to check for.

    For example, on an instance, you might check forcompute.instances.start,compute.instances.stop, andcompute.instances.delete.

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/testIamPermissions    {      "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 multiplemembers simultaneously, review recommendations on how tomodify an IAM policy programmatically.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.