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 instances 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 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 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 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 VMs 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.

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

Limitations

This feature is not supported for projects that are protected with VPC Service Controls.

Supported operating systems

Specify the operating system in the OperatingSystemSection of your descriptor file or by using the --os flag option when importing by using the gcloud compute instances import command.

For information about which operating systems are supported, see Operating system details.

Support for BYOL and BYOS

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 license or subscription, you can import your virtual appliances with their licenses. For information about the operating systems that support BYOL or BYOS, see Operating system details.

To import appliances as BYOL licensed appliances, specify the appropriate BYOL values for the [--os] flag when you run the gcloud compute instances import command.

Importing across projects

  • Source project: the project where the OVA or OVF file is stored.
  • Destination project: the project where you want to create the VM or machine image.

If your source and destination project are different, then the service accounts in the destination project needs access to the Cloud Storage bucket in your source project.

To import across projects, complete the following steps:

  1. In your source project, locate the Cloud Storage bucket.
  2. On the Cloud Storage bucket, grant roles/storage.objectViewer to the following service accounts:

    • Cloud Build service account for the destination project: this service account has the format DESTINATION_PROJECT_NUMBER@cloudbuild.gserviceaccount.com
    • Compute Engine service account for the destination project: this service account has the format DESTINATION_PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Replace DESTINATION_PROJECT_NUMBER with the project number for the destination project.

    For instructions on granting access to a Cloud Storage bucket, see Adding a member to a bucket-level policy.

  3. Import the virtual appliance or machine image.

Importing virtual appliances

You can import your virtual appliance using either the gcloud command-line tool, or the Cloud Build API.

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 VM_NAME \
       --source-uri=gs:PATH_TO_OVA_FILE
    

    Replace the following:

    • VM_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": "7200s",
     "steps":[
       {
         "args":[
           "-instance-names=VM_NAME",
           "-ovf-gcs-path=SOURCE_URI",
           "-os=OS",
           "-zone=ZONE",
           "-client-id=api",
           "-timeout=7000s"
         ],
         "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.
    • VM_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/cloud-build/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 VM_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 VM_NAME \
       --source-uri=gs:PATH_TO_OVF_DIRECTORY
      

    Replace the following:

    • VM_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": "7200s",
     "steps":[
       {
         "args":[
           "-instance-names=VM_NAME",
           "-ovf-gcs-path=SOURCE_URI",
           "-os=OS",
           "-zone=ZONE",
           "-client-id=api",
           "-timeout=7000s"
         ],
         "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.
    • VM_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/cloud-build/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 1—using a custom network

For example, assume the following properties:

  • VM 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. Replace SERVICE_PROJECT_ID with the ID for the project that you want to import the virtual appliance to.

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

Example 2—using a custom network (shared VPC)

For example, assume the following properties:

  • VM name: my-instance-2
  • Operating system: Ubuntu 1404
  • Network: my-shared-vpc
  • Subnet: my-shared-subnet
  • Zone: us-east1-c

To import a VM with the preceding properties, complete the following steps:

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

    gcloud projects add-iam-policy-binding HOST_PROJECT_ID \
      --member serviceAccount:SERVICE_PROJECT_NUM@cloudbuild.gserviceaccount.com \
      --role roles/compute.networkUser
    

    Replace the following:

    • HOST_PROJECT_ID: ID of the project where the shared VPC is located
    • SERVICE_PROJECT_NUM: project number for the project that you want to import the virtual appliance to
  2. Import the VM.

    gcloud compute instances import my-instance-2 \
       --os ubuntu-1404 \
       --source-uri gs://my-bucket/Ubuntu.ova \
       --project SERVICE_PROJECT_ID \
       --network projects/HOST_PROJECT_ID/global/networks/my-shared-vpc \
       --subnet projects/HOST_PROJECT_ID/regions/us-east1/subnetworks/my-shared-subnet
       --zone us-east1-c
    

    Replace the following:

    • SERVICE_PROJECT_ID: ID for the project that you want to import the virtual appliance to
    • HOST_PROJECT_ID: ID of the project where the shared VPC is located

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—using a custom network

For example, assume the following properties:

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

Create the following POST request to import an instance with the preceding properties. Replace SERVICE_PROJECT_ID with the ID for the project that you want to import the virtual appliance to.

POST https://cloudbuild.googleapis.com/v1/projects/SERVICE_PROJECT_ID/builds
{
  "timeout":"7200s",
  "steps":[
    {
      "args":[
        "-instance-names=my-instance",
        "-ovf-gcs-path=gs://my-bucket/Ubuntu.ova",
        "-os=ubuntu-1404",
        "-zone=us-east1-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=$BUILD_ID"
      ]
    }
  ],
  "tags":[
    "gce-ovf-import"
  ]
}

Example 2—using a custom network (shared VPC)

For example, assume the following properties:

  • VM name: my-instance-2
  • Operating system: Ubuntu 1404
  • Network: my-shared-vpc
  • Subnet: my-shared-subnet
  • Zone: us-east1-c

To import a VM with the preceding properties, complete the following steps:

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

    gcloud projects add-iam-policy-binding HOST_PROJECT_ID \
      --member serviceAccount:SERVICE_PROJECT_NUM@cloudbuild.gserviceaccount.com \
      --role roles/compute.networkUser
    

    Replace the following:

    • HOST_PROJECT_ID: ID of the project where the shared VPC is located
    • SERVICE_PROJECT_NUM: project number for the project that you want to import the virtual appliance to
  2. Create the following POST request to import the VM.

    POST https://cloudbuild.googleapis.com/v1/projects/SERVICE_PROJECT_ID/builds
    {
     "timeout":"7200s",
     "steps":[
       {
         "args":[
           "-instance-names=my-instance-2",
           "-ovf-gcs-path=gs://my-bucket/Ubuntu.ova",
           "-os=ubuntu-1404",
           "-zone=us-east1-c",
           "-network=projects/HOST_PROJECT_ID/global/networks/my-shared-vpc",
           "-subnet=projects/HOST_PROJECT_ID/regions/us-east1/subnetworks/my-shared-subnet",
           "-client-id=api",
           "-timeout=7000s"
         ],
         "name":"gcr.io/compute-image-tools/gce_ovf_import:release",
         "env":[
           "BUILD_ID=$BUILD_ID"
         ]
       }
     ],
     "tags":[
       "gce-ovf-import"
     ]
    }
    

    Replace the following:

    • SERVICE_PROJECT_ID: ID for the project that you want to import the virtual appliance to.
    • HOST_PROJECT_ID: ID of the project where the shared VPC is located.

Importing a VM using networks that don't allow external IP addresses

To import a VM using networks that don't allow external IP addresses, complete the following steps:

  1. Add the virtual appliance to Cloud Storage.

  2. The import process requires package managers to be installed on the operating system for the VM. 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.

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

  4. Import the VM using either gcloud command-line tool or Cloud Build API.

    When VM is created 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, click the following tabs:

gcloud

To import a virtual appliance from Cloud Storage to Compute Engine, use the gcloud compute instances import command with the --no-address flag.

gcloud compute instances import VM_NAME \
    --source-uri=SOURCE_URI \
    --os=OS \
    --zone=ZONE \
    --no-address

Replace the following:

  • VM_NAME: the name of the instance you want to create.
  • SOURCE_URI: URI for your OVA or OVF file on Cloud Storage. For example, gs://my-bucket/Ubuntu.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 virtual appliance. If left blank, the default zone for the project is used.

API

You can import a VM with no external IP by using the Cloud Build API 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.

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

Replace the following:

  • PROJECT_ID: project ID for the project that you want to import the image into.
  • VM_NAME: name of the VM to create.
  • SOURCE_FILE: URI for the image in Cloud Storage. For example, gs://my-bucket/Ubuntu.ova.
  • OS: operating system of the image. For a list of supported values, review the --os flag options for the gcloud compute images import command.
  • ZONE: the zone in which to create the image. If left blank, the default zone for the project is used.

Importing an OVA file with UEFI bootloader

You can import an OVA file with an UEFI bootloader by using the Cloud Build API and specifying the -uefi-compatible argument.

  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": "7200s",
     "steps":[
       {
         "args":[
           "-instance-names=VM_NAME",
           "-ovf-gcs-path=SOURCE_URI",
           "-os=OS",
           "-uefi-compatible",
           "-zone=ZONE",
           "-client-id=api",
           "-timeout=7000s"
         ],
         "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.
    • VM_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.

Importing a virtual appliance using custom service accounts

During a virtual appliance 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

  1. Add the virtual appliance to Cloud Storage.

  2. 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.

  3. Use the gcloud compute instances import command to import the virtual appliance.

    gcloud compute instances import VM_NAME \
    --source-uri=SOURCE_URI \
    --os=OS \
    --zone=ZONE \
    --compute-service-account=TEMP_SERVICE_ACCOUNT_EMAIL \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --scopes=SCOPES
    

    Replace the following:

    • VM_NAME: the name of the instance you want to create.
    • SOURCE_URI: URI for your OVA or OVF file on Cloud Storage. For example, gs://my-bucket/Ubuntu.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 virtual appliance. If left blank, the default zone for the project is used.
    • 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 the VM created by the import process. 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

  1. Add the virtual appliance to Cloud Storage.

  2. 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.

  3. 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":[
            "-instance-names=VM_NAME",
            "-ovf-gcs-path=SOURCE_FILE",
            "-os=OS",
            "-compute-service-account=TEMP_SERVICE_ACCOUNT_EMAIL",
            "-service-account=SERVICE_ACCOUNT_EMAIL",
            "-zone=ZONE",
            "-scopes=SCOPES",
            "-client-id=api",
            "-timeout=7000s"
          ],
          "name":"gcr.io/compute-image-tools/gce_ovf_import:release",
          "env":[
            "BUILD_ID=$BUILD_ID"
          ]
        }
      ],
      "tags":[
        "gce-ovf-import"
      ]
    }
    

    Replace the following:

    • PROJECT_ID: project ID for the project that you want to import the image into.
    • VM_NAME: name of the VM to create.
    • SOURCE_FILE: URI for the image in Cloud Storage. For example, gs://my-bucket/Ubuntu.ova.
    • OS: operating system of the image. For a list of supported values, review the --os flag options for the gcloud compute images import command.
    • ZONE: the zone in which to create the image. If left blank, the default zone for the project is used.
    • 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 the VM created by the import process. 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