Prerequisites for importing and exporting VM images

Linux Windows
The image import feature on Compute Engine is being moved to Migrate to Virtual Machines. We recommend that you use the newimage import feature on Migrate to Virtual Machines to import your virtual disks to Google Cloud.

This document describes the prerequisites for importing and exporting imageson Compute Engine.

You can share virtual machine (VM) instances, virtual disk files, and machineimages from other cloud environments or from your on-premises environment byimporting and exporting images from Cloud Storage. The followingchecklist summarizes the requirements that you need to meet before you importand export images:

  1. Set up access to a Cloud Storage bucket
  2. Grant required roles to your user account
  3. Grant required roles to the Cloud Build service account
  4. Grant required roles to the Compute Engine service account

Before you begin

Set up access to a Cloud Storage bucket

You must have access to a Cloud Storage bucket thatthe import or export tool can use. If you don't have a Cloud Storagebucket, seeCreate a Cloud Storage bucket.

To set up access to your Cloud Storage bucket, seeGrant requiredroles to your account andCompute Engine serviceaccount.

  • If you're exporting an image, the export tool uploads the image to the Cloud Storage bucket.

  • If you're importing an image, you must first upload the image to the Cloud Storage bucket. The import tool downloads the file from the Cloud Storage bucket to Compute Engine, and then the tool creates an image in Compute Engine from that disk file.

Grant required IAM roles

The VM image import and export tool requires the following accounts to performthe operation on its behalf:

  • User account. The account from which you're running the import and exportcommands.
  • Cloud Build service account. A default Cloud Buildservice account that is created when the import or export tool enables theCloud Build API.
  • Compute Engine service account. A default or customCompute Engine service account that is required for the import andexport workflow.

Grant required roles to your user account

To import or export images, your user account requires the following roles:

  • Storage Admin role (roles/storage.admin)
  • Viewer role (roles/viewer)
  • Project IAM Admin role (roles/resourcemanager.projectIamAdmin)
  • Cloud Build Editor role (roles/cloudbuild.builds.editor)

Console

  1. Go to theIAM & Admin page for theproject or organization.

    Go to IAM & Admin

  2. Locate your account and clickEdit.

  3. In theSelect a role list, select the following roles:

    • Cloud Storage>Storage Admin
    • Project>Viewer
    • Resource Manager>Project IAM Admin
    • Cloud Build>Cloud Build Editor
  4. Save your changes.

gcloud

In the following steps, you use thegcloud projects add-iam-policy-bindingcommand to grant therequired roles at the project level.

  1. Grant theroles/storage.admin role:

    gcloud projects add-iam-policy-bindingPROJECT_ID \  --member='MEMBER' \  --role='roles/storage.admin'

    Replace the following:

    • PROJECT_ID: theGoogle Cloud project IDfor your project
    • MEMBER: the account that runs theimport and export commands—for example,user:export-user@gmail.com
  2. Grant theroles/viewer role:

    gcloud projects add-iam-policy-bindingPROJECT_ID \  --member='MEMBER' \  --role='roles/viewer'
  3. Grant theroles/resourcemanager.projectIamAdmin role:

    gcloud projects add-iam-policy-bindingPROJECT_ID \  --member='MEMBER' \  --role='roles/resourcemanager.projectIamAdmin'
  4. Grant theroles/cloudbuild.builds.editor role:

    gcloud projects add-iam-policy-bindingPROJECT_ID \  --member='MEMBER' \  --role='roles/cloudbuild.builds.editor'

REST

  1. Read the existing policy with the resource'sgetIamPolicy method. Forprojects, use theprojects.getIamPolicy method.

    POST https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID:getIamPolicy

    ReplacePROJECT_ID with the projectID—for example,my-project-1.

  2. To grant the required roles to your account, edit the policy witha text editor.

    For example, to grant the required role to your accountuser:export-user@gmail.com, add the following binding to the policy:

    {   {     "role":"roles/storage.admin",     "member":[       "user:export-user@gmail.com"     ]   }   {     "roles":"roles/viewer",     "member":[       "user:export-user@gmail.com"     ]   }   {     "roles":"roles/resourcemanager.projectIamAdmin",     "member":[       "user:export-user@gmail.com"     ]   }   {     "roles":"roles/cloudbuild.builds.editor",     "member":[       "user:export-user@gmail.com"     ]   }}
  3. To write the updated policy, use thesetIamPolicy method.

    For example, to seta policy at the project level, use theproject.setIamPolicymethod. Inthe body of the request, provide the updated IAM policyfrom the previous step.

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

Grant required roles to the Cloud Build service account

When you use the Google Cloud console or the gcloud CLI to importor export images for the first time, the tool attempts to enablethe Cloud Build API and grant the required roles to theCloud Build service account.

The service account used for Cloud Build depends on whether you usedCloud Build on the project before May 2024.If yes, the legacy Cloud Build service account is used for futurebuilds. Otherwise, the default Compute Engine service account is used.

  • Service Account Token Creator role (roles/iam.serviceAccountTokenCreator)
  • Service Account User role (roles/iam.serviceAccountUser)
  • Compute Admin role (roles/compute.admin)

    To avoid granting the Compute Admin role, you can create a custom role with the following Compute Engine IAM permissions andgrant it to the Cloud Build service account:

    Permissions required for the custom role

    The Cloud Build service account must have the followingpermissions:
    • compute.disks.create
    • compute.disks.delete
    • compute.disks.get
    • compute.disks.getIamPolicy
    • compute.disks.list
    • compute.disks.resize
    • compute.disks.setLabels
    • compute.disks.use
    • compute.disks.useReadOnly
    • compute.images.create
    • compute.images.get
    • compute.images.getFromFamily
    • compute.images.getIamPolicy
    • compute.images.list
    • compute.images.useReadOnly
    • compute.instances.attachDisk
    • compute.instances.create
    • compute.instances.delete
    • compute.instances.detachDisk
    • compute.instances.get
    • compute.instances.getSerialPortOutput
    • compute.instances.list
    • compute.instances.setLabels
    • compute.instances.setMetadata
    • compute.instances.setServiceAccount
    • compute.machineTypes.list
    • compute.networks.list
    • compute.projects.get
    • compute.subnetworks.list
    • compute.subnetworks.use
    • compute.subnetworks.useExternalIp
    • compute.zoneOperations.get
    • compute.zones.list
  • Compute Network User role (roles/compute.networkUser)

    This role is required only when you import or export images that use Shared VPC.

    In the Shared VPC project, grant the Compute Network User role to the Cloud Build service account that is located in the project where you import or export images.

However, you can manually grant these roles to ensure that the requiredpermissions are in effect:

Console

  1. After you enable the Cloud Build API, go to theIAM & Adminpage for the project or organization.

    Go to IAM & Admin

  2. Locate the Cloud Build service account and clickEdit.

  3. If the required roles are not listed, do the following:

    1. ClickAdd another role.
    2. In theSelect a role list, select the required roles that you wantto add:

      • Service Account>Service Account Token Creator
      • Service Account>Service Account User
      • Compute Engine>Compute Admin

        Alternatively, you can select theCustom role. SeePermissions required for the custom role earlierin this document.

    3. ClickSave to save the changes.

  4. Optional: If you're importing or exporting images that use Shared VPC, select the Compute Network User role in the Shared VPC project:

    1. From the project selector at the top of the console, select theShared VPC host project.
    2. On theIAM & Admin page, clickGrant access.
    3. In theNew principals field, enter the email address of the Cloud Build service account:
      PROJECT_NUMBER@cloudbuild.gserviceaccount.com'
      ReplacePROJECT_NUMBER with the unique number of the project where you import or export images.
    4. In theSelect a role list, selectCompute Engine>Compute Network User role.
    5. ClickSave to save the changes.

gcloud

In the following steps, you use thegcloud projects add-iam-policy-bindingcommand to grant therequired roles at the project level.

  1. Grant theroles/compute.admin role to the Cloud Build serviceaccount.To avoid granting theroles/compute.admin role, you can create a customrole with the required permissions and then grant that role to theCloud Build service account. SeePermissions required for the custom role earlier in this document.

    gcloud projects add-iam-policy-bindingPROJECT_ID \   --member='serviceAccount:PROJECT_NUMBER@cloudbuild.gserviceaccount.com' \   --role='roles/compute.admin'

    Replace the following:

  2. Grant theroles/iam.serviceAccountUser role:

    gcloud projects add-iam-policy-bindingPROJECT_ID \   --member='serviceAccount:PROJECT_NUMBER@cloudbuild.gserviceaccount.com' \   --role='roles/iam.serviceAccountUser'
  3. Grant theroles/iam.serviceAccountTokenCreator role:

    gcloud projects add-iam-policy-bindingPROJECT_ID \   --member='serviceAccount:PROJECT_NUMBER@cloudbuild.gserviceaccount.com' \   --role='roles/iam.serviceAccountTokenCreator'
  4. Optional: If you're exporting or importingimages that use Shared VPC, grant theroles/compute.networkUser role:

    gcloud projects add-iam-policy-bindingHOST_PROJECT_ID \   --member='serviceAccount:PROJECT_NUMBER@cloudbuild.gserviceaccount.com' \   --role='roles/compute.networkUser'

    Replace the following:

    • HOST_PROJECT_ID: the ID of the host projectwhere the Shared VPC is located
    • PROJECT_NUMBER: the unique number of the projectwhere you import or export images

REST

  1. Read the existing policy with the resource'sgetIamPolicy method. Forprojects, use theprojects.getIamPolicy method.

    POST https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID:getIamPolicy

    ReplacePROJECT_ID with the projectID—for example,my-project-1.

  2. To grant the required roles to your account, edit the policy witha text editor.

    For example, to grant the required roles toserviceAccount:12345@cloudbuild.gserviceaccount.com, add the followingbinding to the policy:

    {   {     "role":"roles/compute.admin",     "member":[       "serviceAccount:12345@cloudbuild.gserviceaccount.com"     ]   }   {     "roles":"roles/iam.serviceAccountUser",     "member":[       "serviceAccount:12345@cloudbuild.gserviceaccount.com"     ]   }  {     "roles":"roles/iam.serviceAccountTokenCreator",     "member":[       "serviceAccount:12345@cloudbuild.gserviceaccount.com"     ]   }}

    To avoid granting theroles/compute.admin role, you can create acustom role with the required permissions and then grant that role tothe Cloud Build service account. SeePermissions required for the custom role earlier in this document.

  3. Optional: If you're exporting or importing images that useShared VPC, grant theroles/compute.networkUser role in theShared VPC project.

    POST https://cloudresourcemanager.googleapis.com/v1/projects/HOST_PROJECT_ID:getIamPolicy

    ReplaceHOST_PROJECT_ID with the ID of theShared VPC project.

    Add the following IAM binding to theCloud Build service account:

    {   {     "roles":"roles/compute.networkUser",     "member":[       "serviceAccount:12345@cloudbuild.gserviceaccount.com"     ]   }}
  4. To write the updated policy, use thesetIamPolicy method.

    For example, to seta policy at the project level, use theproject.setIamPolicymethod. Inthe body of the request, provide the updated IAM policyfrom the previous step.

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

For more information on managing access to resources, seeGranting, changing,and revoking access to resources.

Note: By default, when the Cloud Build API is enabled, the Cloud Build Service Account role (roles/cloudbuild.builds.builder)is granted to theCloud Build service account.If this role is removed, importing and exporting images might fail.

Grant required roles to the Compute Engine service account

When you use the Google Cloud console or the gcloud CLI to importor export images for the first time, the tool attempts to grant the requiredroles to thedefault Compute Engine service account.

Depending on your organization policy configuration, the default service account might automatically be granted theEditor role on your project. We strongly recommend that you disable the automatic role grant by enforcing theiam.automaticIamGrantsForDefaultServiceAccounts organization policy constraint. If you created your organization after May 3, 2024, this constraint is enforced by default.

If you disable the automatic role grant, you must decide which roles to grant to the default service accounts, and thengrant these roles yourself.

If the default service account already has the Editor role, we recommend that you replace the Editor role with less permissive roles.To safely modify the service account's roles, usePolicy Simulator to see the impact of the change, and thengrant and revoke the appropriate roles.

Your Compute Engine service account must have the following roles:

  • Compute Storage Admin role (roles/compute.storageAdmin): required for both exporting and importing VM images
  • Storage Object Viewer role (roles/storage.objectViewer): required for importing VM images
  • Storage Object Admin role (roles/storage.objectAdmin): required for exporting VM images

Console

  1. Go to theIAM & Admin page for theproject or organization.

    Go to IAM & Admin

  2. Locate the Compute Engine service account and clickEdit.

  3. In theSelect a role list, select the following roles:

    • Compute Engine>Compute Storage Admin
    • Cloud Storage>Storage Object Viewer
    • Cloud Storage>Storage Object Admin
  4. Save your changes.

gcloud

In the following steps, you use thegcloud projects add-iam-policy-bindingcommand to grant therequired roles at the project level.

  1. Grant theroles/compute.storageAdmin role:

    gcloud projects add-iam-policy-bindingPROJECT_ID \  --member='serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com' \  --role='roles/compute.storageAdmin'
  2. If you're importing an image, grant theroles/storage.objectViewer role:

    gcloud projects add-iam-policy-bindingPROJECT_ID \  --member='serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com' \  --role='roles/storage.objectViewer'
  3. If you're exporting an image, grant theroles/storage.objectAdmin role:

    gcloud projects add-iam-policy-bindingPROJECT_ID \  --member='serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com' \  --role='roles/storage.objectAdmin'

REST

  1. Read the existing policy with the resource'sgetIamPolicy method. Forprojects, use theprojects.getIamPolicy method.

    POST https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID:getIamPolicy

    ReplacePROJECT_ID with the projectID—for example,my-project-1.

  2. To grant the required roles to your account, edit the policy witha text editor.

    For example, to grant the required roles toserviceAccount:12345-compute@developer.gserviceaccount.com forimporting an image, add the following binding to the policy:

    {   {     "role":"roles/compute.storageAdmin",     "member":[       "serviceAccount:12345-compute@developer.gserviceaccount.com"     ]   }   {     "roles":"roles/storage.objectViewer",     "member":[       "serviceAccount:12345-compute@developer.gserviceaccount.com"     ]   }}
  3. To write the updated policy, use thesetIamPolicy method.

    For example, to seta policy at the project level, use theproject.setIamPolicymethod. Inthe body of the request, provide the updated IAM policyfrom the previous step.

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

If you don't want to use the default Compute Engine service account,you can specify auser-managed service accountusing the--compute-service-account flag in thegcloud import and exportcommands. For more information on using custom Compute Engine serviceaccount, see the following resources:

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 2026-02-18 UTC.