Import virtual disks

This document describes the steps to import virtual machine (VM) disk images into Google Distributed Cloud (GDC) air-gapped.

Import your existing virtual disks, often called golden disks or golden images, into Distributed Cloud to save time and use the resulting image to create virtual machines. The import tool supports RAW and QCOW image formats.

This document is for developers in platform administrator or application operator groups that create VM images. For more information, see Audiences for GDC air-gapped documentation.

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.

Request permissions and access

To import images and perform the VM operations listed on this page, ask your Project IAM Admin to grant you the following IAM roles in the namespace of the project where the VM resides:

  • Project VirtualMachine Admin (project-vm-admin): manages VMs in the project namespace.

  • Project Viewer (project-viewer): has read-only access to all resources within a project namespace.

Follow the steps to verify your access.

Import virtual disks

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.

To import your virtual disks, use either the gdcloud CLI or the Virtual Machine Manager API.

gdcloud

The import command checks that the disk has the necessary packages to configure credentials for connecting to the instance using secure shell (SSH) and Remote Desktop Protocol (RDP). This includes the guest environment.

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

  • To create a bootable image, use the gdcloud compute images import command:
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

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 \
  -n PROJECT_ID \
  apply -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: IMAGE_OS
    minimumDiskSize: DISK_SIZE
EOF

    Replace the following variables:

    • 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/.
    • IMAGE_OS: 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 \
  -n PROJECT_ID \
  get virtualmachineimageimport.virtualmachine.gdc.goog 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 if you perform the image import 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