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:
- Install or update to the latest version of the gcloud command-line tool.
- 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.
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.
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 projectPROJECT_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.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.
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 thegcloud 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 thegcloud compute instances import
command.ZONE
: the zone in which to import the machine image.
What's next?
- Learn more about machine images
- Create VM instances from machine images