Sharing Images Across Projects

This page describes how to share custom images with another project using the Compute Engine Image User role. To learn more about images, read the Images Overview. To learn more about roles, read the IAM documentation.

Compute Engine offers public OS images that you can customize and save to your project as custom images. By default, custom images are only available to the project where it was created. If you want to share custom images with other Google Cloud Platform projects, you can grant the Compute Engine Image User role, roles/compute.imageUser, to users of another project.

The compute.imageUser role allows users to get, list, and use images from your project, while preventing access to other resources. The role makes it easy to share your images using familiar Google Cloud Platform tools, such as the Identity and Access Management (IAM) API.

For example, your company might have a specific project that contains a list of qualified images that the rest of your company can use. You can assign a group to the project that is explicitly responsible for creating and maintaining images for the rest of the team by granting this group project editor permissions. Then, you can grant the Compute Engine Image User role to all other team members so that team members can use these images in their own projects.

Before you begin

Limitations

The following are restrictions for using this feature:

  • You can only grant the compute.imageUser role on the project level.

  • Granting the compute.imageUser role grants permissions to all images in the specific project. It is not possible to share specific images.

  • It is not possible to grant this role to allAuthenticatedUsers or allUsers.

Granting a user access to images

To grant the image sharing role, use the Console, gcloud, or the API. For details on using IAM, read the IAM documentation.

For example, assume that a User A owns Project A and wants to create VM instances using images owned by Project B. The owner of Project B must grant User A the compute.imageUser role on Project B. This grants User A the ability to use the images from Project B to create instances in Project A.

Console

  1. Go to the IAM page in the Cloud Platform Console.

    Go to the IAM page

  2. If prompted, select your project.
  3. If you are adding a new user:
    1. Click on Add at the top of the page.
    2. Select Compute Engine > Compute Image User from the role selector.
    3. Provide one or more email address(es) of the account you want to grant access to.
  4. If you are granting the role to an existing user, look for the user's information in the Members column.
    1. In the Role(s) column, expand the dropdown list of roles for the service account.
    2. Select Compute Engine > Compute Image User from the role selector.
  5. Save your changes.

gcloud

In gcloud, add a binding to the Cloud IAM policy for the image project:

gcloud projects add-iam-policy-binding [PROJECT_ID] \
    --member [MEMBER_TYPE]:[ACCOUNT] --role roles/compute.imageUser

where:

  • [PROJECT_ID] is the ID of the project containing images you want to share.
  • [MEMBER_TYPE] is the type of account you are granting access to. For example, use user for individual users, serviceAccount for a service account, and group for a Google group.
  • [ACCOUNT] is the email address of the account to grant this role. For example, for a service account, this might be my-sa@my-project-123.iam.gserviceaccount.com.

For example, the following grants a user whose email is john@example.com access to the images in a project named database-images:

gcloud projects add-iam-policy-binding database-images \
    --member user:john@example.com --role roles/compute.imageUser

API

In the API, make a POST request to the following URL, where [PROJECT_ID] is the ID of the project containing the images you want to share.

POST https://cloudresourcemanager.googleapis.com/v1/projects/$[PROJECT_ID]:setIamPolicy

The request body should contain the list of bindings you want to apply to this project. The roles/compute.imageUser role should be part of the binding. For example:

{
   "policy": {
       "version": "0",
       "bindings": [
       {
           "role": "roles/owner",
           "members": [
               "user:example@gmail.com"
           ]
       },
       {
           "role": "roles/compute.imageUser",
           "members": [
               "user:john@gmail.com"
           ]
       }
       ]
   }

}

Granting a managed instance group access to images

Compute Engine allows you to create groups of instances, either as managed or unmanaged instance groups. If you create a managed instance group, Compute Engine uses a the Google APIs service account to call the Compute Engine API and perform relevant actions related to the group, such as recreating unhealthy instances, updating an instance, and so on. If you want to create a managed instance group using an image from another project, you can grant the compute.imageUser role to the APIs service account belonging to the project creating the managed instance group.

For example, assume that Project A wants to create managed instance groups using images owned by Project B. The owner of Project B must grant the Google APIs service account of Project A the compute.imageUser role on Project B. This grants the account the ability to use the images from Project B to create managed instance groups in Project A.

After granting the compute.imageUser role, you can provide the URL of the specific image when you create the instance template for the group.

Follow these steps to get the service account email and grant the account access:

  1. Go to the IAM page in the Cloud Platform Console of the project that will be creating the managed instance groups.

    Go to the IAM page

  2. If prompted, select your project from the list.
  3. Look for the Google APIs service account, which has the email address in the following format:

    [PROJECT_NUMBER]@cloudservices.gserviceaccount.com
    
  4. Make note of the email address above. Next, grant the account access to the project that owns the images.

    Console

    1. While still in the Google Cloud Platform Console, go to the IAM page of the project that contains the images you want access to.

      Go to the IAM page

    2. Select the project from the project list.
    3. Click the Add button to add a new member.
    4. In the Members box, enter the email address of the service account.
    5. Expand the Roles dropdown and select Compute Engine > Compute Image User (beta).
    6. Click Add to add the account.

    gcloud

    In gcloud, add a binding to the Cloud IAM policy for the project:

    gcloud projects add-iam-policy-binding [PROJECT_ID] \
        --member serviceAccount:[SERVICE_ACCOUNT_EMAIL] --role roles/compute.imageUser

    where:

    • [PROJECT_ID] is the ID of the project containing images you want to share.
    • [SERVICE_ACCOUNT_EMAIL] is the email of the service account.

    For example:

    gcloud projects add-iam-policy-binding database-images \
        --member serviceAccount:123456789012@cloudservices.gserviceaccount.com  \
        --role roles/compute.imageUser

    API

    In the API, make a POST request to the following URL, where [PROJECT_ID] is the ID of the project containing the images you want to share.

    POST https://cloudresourcemanager.googleapis.com/v1/projects/$[PROJECT_ID]:setIamPolicy
    

    The request body should contain the list of bindings you want to apply to this project. The roles/compute.imageUser role should be part of the binding. For example:

    {
       "policy": {
           "version": "0",
           "bindings": [
           {
               "role": "roles/owner",
               "members": [
                   "user:example@gmail.com"
               ]
           },
           {
               "role": "roles/compute.imageUser",
               "members": [
                   "serviceAccount:123456789012@cloudservices.gservbiceaccount.com"
               ]
           }
           ]
       }
    

    }

Accessing images

If someone has granted you the compute.imageUser role, you can access the images in the project by specifying the image project in your requests. For example, to get a list of images available to you:

gcloud compute images list --project [IMAGE_PROJECT]

To learn how to use an image to create new resources, such as creating an instance, read Creating and starting an instance.

For example, the following gcloud command creates an instance using an image called database-image-a from project database-images:

gcloud compute instances create test-instance --image database-image-a --image-project database-images

Similarly, you can use the image to create persistent disks. For information on creating a disk from an image, read Creating a standalone root persistent disk.

What's next

Send feedback about...

Compute Engine Documentation