Import machine images from virtual appliances

The machine image import feature on Compute Engine is being deprecated andwill reach end-of-support (EoS) on July 1st, 2025. We recommend that you usethe newmachine image import feature on Migrate to Virtual Machinesto import your machine images to Google Cloud.

Use a machine image to store all theconfiguration, metadata, permissions, and data from one or more disks for a VMinstance running on Compute Engine. For information about when and how touse machine images, seeMachine images.

This document describes the steps for importing a machine image from avirtual appliance.

Before you begin

Limitations and restrictions

  • You can share a machine image across projects. However,shared VPC networks aren't supported.
  • This feature is not supported for projects that are protectedwithVPC Service Controls.
  • Machine images can't be created from source VMs that have greater than 200 TBof disks attached.

Supported operating systems

For operating system support, seeOperating system details.

Import machine images

You can import machine images from virtual appliances using either theGoogle Cloud CLI orCloud Build API.

gcloud

Use thegcloud compute machine-images import commandto import a machine image from virtual appliances.

gcloud compute machine-images importMACHINE_IMAGE_NAME \    --source-uri=gs:SOURCE_URI \    --os=OS

Replace the following:

  • MACHINE_IMAGE_NAME: name of the machineimage that you want to import.
  • SOURCE_URI: path toyour OVA or OVF file on Cloud Storage.
  • OS: operating system of the OVA file. Thisflag is optional by default, but it might be required in some cases. Werecommend that you provide this flag.

Example

For example, you can use the followinggcloud command to import a machineimage calledmy-machine-image from a source OVA file calledmy-ova thatis stored in thegs://my-bucket directory and runscentos-7:

gcloud compute machine-images import my-machine-image  \    --source-uri=gs://my-bucket/my-ova/ \    --os=centos-7

REST

  1. Upload the virtual appliance toCloud Storage.

  2. Send aPOST request to theprojects.builds.create method.

    Note: Twotimeout values are required. Default values forthese are provided in the following sample requests.These default values work in most scenarios. However, if you need to adjust thesevalues, ensure that the Cloud Build timeout is at least 3% greater thanthe timeout specified for the arguments (args) section.
    POST https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/builds{ "timeout": "7200s", "steps":[   {     "args":[       "-machine-image-name=MACHINE_IMAGE_NAME",       "-ovf-gcs-path=SOURCE_URI",       "-os=OS",       "-client-id=api",       "-timeout=7000s"     ],     "name":"gcr.io/compute-image-tools/gce_ovf_import:release",     "env":[       "BUILD_ID=$BUILD_ID"     ]   } ], "tags":"gce-ovf-machine-image-import"}

    Replace the following:

    • PROJECT_ID: project ID for the project thatyou want to import the OVA file into.
    • MACHINE_IMAGE_NAME: name for the machineimage to import. For example,my-machine-image.
    • SOURCE_URI: URI for the OVA file or adirectory containing OVF packages that is stored in Cloud Storage.For example,gs://my-bucket/my-instance.ova.
    • OS: operating system of the OVA file. Forexample,ubuntu-1604. This flag is optional by default, but it mightbe required in some cases. We recommend that you provide this flag.

    For additionalargs values that can be provided, see the optionalflags section of theCompute Engine OVF import GitHub page.

Import machine images with OVF overrides

When you import a machine image from a virtual appliance, you can override thesettings in the OVF file. For example, you can change the CPU or memoryconfiguration, or you can use a custom network.

Custom CPU and memory

To override the CPU or memory configuration specified in the OVF file,complete the following steps:

gcloud

To override the CPU or memory configuration specified in the OVF file,follow the Google Cloud CLI steps toimport a machine imageand specify the--custom-cpu and--custom-memory flags.

Example

A machine image namedmy-machine-image has thefollowing overrides applied to the settings in the OVF file:

  • Operating system:Ubuntu 1404
  • CPU:2 CPUs
  • Memory:2048 MB

To importmy-machine-image with these overrides, run the following command:

gcloud compute machine-images import my-machine-image \    --os=ubuntu-1404 --source-uri=gs://my-bucket/Ubuntu.ova \    --custom-cpu=2 --custom-memory=2048MB

REST

To override the CPU or memory configuration specified in the OVF file,follow the Compute Engine API steps toimport a machine imageand specify the-machine-type argument.This-machine-type represents apredefined orN1 seriescustom machinetype to use.

Example

A machine image namedmy-machine-image in themy-project project has thefollowing overrides applied to the settings in the OVF file:

  • Operating system:Ubuntu 1404
  • CPU:2 CPUs
  • Memory:2048 MB

To importmy-machine-image with theseoverrides, make the following request to the Cloud Build API.

Note: Twotimeout values are required. Default values forthese are provided in the following sample requests.These default values work in most scenarios. However, if you need to adjust thesevalues, ensure that the Cloud Build timeout is at least 3% greater thanthe timeout specified for the arguments (args) section.
POST https://cloudbuild.googleapis.com/v1/projects/my-project/builds{  "timeout":"7200s",  "steps":[    {      "args":[        "-machine-image-name=my-machine-image",        "-ovf-gcs-path=gs://my-bucket/Ubuntu.ova",        "-os=ubuntu-1404",        "-machine-type=custom-2-2048",        "-client-id=api",        "-timeout=7000s"      ],      "name":"gcr.io/compute-image-tools/gce_ovf_import:release",      "env":[        "BUILD_ID=$BUILD_ID"      ]    }  ],  "tags":"gce-ovf-machine-image-import"}

Custom networks

To override the network configuration specified in the OVF file,complete the following steps:

gcloud

To set up a custom network, follow the Google Cloud CLI steps toimport a machine imageand specify a--network flag.If the network is configured with a custom subnet mode,you must also specify--subnet and--zone flags.

Example

A machine image namedmy-machine-image has thefollowing overrides applied to the settings in the OVF file:

  • Operating system:Ubuntu 1404
  • Network:custom-vpc-network
  • Subnet:company-vpc-us-east1-c
  • Zone:us-east1-c

To importmy-machine-image with these overrides, run the following examplecommand:

gcloud compute machine-images import my-machine-image \    --os=ubuntu-1404 \    --source-uri=gs://my-bucket/Ubuntu.ova \    --network=custom-vpc-network \    --subnet=company-vpc-us-east1-c \    --zone=us-east1-c

REST

To use a custom network, follow the REST steps toimport a machine imageand specify a-network argument.If the network is configured with a custom subnet mode,you must also specify-subnet and-zone arguments.

Example

A machine image namedmy-machine-image has thefollowing overrides applied to the settings in the OVF file:

  • Operating system:Ubuntu 1404
  • Network:custom-vpc-network
  • Subnet:company-vpc-us-east1-c
  • Zone:us-central1-c

To importmy-machine-image with these overrides, make the followingrequest to the Compute Engine API.

Note: Twotimeout values are required. Default values forthese are provided in the following sample requests.These default values work in most scenarios. However, if you need to adjust thesevalues, ensure that the Cloud Build timeout is at least 3% greater thanthe timeout specified for the arguments (args) section.
POST https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/builds{  "timeout":"7200s",  "steps":[    {      "args":[        "-machine-image-name=my-machine-image",        "-ovf-gcs-path=gs://my-bucket/Ubuntu.ova",        "-os=ubuntu-1404",        "-zone=us-central1-c",        "-network=custom-vpc-network",        "-subnet=company-vpc-us-east1-c",        "-client-id=api",        "-timeout=7000s"      ],      "name":"gcr.io/compute-image-tools/gce_ovf_import:release",      "env":[        "BUILD_ID=$BUsILD_ID"      ]    }  ],  "tags":"gce-ovf-machine-image-import"}

ReplacePROJECT_ID with your project ID.

Import a machine image within a network that does not allow external IP

To import a machine image using a network that does not allow external IPaddresses, complete the following steps:

  1. Add the virtual appliance toCloud Storage.

  2. The import process requires package managers to be installed on theoperating system for the machine image. These package managers mightneed to make requests to package repositories that are outside Google Cloud.To allow access for these updates, you need to configure Cloud NAT.For more information, seeCreate a NAT configuration using Cloud Router.

  3. ConfigurePrivate Google Access.For more information, seeConfiguring Private Google Access.

  4. Import the machine image using either the Google Cloud CLI or theCloud Build API.

    When you import a machine image from a virtual appliance, temporary VMs arecreated in your project. To ensure that these temporary VMs are not assignedexternal IP addresses, you must specify an additional flag or argument.

    For more information about the required flag or argument, click thefollowing tabs:

gcloud

Use thegcloud compute machine-images import commandwith the--no-address flag .

gcloud compute machine-images importMACHINE_IMAGE_NAME \    --source-uri=SOURCE_URI \    --os=OS \    --zone=ZONE \    --no-address

Replace the following:

  • MACHINE_IMAGE_NAME: name of the machineimage that you want to import.
  • SOURCE_URI: URI foryour OVA or OVF file on Cloud Storage. For example,gs://my-bucket/Ubuntu.ova.
  • OS: operating system of the OVA file. Thisflag is optional by default, but it might be required in some cases. Werecommend that you provide this flag.For a list of supported values, see--os flag optionsfor thegcloud compute machine-images import command.
  • ZONE: thezone in which to import themachine image. If left blank, the default zone for the project is used.

REST

Send aPOST request to theprojects.builds.create methodusing theCloud Build API. Specifythe-no-external-ip argument.

Note: Twotimeout values are required. Default values forthese are provided in the following sample requests.These default values work in most scenarios. However, if you need to adjust thesevalues, ensure that the Cloud Build timeout is at least 3% greater thanthe timeout specified for the arguments (args) section.

 POST https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/builds {  "timeout":"7200s",  "steps":[    {      "args":[        "-machine-image-name=MACHINE_IMAGE_NAME",        "-ovf-gcs-path=SOURCE_URI",        "-os=OS",        "-zone=ZONE",        "-no-external-ip",        "-client-id=api",        "-timeout=7000s"      ],      "name":"gcr.io/compute-image-tools/gce_ovf_import:release",      "env":[        "BUILD_ID=$BUILD_ID"      ]    }  ],  "tags":"gce-ovf-machine-image-import"}

Replace the following:

Import a machine image using custom service accounts

During a machine image import, temporary virtual machine (VM) instances arecreated in your project. The import tool on these temporary VMs must beauthenticated.

Aservice account is an identity thatis attached to a VM. Service account access tokens can be accessed through theVM metadata serverand used to authenticate the import tool on the VM.

By default, the import process uses thedefault Compute Engine service account.However, if the default Compute Engine service account is disabled inyour project or if you want to use a custom Compute Engine service account,then you need to create a service account and specify it for the import process.

gcloud

  1. Add the virtual appliance toCloud Storage.

  2. Create a service account and assign the minimum roles. For more informationabout creating service accounts, seeCreating and managing service accounts.

    At minimum, the specified Compute Engine service account needs to have thefollowing roles assigned:

    • roles/compute.storageAdmin
    • roles/storage.objectViewer

    These minimum roles are needed for the service account specified for the--compute-service-account flag. For more information, seeGrantrequired roles to the Compute Engine service account.

  3. Use thegcloud compute machine-images import command to import a machine image from virtual appliances.

    gcloud compute machine-images importMACHINE_IMAGE_NAME \    --source-uri=gs:SOURCE_URI \    --os=OS \    --compute-service-account=TEMP_SERVICE_ACCOUNT_EMAIL \    --service-account=SERVICE_ACCOUNT_EMAIL \    --scopes=SCOPES

    Replace the following:

    • MACHINE_IMAGE_NAME: name of the machineimage that you want to import.
    • SOURCE_URI: path toyour OVA or OVF file on Cloud Storage.
    • OS: operating system of the OVA file. Thisflag is optional by default, but it might be required in some cases. Werecommend that you provide this flag.
    • TEMP_SERVICE_ACCOUNT_EMAIL: the emailaddress associated with the custom serviceaccount created in the previous step. This service accountis used by the temporary VMs.If unspecified, the VM uses the default Compute Engineservice account.
    • SERVICE_ACCOUNT_EMAIL: the emailaddress associated with the custom service account that is to be attachedto any VM created from this machine image. There are no permission restrictionsfor this service account, you can customize this service account as needed.If unspecified, the default Compute Engine service accountis attached to the VM.
    • SCOPES: specify the level of access for the--service-account option. If unspecified, the default scopes are used.For more information, review the--scopes flag.

REST

  1. Add the virtual appliance toCloud Storage.

  2. Create a service account and assign the minimum roles. For more informationabout creating service accounts, seeCreate service accounts.

    At minimum, the specified Compute Engine service account needs to have thefollowing roles assigned:

    • roles/compute.storageAdmin
    • roles/storage.objectViewer

    These minimum roles are needed for the service account specified for the-compute-service-account argument. For more information, seeGrantrequired roles to the Compute Engine service account.

  3. Send aPOST request to theprojects.builds.create methodusing the Cloud Build API.

    Note: Twotimeout values are required. Default values forthese are provided in the following sample requests.These default values work in most scenarios. However, if you need to adjust thesevalues, ensure that the Cloud Build timeout is at least 3% greater thanthe timeout specified for the arguments (args) section.
    POST https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/builds{"timeout":"7200s","steps":[  {    "args":[      "-machine-image-name=MACHINE_IMAGE_NAME",      "-ovf-gcs-path=SOURCE_URI",      "-os=OS",      "-zone=ZONE",      "-compute-service-account=TEMP_SERVICE_ACCOUNT_EMAIL",      "-service-account=SERVICE_ACCOUNT_EMAIL",      "-client-id=api",      "-timeout=7000s"    ],    "name":"gcr.io/compute-image-tools/gce_ovf_import:release",    "env":[      "BUILD_ID=$BUILD_ID"    ]  }],"tags":"gce-ovf-machine-image-import"}

    Replace the following:

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 2025-12-15 UTC.