Importing virtual appliances

A virtual appliance is a package that contains disk images and hardware configuration for a virtual machine (VM) instance.

A widely used and popular format for virtual appliances is the OVF format. When you package virtual appliances in the OVF format, you generate an OVF package. An OVF package is a folder that contains an .ovf descriptor file and a collection of other resources, such as disks. When an OVF package is archived into a single file, it is referred to as an OVA file.

You can import VMs that are in OVF format to Compute Engine, whether they are in an OVF package or in an OVA single file. To check whether using a virtual appliance is the best choice for your use case, review Choosing an import method.

When you import a virtual appliance, the import process uses the information stored in the descriptor file to create and start a VM on Compute Engine.

On Compute Engine, you can import OVA or OVF files as follows:

Before you begin

Enable the Cloud Build API

The virtual appliance import tool uses Cloud Build.

In most cases, gcloud compute 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

  1. 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 Cloud 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:

  1. 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 Cloud 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.

  2. 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
    
  3. 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
    
  4. 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:

Requirements

Source VM requirements

The following requirements must be met by the VM that is used to create the OVF file:

  • Virtual disks must be in VMDK or VHD formats.
  • Virtual disks must be configured with MBR boot. UEFI is not supported.
  • Virtual disks must not be encrypted.

    To verify that your VM meets the requirements, you can run the precheck tool.

The operating system for the source VM should meet the following requirements:

  • For all Windows operating systems, PowerShell version 3 or later must be installed. PowerShell versions earlier than 3.0 can cause issues with the startup and shutdown scripts used during the import process.
  • For all Linux distributions, the boot disk must meet the following requirements:

    • The boot disk must have GRUB installed.
    • The boot disk must not span multiple physical disks. A disk partitioned by using a Logical Volume Manager (LVM) is not supported. If the disk spans multiple physical disks, then the VM created from the OVF file might not boot on Compute Engine.

OVF file requirements

The following requirements must be met by the OVF file:

  • The OVF files must provide Level 1 portability as described in the OVF specification document. Virtual appliances that meet Level 2 portability can be imported, but any custom extensions such as source hypervisor-specific details are ignored during the import process.
  • The OVF file must contain only one VM. If more than one VM is present, only the first VM is imported.
  • The first disk in the OVF file must be bootable.

Configurations that are imported by the import tool

The OVF standard specifies the process for packaging virtual appliances in a manner that does not depend on the virtualization provider. OVF virtual appliances packages contain one .ovf descriptor file and a collection of other resources such as virtual disks.

When you import an OVF virtual appliance to Compute Engine, the following configurations from the descriptor file are processed and imported:

  • Virtual Disks. Information retrieved from the DiskSection element of the OVF package.
  • CPU and Memory. Retrieved from the ResourceAllocationSection of the OVF package.

    If the CPU or memory configurations are outside the limits of the supported range in Compute Engine, the import process sets the values to the max that is supported on Compute Engine.

  • Boot Disk. Details retrieved from the BootDeviceSection element of the OVF package.

  • Guest OS. Details retrieved from the OperatingSystemSection element of the OVF package.

    The guest OS information is used to install the correct drivers and guest environment packages on the imported instance. If the guest OS information found in OVF is incorrect, the import fails. You can use the --os flag to override guest OS information.

Imported instances are always created with a single network adapter with an external IP address. This single network adapter is used regardless of the networking configurations specified in the OVF file. To import a VM with no external IP address, see Importing a VM with no external IP address.

Limitations

  • When importing a virtual appliance, the following sections of the descriptor file are ignored (not imported):

    • NetworkSection
    • AnnotationSection
    • ProductSection
    • EulaSection
    • StartupSection
    • DeploymentOptionSection
    • InstallSection
    • EnvironmentFilesSection
    • SharedDiskSection
    • ScaleOutSection
    • PlacementGroupSection
    • PlacementSection
    • EncryptionSection

Supported operating systems

Specify one of the following operating systems in the OperatingSystemSection of your descriptor file or by using the --os flag option during the import:

Linux distributions and versions

  • CentOS 6, CentOS 7, and CentOS 8
  • Debian 8, Debian 9
  • Red Hat Enterprise Linux 6, Red Hat Enterprise Linux 7, and Red Hat Enterprise Linux 8
  • Ubuntu 14.04 LTS, Ubuntu 16.04 LTS, and Ubuntu 18.04 LTS
  • SUSE Linux Enterprise Server 12, SUSE Linux Enterprise Server 15, and OpenSUSE 15

Windows versions

  • Windows Server 2008 R2 SP1
  • Windows Server 2012, Windows Server 2012 R2, Windows Server 2012 R2 Core
  • Windows Server 2016, Windows Server 2016 Core
  • Windows Server 2019, Windows Server 2019 Core
  • Windows 7 SP1 (32-bit and 64-bit, BYOL only)
  • Windows 8.1 (32-bit and 64-bit, BYOL only)
  • Windows 10, versions 1709, 1803, 1903, 1909 (32-bit and 64-bit, BYOL only)

Support for BYOL

By default, OVF files that use Windows Server and Red Hat Enterprise Linux (RHEL) operating systems are imported and configured to use premium OS on-demand billing, which incurs additional charges.

If you prefer to use your own software subscription, you can import virtual appliances as bring-your-own-license (BYOL)–licensed appliances. This is available for Windows Server, Red Hat Enterprise Linux (RHEL), and SUSE Linux Enterprise Server (SLES).

To import appliances as BYOL licensed appliances, specify one of following BYOL values for the [--os] flag when you run the import command.

  • rhel-6-byol
  • rhel-7-byol
  • rhel-8-byol
  • sles-12-byol
  • sles-15-byol
  • windows-2008r2-byol
  • windows-2012-byol
  • windows-2012r2-byol
  • windows-2016-byol
  • windows-2019-byol
  • windows-7-x64-byol
  • windows-7-x86-byol
  • windows-8-x64-byol
  • windows-8-x86-byol
  • windows-10-x64-byol
  • windows-10-x86-byol

Importing an OVA file

gcloud

  1. Upload the virtual appliance to Cloud Storage.
  2. To import an OVA file from Cloud Storage to Compute Engine, use the gcloud compute instances import command.

    gcloud compute instances import INSTANCE_NAME \
       --source-uri=gs:PATH_TO_OVA_FILE
    

    Replace the following:

    • INSTANCE_NAME: the name of the instance you want to create
    • PATH_TO_OVA_FILE: the path to your OVA file on Cloud Storage

    Examples

    For example, to import an OVA file Ubuntu.ova and create an instance named my-instance, run the following command:

    gcloud compute instances import my-instance \
        --source-uri=gs://my-bucket/Ubuntu.ova
    

    In some cases, you might be prompted to provide a value for the OS. To specify the operating system, you need to add the --os flag. For a list of supported values, review the --os flag options for the gcloud compute instances import command.

    For example, to import an OVA file Ubuntu.ova and create an instance named my-instance that runs Ubuntu 16.04, run the following command:

    gcloud compute instances import my-instance \
        --os=ubuntu-1604
        --source-uri=gs://my-bucket/Ubuntu.ova
    

API

  1. Upload the virtual appliance to Cloud Storage.

  2. In the API, create a POST request to the Cloud Build API.

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

    Replace the following:

    • PROJECT_ID: the project ID for the project that you want to import the OVA file into.
    • TIMEOUT: the maximum time a build should last before it fails with a TIMEOUT message. In the API, the time must be specified in seconds. A timeout value of 7200s should work for most scenarios.
    • INSTANCE_NAME: the name for the virtual machine instance to create. For example, my-instance.
    • SOURCE_URI: the URI for the OVA file that is stored in Cloud Storage. For example, gs://my-bucket/my-instance.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, review the --os flag options for the gcloud compute instances import command.
    • ZONE: the zone in which to create the VM instance. If left blank, the default zone for the project is used.

    For additional args values that can be provided, see the optional flags section of the Compute Engine OVF import GitHub page.

    Example response

    The following sample response resembles the output that is returned:

    {
    "name": "operations/build/myproject-12345/operation-1578608233418",
    "metadata": {
      "@type": "type.googleapis.com/google.devtools.cloudbuild.v1.BuildOperationMetadata",
      "build": {
        "id": "3a2055bc-ccbd-4101-9434-d376b88b8940",
        "status": "QUEUED",
        "createTime": "2019-12-30T19:06:03.968694865Z",
        "steps": [
          {
            "name": "gcr.io/compute-image-tools/gce_ovf_import:release",
            "env": [
              "BUILD_ID=3a2055bc-ccbd-4101-9434-d376b88b8940"
            ],
            "args": [
              "-instance-names=my-instance",
              "-ovf-gcs-path=gs://my-bucket/my-instance.ova",
              "-os=rhel-6",
              "-zone=asia-northeast2",
              "-client-id=api",
              "-timeout": "7056s"
            ]
          }
        ],
        "timeout": "7200s",
        "projectId": "myproject-12345",
        "logsBucket": "gs://12345.cloudbuild-logs.googleusercontent.com",
        "options": {
          "logging": "LEGACY"
        },
        "logUrl": "https://console.cloud.google.com/gcr/builds/3a2055bc-ccbd-4101-9434-d376b88b8940?project=myproject-12345",
        "tags": [
          "gce-ovf-import"
        ]
      }
    }
    }
    

    To monitor your build, you can use one of the following methods:

    • Run a projects.builds.get request using the returned build-id.
    • Review the logs hosted at the provided logUrl.

Importing an OVF file

gcloud

  1. Upload the virtual appliance to Cloud Storage.
  2. To import an OVF file from Cloud Storage to Compute Engine, use the gcloud compute instances import command.

    If your directory contains only one OVF file, you can either provide the path to the descriptor file or the path to the directory that contains the OVF file.

    • To import an OVF file using the path to the descriptor file, run the following command:

      gcloud compute instances import INSTANCE_NAME \
       --source-uri=gs:PATH_TO_OVF_FILE
      
    • To import an OVF file using the directory path, run the following command:

      gcloud compute instances import INSTANCE_NAME \
       --source-uri=gs:PATH_TO_OVF_DIRECTORY
      

    Replace the following:

    • INSTANCE_NAME: the name of the instance to create
    • PATH_TO_OVF_FILE: the path to the OVF file on Cloud Storage
    • PATH_TO_OVF_DIRECTORY: the path to the directory that contains the OVF file on Cloud Storage

    Examples

    • To import an OVF file Ubuntu.ovf from the my-ovf-directory directory that creates an instance named my-instance, run the following command:

      gcloud compute instances import my-instance \
       --source-uri=gs://my-bucket/my-ovf-directory/Ubuntu.ovf
      
    • To import an OVF file from the my-ovf-directory directory that creates an instance named my-instance, run the following command:

      gcloud compute instances import my-instance \
       --source-uri=gs://my-bucket/my-ovf-directory
      

      In some cases, you might be prompted to provide a value for the OS. To specify the operating system, you need to add the --os flag. For a list of supported values, review the --os flag options for the gcloud compute instances import command. For example, to import an OVF file Ubuntu.ovf and create an instance named my-instance that runs Ubuntu 16.04, run the following command:

      gcloud compute instances import my-instance \
       --os=ubuntu-1604 \
       --source-uri=gs://my-bucket/my-ovf-directory/Ubuntu.ovf
      

API

  1. Add the virtual appliance to Cloud Storage.

  2. In the API, create a POST request to the Cloud Build API.

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

    Replace the following:

    • PROJECT_ID: the project ID for the project that you want to import the OVA file into.
    • TIMEOUT: the maximum time a build should last before it fails with a TIMEOUT message. In the API, the time must be specified in seconds. A timeout value of 7200s should work for most scenarios.
    • INSTANCE_NAME: the name for the virtual machine instance to create. For example, my-instance.
    • SOURCE_URI: the URI for the OVF file that is stored in Cloud Storage. For example, gs://my-bucket/my-instance.ovf.
    • OS: the operating system of the OVF 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, review the --os flag options for the gcloud compute instances import command.
    • ZONE: the zone in which to create the VM instance. If left blank, the default zone for the project is used.

    For additional args values that can be provided, see the optional flags section of the Compute Engine OVF import GitHub page.

    Example response

    The following sample response resembles the output that is returned:

    {
    "name": "operations/build/myproject-12345/operation-1578608233418",
    "metadata": {
      "@type": "type.googleapis.com/google.devtools.cloudbuild.v1.BuildOperationMetadata",
      "build": {
        "id": "3a2055bc-ccbd-4101-9434-d376b88b8940",
        "status": "QUEUED",
        "createTime": "2019-12-30T19:06:03.968694865Z",
        "steps": [
          {
            "name": "gcr.io/compute-image-tools/gce_ovf_import:release",
            "env": [
              "BUILD_ID=3a2055bc-ccbd-4101-9434-d376b88b8940"
            ],
            "args": [
              "-instance-names=my-instance",
              "-ovf-gcs-path=gs://my-bucket/my-instance.ovf",
              "-os=ubuntu-1404",
              "-zone=asia-south1",
              "-client-id=api",
              "-timeout": "7056s"
            ]
          }
        ],
        "timeout": "7200s",
        "projectId": "myproject-12345",
        "logsBucket": "gs://12345.cloudbuild-logs.googleusercontent.com",
        "options": {
          "logging": "LEGACY"
        },
        "logUrl": "https://console.cloud.google.com/gcr/builds/3a2055bc-ccbd-4101-9434-d376b88b8940?project=myproject-12345",
        "tags": [
          "gce-ovf-import"
        ]
      }
    }
    }
    

    There are a couple ways you can monitor your build:

    • Run a projects.builds.get request using the returned build-id.
    • Review the logs hosted at the provided logUrl.

Importing with custom settings

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 an OVA or import an OVF file and specify the --custom-cpu and --custom-memory flags.

Example

For example, to import an instance named my-instance that runs Ubuntu 1404 and has 2 CPUs and 2048 MB of memory, run the following command:

gcloud compute instances import my-instance \
    --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 Cloud Build API steps to import an OVA or import an OVF file and specify the -machine-type argument. This -machine-type represents a predefined or custom machine type to use.

Example

For example, to import an instance named my-instance that runs Ubuntu 1404 and has 2 CPUs and 2048 MB of memory, use the following request. Replace PROJECT_ID with your project ID.

POST https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/builds
{
  "timeout":"7200s",
  "steps":[
    {
      "args":[
        "-instance-names=my-instance",
        "-ovf-gcs-path=gs://my-bucket/Ubuntu.ova",
        "-os=ubuntu-1404",
        "-machine-type=custom-2-2048",
        "-zone=asia-south1",
        "-client-id=api",
        "-timeout=7056s"
      ],
      "name":"gcr.io/compute-image-tools/gce_ovf_import:release",
      "env":[
        "BUILD_ID=$BUILD_ID"
      ]
    }
  ],
  "tags":[
    "gce-ovf-import"
  ]
}

Custom networks

gcloud

To use a custom network, follow the gcloud command-line tool steps to import an OVA or import an OVF file and specify a --network flag. If the network is configured with a custom subnet mode, you must also specify --subnet and --zone flags.

Example

For example, consider the following properties:

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

Run the following command to import an instance with the preceding properties:

gcloud compute instances import my-instance --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 Cloud Build API steps to import an OVA or import an OVF file and specify a -network argument. If the network is configured with a custom subnet mode, you must also specify -subnet and -zone arguments.

Example

For example, consider the following properties:

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

Create the following POST request to import an instance with the preceding properties. Replace PROJECT_ID with your project ID.

POST https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/builds
{
  "timeout":"7200s",
  "steps":[
    {
      "args":[
        "-instance-names=my-instance",
        "-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=7056s"
      ],
      "name":"gcr.io/compute-image-tools/gce_ovf_import:release",
      "env":[
        "BUILD_ID=$BUILD_ID"
      ]
    }
  ],
  "tags":[
    "gce-ovf-import"
  ]
}

Importing a VM with no external IP address

To import a VM with no external IP, you must use the Cloud Build API.

  1. Add the virtual appliance to Cloud Storage.

  2. Configure Private Google Access. For detailed instructions, see Configuring Private Google Access.

  3. Import the VM with an override for the external IP.

    To override the external IP settings specified in the OVF file, follow the Cloud Build API steps to import an OVA or import an OVF file and specify the -no-external-ip argument.

    Example

    For example, to import an instance named my-instance that runs Ubuntu 1404 and has no external IP, use the following request. Replace PROJECT_ID with your project ID.

    POST https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/builds
    {
      "timeout":"7200s",
      "steps":[
        {
          "args":[
            "-instance-names=my-instance",
            "-ovf-gcs-path=gs://my-bucket/Ubuntu.ova",
            "-os=ubuntu-1404",
            "-no-external-ip",
            "-zone=asia-south1",
            "-client-id=api",
            "-timeout=7056s"
          ],
          "name":"gcr.io/compute-image-tools/gce_ovf_import:release",
          "env":[
            "BUILD_ID=$BUILD_ID"
          ]
        }
      ],
      "tags":[
        "gce-ovf-import"
      ]
    }
    

What's next