Import 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 Choose a migration path.

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

  • If the project that you want to import the virtual appliance to has a trusted image policy defined, add projects/compute-image-import and 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.
  • To find out how to meet requirements before importing images, see Prerequisites for importing and exporting VM images.
  • If you haven't already, set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine as follows.

    Select the tab for how you plan to use the samples on this page:

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command:

      gcloud init
    2. Set a default region and zone.

    REST

    To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

      Install the Google Cloud CLI, then initialize it by running the following command:

      gcloud init

Requirements

This section lists requirements for importing virtual appliances to Compute Engine.

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.

Permissions

To enable a seamless experience when importing images, ensure that you've granted required IAM roles to your account, the Cloud Build service account, and the Compute Engine service account. For more information, see Grant required IAM roles.

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

You can optionally specify the operating system in the OperatingSystemSection element of your descriptor file or specify the --os flag when you import virtual appliance 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.

You can import appliances as BYOL licensed appliances by using the gcloud compute instances import command with the --byol flag. If you are manually specifying the OS, use the --os flag to specify a value that contains the byol suffix for the guest OS that you want to import. For example, --os=rhel-8-byol imports a RHEL 8 image with an existing license.

Import 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 principal to a bucket-level policy.

  3. Import the virtual appliance or machine image.

Import virtual appliances

You can import your virtual appliance using either the Google Cloud CLI, or REST.

Import 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
    

    If the guest OS information in the OVF descriptor file is incorrect or if you want to override the detected OS, you can specify the operating system by adding 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
    

REST

  1. Upload the virtual appliance to Cloud Storage.

  2. Send 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",
           "-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.
    • 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",
              "-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.

Import 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
      

      If the guest OS information in the OVF descriptor file is incorrect or if you want to override the detected OS, you can specify the operating system by adding 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
      

REST

  1. Add the virtual appliance to Cloud Storage.

  2. Send 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. The --os flag is optional by default, but you can override the detected OS by using 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 Google Cloud CLI 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 has 2 CPUs and 2048 MB of memory, run the following command:

gcloud compute instances import my-instance \
    --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 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 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",
        "-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

The custom network must be defined in the same project that you're importing the image into.

gcloud

To use a custom network, follow the Google Cloud CLI 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
  • 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 \
    --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
  • 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 Cloud Build service account. For more information, see Grant required roles to the Cloud Build service account.

  2. Import the VM.

    gcloud compute instances import my-instance-2 \
       --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

REST

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
  • 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",
        "-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
  • 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 Cloud Build service account. For more information, see Grant required roles to the Cloud Build service account.

  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",
           "-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.

Import 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 Google Cloud CLI or REST.

    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 \
    --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.
  • ZONE: the zone in which to create the virtual appliance. If left blank, the default zone for the project is used.

REST

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",
        "-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.
  • ZONE: the zone in which to create the image. If left blank, the default zone for the project is used.

Import an OVA file with UEFI bootloader

gcloud

You can use the gcloud compute instances import command to force an import to use UEFI boot.

gcloud compute instances import VM_NAME \
  --source-uri=SOURCE_URI \
  --guest-os-features=UEFI_COMPATIBLE

Replace the following:

  • VM_NAME: the name of the VM you want to create.
  • SOURCE_URI: URI for your OVA or OVF file on Cloud Storage. For example, gs://my-bucket/Ubuntu.ova.

REST

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",
           "-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.
    • ZONE: the zone in which to create the VM instance. If left blank, the default zone for the project is used.

Import 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. For more information, see Grant required roles to the Compute Engine service account.

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

    gcloud compute instances import VM_NAME \
    --source-uri=SOURCE_URI \
    --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.
    • 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.

REST

  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 argument. For more information, see Grant required roles to the Compute Engine service account.

  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",
            "-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.
    • 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