Import virtual disks

If you have virtual disks in your on-premises environment with software and configurations that you need, occasionally referred to as golden disks or golden images, you can save time by importing those virtual disks into Distributed Cloud and using the resulting image to create virtual machines. The import tool supports RAW and QCOW image formats.

Before you begin

Before continuing, ensure that you have the following:

  • The gdcloud CLI downloaded, installed, and configured. All CLI commands for GDC use the gdcloud or kubectl CLI, and require an operating system (OS) environment.

  • Login access to the Kubernetes cluster. Follow the CLI steps in Sign in to sign in to the Kubernetes cluster.

Request permissions and access

To perform the tasks listed in this page, you must have the Project VirtualMachine Admin role. Follow the steps to verify that you have the Project VirtualMachine Admin (project-vm-admin) role in the namespace of the project where the VM resides.

For VM operations using the GDC console or the gdcloud CLI, request your Project IAM Admin to assign you the roles listed in the previous paragraph and the Project Viewer (project-viewer) role.

Import virtual disks

You can import your virtual disks using either the gdcloud CLI or the Virtual Machine Manager API.

To get the permissions you need to import images, ask your Organization IAM Admin to grant you the Project VirtualMachine Image Admin (project-vm-image-admin) role for your project.

gdcloud

Use the gdcloud compute images import command to create a bootable image.

The import command ensures that the disk has the required packages, including the guest environment, which is required to configure credentials for connecting to the instance using secure shell (SSH) on Linux and Remote Desktop Protocol (RDP) on Windows.

On Linux, the command also installs packages for network time protocol (NTP) and cloud-init for the instance to run properly in GDC.

You can import virtual disk files directly from your workstation. The import tool automatically uploads the file to an object storage bucket in your project.

gdcloud compute images import IMAGE_NAME \
  --source-file=SOURCE_FILE \
  --os=IMAGE_OS \
  --timeout=TIMEOUT

Replace the following variables:

  • IMAGE_NAME: the name of your destination image. The name must be no longer than 35 characters.
  • SOURCE_FILE: your virtual disk file. This file is a local file on your workstation. You can provide an absolute or relative path.
  • IMAGE_OS: the OS on the disk to import.
  • TIMEOUT: the time an import can last before it fails with "TIMEOUT". For example, if you specify 2h, the process fails after 2 hours. The default timeout is 1h.

The upload operation can take an extended period of time depending on the size of your virtual disk and the speed of your network connection. The import operation can take tens of minutes to run depending on the size of the disk.

API

Before starting the import process with the API, you need to upload your virtual disk to an object storage bucket named vm-images-bucket. To create an object storage bucket, see Create storage buckets for projects.

To import a virtual disk through the API, do the following:

  1. Create a VirtualMachineImageImport object in the Management API server to start the image import process:

    kubectl --kubeconfig MANAGEMENT_API_SERVER \
  apply -n PROJECT_ID -f - <<EOF
apiVersion: virtualmachine.gdc.goog/v1
kind: VirtualMachineImageImport
metadata:
  name: IMAGE_NAME
  namespace: PROJECT_ID
spec:
  source:
    objectStorage:
      bucketRef:
        name: vm-images-bucket
      objectName: SOURCE_FILE
  imageMetadata:
    name: IMAGE_NAME
    operatingSystem: OPERATING_SYSTEM
    minimumDiskSize: DISK_SIZE
EOF

    Replace the following variables:

    Variable Description
    IMAGE_NAME The name of the image to import. The name must be no longer than 35 characters.
    PROJECT_ID The project ID for the project where you want to import the image.
    SOURCE_FILE The name of the source file that contains the upload of the virtual disk to object storage. This value is the section of the object storage path after vm-images-bucket/.
    OPERATING_SYSTEM The OS on the disk to import.
    DISK_SIZE The minimum size a disk must have to be created with this image. We recommend that at least a 20% buffer is used on top of the file system size of the original image. For example: use at least 12Gi for a virtual disk with original file system size 10Gi.

  2. Monitor the progress of the import by querying the status of the VirtualMachineImageImport object:

    kubectl --kubeconfig MANAGEMENT_API_SERVER \
  get virtualmachineimageimport --namespace PROJECT_ID \
  IMAGE_NAME -o jsonpath='{.status}'

Clean up resources

The import process involves uploading your virtual disk file to object storage. If you use the gdcloud CLI, the object is cleaned up when the command finishes, whether or not it was successful. If the command is interrupted, or the image import is done with the API, the virtual disk file might remain in the object storage bucket named vm-images-bucket until you manually delete the file.

What's next

Create a new VM instance that uses your image in the page, Create and start a VM.