Sharing Images, Snapshots, and Disks

You can share images, snapshots, and disks with users outside of your project or organization. Users with read access to those resources can use them to complete operations in other projects and organizations. For example, if you grant a user read access to an image or snapshot in your project, they can use those resources to create persistent disks in their own projects. Use IAM roles to share read access to your images, snapshots, and disks.

In some situations, you want those authorized users to have access to these storage resources only when they use those resources within your organization or certain projects. To limit the projects where users can use your images, snapshots, and disks to create resources, set the storage resource usage constraint as an organization policy.

To learn more about IAM roles, read the IAM documentation.

Before you begin

Limitations

Sharing storage resources has the following restrictions:

  • You can grant access to images, snapshots, and disks only at the project level.

  • It is not possible to share only specific images, snapshots, or disks.

  • It is not possible to grant roles to allAuthenticatedUsers or allUsers that allow access to images, snapshots, or disks.

  • You can set the 'constraints/compute.storageResourceUseRestrictions' constraint only at the organization level.

  • You must use the Compute Engine API to create images, snapshots, or disks from resources outside of your project. For example, you can reference images, snapshots, and disks in remote projects when you run methods that require you to specify a path to an image, snapshot, or disk. Some examples of these methods are:

Sharing storage resources across projects and organizations

You can share access to images, disks, and snapshots using the following IAM roles or permissions:

  • Images: The roles/compute.imageUser role or the compute.images.useReadOnly permission.
  • Snapshots: The roles/compute.storageAdmin role or the compute.snapshots.useReadOnly permission.
  • Disks: The roles/compute.storageAdmin role or the compute.disks.useReadOnly permission.

These roles and permissions allow you to share each resource type independently with other team members outside of your projects. For example, your company might have a specific project with 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. Then, you can grant the roles/compute.imageUser role to other team members so that team members can use these images in their own projects.

To grant the image sharing role, use the Console, the gcloud command-line tool, or the API. To learn how to use IAM, read the IAM documentation.

Console

  1. Go to the IAM page in the GCP Console.

    Go to the IAM page

  2. If prompted, select your project.
  3. If you are adding a new user:
    1. Click Add at the top of the page.
    2. Provide one or more email address of the account to which you want to grant access.
    3. Grant one or more roles to the member.
      • Images: Select Compute Engine > Compute Image User from the role selector.
      • Snapshots and Disks: Select Compute Engine > Compute Storage Admin from the role selector.
  4. Save your changes.

gcloud

Using the gcloud command-line tool, 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 [ROLE]

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.
  • [ROLE] is the role that you want to grant to the user. For images, specify roles/compute.imageUser. For snapshots and disks, specify roles/compute.storageAdmin.

For example, the following grants the roles/compute.imageUser role to john@example.com so that they can access 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 role should be part of the binding. For example:

{
   "policy": {
       "version": "0",
       "bindings": [
       {
           "role": "roles/compute.admin",
           "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 the Google APIs service account to call the Compute Engine API and perform relevant actions related to the group, such as recreating unhealthy instances and updating instances. 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 GCP 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

    Using the gcloud command-line tool, 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"
               ]
           }
           ]
       }
    

    }

Restricting use of your shared images, disks, and snapshots

After you have shared images, disks, and snapshots with other users, you can control where those users employ those resources. Set the constraints/compute.storageResourceUseRestrictions constraint to define the projects where users are permitted to use your storage resources.

You must have permission to modify your organization's policies to set these constraints. For example, the resourcemanager.organizationAdmin role has permission to set these constraints.

  1. Find the organization ID for your organization.

    gcloud organizations list
    
  2. Obtain the existing policy settings for your organization.

    gcloud beta resource-manager org-policies describe \
        compute.storageResourceUseRestrictions \
        --organization [ORGANIZATION_ID] > org-policy.yaml
    

    where [ORGANIZATION_ID] is your organization ID.

  3. Open the org-policy.yaml file in a text editor and modify the compute.storageResourceUseRestrictions constraint. Add the restrictions that you need or remove the restrictions that you no longer require. When you are done editing the file, save your changes. For example, you might set the following constraint entry in your policy file:

    constraint: compute.storageResourceUseRestrictions
    listPolicy:
      allowedValues:
        - under:organization/[ORGANIZATION_ID]
    
  4. Apply the policy.yaml file to your organization.

    gcloud beta resource-manager org-policies set-policy
    --organization [ORGANIZATION_ID] org-policy.yaml
    

    where [ORGANIZATION_ID] is your organization ID.

When you are done configuring the constraints in your organization policy, test those constraints to ensure that they create the restrictions that you need.

Using images from another project

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

Was this page helpful? Let us know how we did:

Send feedback about...

Compute Engine Documentation