Importing machine images from virtual appliances

Use a machine image to store all the configuration, metadata, permissions, and data from one or more disks for a VM instance running on Compute Engine. For information about when and how to use machine images, see Machine images.

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

Before you begin

If you want to use the command-line examples in this guide, do the following:
1. Install or update to the latest version of the gcloud command-line tool.
2. Set a default region and zone.
If you want to use the API examples in this guide, set up API access.
Review source VM and OVF file requirements in the importing virtual appliances Compute Engine guide.
If the project that you want to import the machine image in has a trusted image policy defined, add projects/compute-image-tools to the allowed list of publishers.
If you are importing a virtual appliance from a different project, see Importing across projects.
Enable the Cloud Build API.

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 protected with VPC Service Controls.
Machine images can't be created from source VMs that have greater than 200 TB of disks attached.

Supported operating systems

For operating system support, see Operating system details.

Enable the Cloud Build API

In most cases, gcloud beta compute machine-images import attempts to grant these permissions to the Cloud Build service account. However, you can manually grant these permissions to ensure that the required permissions are in effect.

Console

Enable the Cloud Build API.

Enable the Cloud Build API

When you enable the Cloud Build API from the console, Compute Engine grants the Cloud Build service account the following roles so that the Cloud Build service can import instances into Compute Engine:
- roles/iam.serviceAccountTokenCreator
- roles/compute.admin
- roles/iam.serviceAccountUser
The import tool also uses the default Compute Engine service account. By default, the Compute Engine service account has the IAM project editor role. If this role is removed, the import process might fail. To add the role back to the service account, see Granting access. For more information about the Compute Engine default service account, see Compute Engine default service account.

gcloud

To set up the Cloud Build service using gcloud command-line tool, complete the following steps:

Enable Cloud Build.
```
gcloud services enable cloudbuild.googleapis.com
```
The import tool also uses the default Compute Engine service account. By default, the Compute Engine service account has the IAM project editor role. If this role is removed, the import process might fail. To add the role back to the service account, see Granting access. For more information about the Compute Engine default service account, see Compute Engine default service account.

Add the compute.admin role to the service account for the Cloud Build API.

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member serviceAccount:PROJECT_NUM@cloudbuild.gserviceaccount.com \
   --role roles/compute.admin

Add the iam.serviceAccountUser role to the service account for the Cloud Build API.

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member serviceAccount:PROJECT_NUM@cloudbuild.gserviceaccount.com \
   --role roles/iam.serviceAccountUser

Add the iam.serviceAccountTokenCreator role to the service account for the Cloud Build API.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
   --member serviceAccount:PROJECT_NUM@cloudbuild.gserviceaccount.com \
   --role roles/iam.serviceAccountTokenCreator
```
Replace the following:
- PROJECT_ID: the projectID for your project
- PROJECT_NUM: the project number for your project.

Importing machine images

You can import machine images from virtual appliances using either the gcloud command-line tool, or the Cloud Build API.

gcloud

Use the gcloud beta compute machine-images import command to import a machine image from virtual appliances.

gcloud beta compute machine-images import MACHINE_IMAGE_NAME \
    --source-uri=gs:SOURCE_URI \
    --os=OS

Replace the following:

MACHINE_IMAGE_NAME: name of the machine image that you want to import.
SOURCE_URI: path to your OVA or OVF file on Cloud Storage.
OS: operating system of the OVA file. This flag is optional by default, but it might be required in some cases. We recommend that you provide this flag.

Example

For example, you can use the following gcloud command to import a machine image called my-machine-image from a source OVA file called my-ova that is stored in the gs://my-bucket directory and runs centos-7:

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

API

Upload the virtual appliance to Cloud Storage.
In the API, create a POST request to the Cloud Build API.

Note: Two timeout values are required. Default values for these are provided in the following sample requests. These default values work in most scenarios. However, if you need to adjust these values, ensure that the Cloud Build timeout is at least 3% greater than the 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 that you want to import the OVA file into.
- MACHINE_IMAGE_NAME: name for the machine image to import. For example, my-machine-image.
- SOURCE_URI: URI for the OVA file or a directory containing OVF packages that is stored in Cloud Storage. For example, gs://my-bucket/my-instance.ova.
- OS: operating system of the OVA file. For example, ubuntu-1604. This flag is optional by default, but it might be required in some cases. We recommend that you provide this flag.
For additional args values that can be provided, see the optional flags section of the Compute Engine OVF import GitHub page.

Importing machine images with OVF overrides

Custom CPU and memory

gcloud

To override the CPU or memory configuration specified in the OVF file, follow the gcloud command-line tool steps to import a machine image and specify the --custom-cpu and --custom-memory flags.

Example

A machine image named my-machine-image has the following overrides applied to the settings in the OVF file:

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

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

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

API

To override the CPU or memory configuration specified in the OVF file, follow the Compute Engine API steps to import a machine image and specify the -machine-type argument. This -machine-type represents a predefined or custom machine type to use.

Example

A machine image named my-machine-image has the following overrides applied to the settings in the OVF file:

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

To import my-machine-image with these overrides, make the following request to the Compute Engine API.

Note: Two timeout values are required. Default values for these are provided in the following sample requests. These default values work in most scenarios. However, if you need to adjust these values, ensure that the Cloud Build timeout is at least 3% greater than the 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",
        "-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"
}

Replace PROJECT_ID with your project ID.

Custom networks

gcloud

To set up a custom network, follow the gcloud command-line tool steps to import a machine image and 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 named my-machine-image has the following 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 import my-machine-image with these overrides, run the following example command:

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

API

To use a custom network, follow the Compute Engine API steps to import a machine image and 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 named my-machine-image has the following 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 import my-machine-image with these overrides, make the following request to the Compute Engine API.

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

Replace PROJECT_ID with your project ID.

Importing 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 IP addresses, complete the following steps:

Add the virtual appliance to Cloud Storage.
The import process requires package managers to be installed on the operating system for the machine image. These package managers might need 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, see Create a NAT configuration using Cloud Router.
Configure Private Google Access. For more information, see Configuring Private Google Access.
Import the machine image using either the gcloud command-line tool or the Cloud Build API.

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

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

gcloud

Use the gcloud beta compute machine-images import command with the --no-address flag .

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

Replace the following:

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

API

Use the Cloud Build API and specify the -no-external-ip argument.

 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:

PROJECT_ID: the project ID for the project that you want to import the machine image into.
MACHINE_IMAGE_NAME: the name for the machine image to import. For example, my-machine-image.
SOURCE_URI: the URI for the OVA file that is stored in Cloud Storage. For example, gs://my-bucket/my-machine.ova.
OS: the operating system of the OVA file. For example, ubuntu-1604. This flag is optional by default, but it might be required in some cases. We recommend that you provide this flag. For a list of supported values, see --os flag options for the gcloud compute instances import command.
ZONE: the zone in which to import the machine image.

Importing a machine image using custom service accounts

During a machine image import, temporary virtual machine (VM) instances are created in your project. The import tool on these temporary VMs must be authenticated.

A service account is an identity that is attached to a VM. Service account access tokens can be accessed through the instance metadata server and used to authenticate the import tool on the VM.

By default, the import process uses the default Compute Engine service account. However, if the default Compute Engine service account is disabled in your 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

Add the virtual appliance to Cloud Storage.
Create a service account and assign the minimum roles. For more information about creating service accounts, see Creating and managing service accounts.

At minimum, the specified Compute Engine service account needs to have the following roles assigned:
- roles/compute.storageAdmin
- roles/storage.objectViewer
These minimum roles are needed for the service account specified for the --compute-service-account flag.
Use the gcloud beta compute machine-images import command to import a machine image from virtual appliances.
```
gcloud beta compute machine-images import MACHINE_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 machine image that you want to import.
- SOURCE_URI: path to your OVA or OVF file on Cloud Storage.
- OS: operating system of the OVA file. This flag is optional by default, but it might be required in some cases. We recommend that you provide this flag.
- TEMP_SERVICE_ACCOUNT_EMAIL: the email address associated with the custom service account created in the previous step. This service account is used by the temporary VMs. If unspecified, the VM uses the default Compute Engine service account.
- SERVICE_ACCOUNT_EMAIL: the email address associated with the custom service account that is to be attached to any VM created from this machine image. There are no permission restrictions for this service account, you can customize this service account as needed. If unspecified, the default Compute Engine service account is 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.

API

Add the virtual appliance to Cloud Storage.
Create a service account and assign the minimum roles. For more information about creating service accounts, see Creating and managing service accounts.

At minimum, the specified Compute Engine service account needs to have the following roles assigned:
- roles/compute.storageAdmin
- roles/storage.objectViewer
These minimum roles are needed for the service account specified for the -compute-service-account flag.
In the API, create a POST request to the Cloud Build API.

Note: Two timeout values are required. Default values for these are provided in the following sample requests. These default values work in most scenarios. However, if you need to adjust these values, ensure that the Cloud Build timeout is at least 3% greater than the 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:
- PROJECT_ID: the project ID for the project that you want to import the machine image into.
- MACHINE_IMAGE_NAME: the name for the machine image to import. For example, my-machine-image.
- SOURCE_URI: the URI for the OVA file that is stored in Cloud Storage. For example, gs://my-bucket/my-machine.ova.
- OS: the operating system of the OVA file. For example, ubuntu-1604. This flag is optional by default, but it might be required in some cases. We recommend that you provide this flag. For a list of supported values, see --os flag options for the gcloud compute instances import command.
- ZONE: the zone in which to import the machine image.
- TEMP_SERVICE_ACCOUNT_EMAIL: the email address associated with the custom service account created in the previous step. This service account is used by the temporary VMs. If unspecified, the VM uses the default Compute Engine service account.
- SERVICE_ACCOUNT_EMAIL: the email address associated with the custom service account that is to be attached to any VM created from this machine image. There are no permission restrictions for this service account, you can customize this service account as needed. If unspecified, the default Compute Engine service account is 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.

What's next?

Learn more about machine images
Create VM instances from machine images