Granting access to Compute Engine resources

Beta

This is a Beta release of
Cloud IAM policies for
Compute Engine resources
. This feature
is not covered by any SLA or deprecation policy and might be subject to backward-incompatible
changes.

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.

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.

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.

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

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.

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.

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 ubuntu-base-v1-0 image
using the gcloud command line tool:

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:

Get the Cloud IAM policy.

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

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.

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.

Note: You do not have to use the beta API to do this on a service account.
This functionality on service accounts is generally available.

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