Prerequisites for importing and exporting VM images Stay organized with collections Save and categorize content based on your preferences.
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:
- Set up access to a Cloud Storage bucket
- Grant required roles to your user account
- Grant required roles to the Cloud Build service account
- Grant required roles to the Compute Engine service account
Before you begin
- If you haven't already, set upauthentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:
gcloudinit
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.- Set a default region and zone.
REST
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:
gcloudinit
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.For more information, seeAuthenticate for using REST in the Google Cloud authentication documentation.
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
Go to theIAM & Admin page for theproject or organization.
Locate your account and clickEdit.
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
Save your changes.
gcloud
In the following steps, you use thegcloud projects add-iam-policy-bindingcommand to grant therequired roles at the project level.
Grant the
roles/storage.adminrole:gcloud projects add-iam-policy-bindingPROJECT_ID \ --member='MEMBER' \ --role='roles/storage.admin'
Replace the following:
PROJECT_ID: theGoogle Cloud project IDfor your projectMEMBER: the account that runs theimport and export commands—for example,user:export-user@gmail.com
Grant the
roles/viewerrole:gcloud projects add-iam-policy-bindingPROJECT_ID \ --member='MEMBER' \ --role='roles/viewer'
Grant the
roles/resourcemanager.projectIamAdminrole:gcloud projects add-iam-policy-bindingPROJECT_ID \ --member='MEMBER' \ --role='roles/resourcemanager.projectIamAdmin'
Grant the
roles/cloudbuild.builds.editorrole:gcloud projects add-iam-policy-bindingPROJECT_ID \ --member='MEMBER' \ --role='roles/cloudbuild.builds.editor'
REST
Read the existing policy with the resource's
getIamPolicymethod. Forprojects, use theprojects.getIamPolicymethod.POST https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID:getIamPolicy
Replace
PROJECT_IDwith the projectID—for example,my-project-1.To grant the required roles to your account, edit the policy witha text editor.
For example, to grant the required role to your account
user: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" ] }}To write the updated policy, use the
setIamPolicymethod.For example, to seta policy at the project level, use the
project.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.createcompute.disks.deletecompute.disks.getcompute.disks.getIamPolicycompute.disks.listcompute.disks.resizecompute.disks.setLabelscompute.disks.usecompute.disks.useReadOnlycompute.images.createcompute.images.getcompute.images.getFromFamilycompute.images.getIamPolicycompute.images.listcompute.images.useReadOnlycompute.instances.attachDiskcompute.instances.createcompute.instances.deletecompute.instances.detachDiskcompute.instances.getcompute.instances.getSerialPortOutputcompute.instances.listcompute.instances.setLabelscompute.instances.setMetadatacompute.instances.setServiceAccountcompute.machineTypes.listcompute.networks.listcompute.projects.getcompute.subnetworks.listcompute.subnetworks.usecompute.subnetworks.useExternalIpcompute.zoneOperations.getcompute.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
After you enable the Cloud Build API, go to theIAM & Adminpage for the project or organization.
Locate the Cloud Build service account and clickEdit.
If the required roles are not listed, do the following:
- ClickAdd another role.
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.
ClickSave to save the changes.
Optional: If you're importing or exporting images that use Shared VPC, select the Compute Network User role in the Shared VPC project:
- From the project selector at the top of the console, select theShared VPC host project.
- On theIAM & Admin page, clickGrant access.
- In theNew principals field, enter the email address of the Cloud Build service account:
ReplacePROJECT_NUMBER@cloudbuild.gserviceaccount.com'
PROJECT_NUMBERwith the unique number of the project where you import or export images. - In theSelect a role list, selectCompute Engine>Compute Network User role.
- 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.
Grant the
roles/compute.adminrole to the Cloud Build serviceaccount.To avoid granting theroles/compute.adminrole, 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:
PROJECT_ID: theGoogle Cloud project ID for your projectPROJECT_NUMBER: theGoogle Cloud project number for your project
Grant the
roles/iam.serviceAccountUserrole:gcloud projects add-iam-policy-bindingPROJECT_ID \ --member='serviceAccount:PROJECT_NUMBER@cloudbuild.gserviceaccount.com' \ --role='roles/iam.serviceAccountUser'
Grant the
roles/iam.serviceAccountTokenCreatorrole:gcloud projects add-iam-policy-bindingPROJECT_ID \ --member='serviceAccount:PROJECT_NUMBER@cloudbuild.gserviceaccount.com' \ --role='roles/iam.serviceAccountTokenCreator'
Optional: If you're exporting or importingimages that use Shared VPC, grant the
roles/compute.networkUserrole: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 locatedPROJECT_NUMBER: the unique number of the projectwhere you import or export images
REST
Read the existing policy with the resource's
getIamPolicymethod. Forprojects, use theprojects.getIamPolicymethod.POST https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID:getIamPolicy
Replace
PROJECT_IDwith the projectID—for example,my-project-1.To grant the required roles to your account, edit the policy witha text editor.
For example, to grant the required roles to
serviceAccount: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 the
roles/compute.adminrole, 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.Optional: If you're exporting or importing images that useShared VPC, grant the
roles/compute.networkUserrole in theShared VPC project.POST https://cloudresourcemanager.googleapis.com/v1/projects/HOST_PROJECT_ID:getIamPolicy
Replace
HOST_PROJECT_IDwith 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" ] }}To write the updated policy, use the
setIamPolicymethod.For example, to seta policy at the project level, use the
project.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
Go to theIAM & Admin page for theproject or organization.
Locate the Compute Engine service account and clickEdit.
In theSelect a role list, select the following roles:
- Compute Engine>Compute Storage Admin
- Cloud Storage>Storage Object Viewer
- Cloud Storage>Storage Object Admin
Save your changes.
gcloud
In the following steps, you use thegcloud projects add-iam-policy-bindingcommand to grant therequired roles at the project level.
Grant the
roles/compute.storageAdminrole:gcloud projects add-iam-policy-bindingPROJECT_ID \ --member='serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com' \ --role='roles/compute.storageAdmin'
If you're importing an image, grant the
roles/storage.objectViewerrole:gcloud projects add-iam-policy-bindingPROJECT_ID \ --member='serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com' \ --role='roles/storage.objectViewer'
If you're exporting an image, grant the
roles/storage.objectAdminrole:gcloud projects add-iam-policy-bindingPROJECT_ID \ --member='serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com' \ --role='roles/storage.objectAdmin'
REST
Read the existing policy with the resource's
getIamPolicymethod. Forprojects, use theprojects.getIamPolicymethod.POST https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID:getIamPolicy
Replace
PROJECT_IDwith the projectID—for example,my-project-1.To grant the required roles to your account, edit the policy witha text editor.
For example, to grant the required roles to
serviceAccount:12345-compute@developer.gserviceaccount.comforimporting 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" ] }}To write the updated policy, use the
setIamPolicymethod.For example, to seta policy at the project level, use the
project.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:
- Importing virtual disks with custom service accounts
- Importing virtual appliances with custom service accounts
- Importing machine images from virtual appliances with custom service accounts
- Exporting custom images with custom service accounts
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.