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 GDC 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](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/audiences.md.txt).

## Before you begin

Before continuing, ensure that you have the following:

### Prepare the environment

- The [gdcloud CLI](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-overview.md.txt) downloaded, installed, and configured. All CLI commands for GDC use the gdcloud CLI or the kubectl CLI, and require an operating system (OS) environment.

> [!NOTE]
> **Note:** Record the path to the generated file, `/tmp/admin-kubeconfig-with-user-identity.yaml`. Use the path to replace <var translate="no">MANAGEMENT_API_SERVER</var> in these instructions.

### Request IAM roles

To get the permissions that you need to import virtual disks, ask your IAM
Project Admin to grant you the following roles on your project:

- **Virtual Machine Project Admin** (`project-vm-admin`): create, modify, list,
  and delete VMs in the project namespace.

- **Project Viewer** (`project-viewer`): view all resources within the project
  namespace.

- **Virtual Machine Image Project Admin** (`project-vm-image-admin`): create,
  list, and delete VM images in the project namespace.

All VM roles must bind to the namespace of the project where the VM resides.
Follow the steps to [verify](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vms/preparation.md.txt#verify-user-access)
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.

> [!IMPORTANT]
> **Important:** To avoid boot errors in Unified Extensible Firmware Interface (UEFI) mode, verify that the source image is UEFI-compatible. A UEFI-compatible image requires a GUID Partition Table (GPT) and a FAT32-formatted EFI System Partition (ESP) with a properly structured boot loader.

To import your virtual disks, use either the gdcloud CLI or the
[Virtual Machine Manager API](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/apis/service/virtualmachine/vmm-api-overview.md.txt).

### gdcloud


The `import` command checks that the GDC-provided image
has the required packages to configure credentials for connecting to the instance
using secure shell (SSH) and Remote Desktop Protocol (RDP). This includes
packages for 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:

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

Replace the following variables:

- <var translate="no">IMAGE_NAME</var>: the name of your destination image. The name must be no longer than 35 characters.
- <var translate="no">SOURCE_FILE</var>: your virtual disk file. This file is a local file on your workstation. You can provide an absolute or relative path.
- <var translate="no">IMAGE_OS</var>: the OS on the disk to import.
- <var translate="no">TIMEOUT</var>: 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.

<br />

### API

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

1. Create a `VirtualMachineImageImport` custom resource in the management API
   server to start the image import process:

   ```bash
   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:
   - <var translate="no">MANAGEMENT_API_SERVER</var>: the kubeconfig file for the management API server.
   - <var translate="no">IMAGE_NAME</var>: the name of the image to import. The name must be no longer than 35 characters.
   - <var translate="no">PROJECT_ID</var>: the project ID for the project where you want to import the image.
   - <var translate="no">SOURCE_FILE</var>: 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/`.
   - <var translate="no">IMAGE_OS</var>: the OS on the disk to import.
   - <var translate="no">DISK_SIZE</var>: the minimum size for a disk that you create from this image. Use at least a 20% buffer on top of the file system size of the original image. For example, use at least `12G` for a virtual disk with an original file system size of 10G.
2. Monitor the progress of the import by querying the status of the
   `VirtualMachineImageImport` custom resource:

   ```bash
   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 CLI deletes the object when the command
finishes, even if the import fails. If you interrupt the command, or
if you import the image 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

- Review [GDC-supported images](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vms/create-a-vm/supported-vm-images.md.txt).
- [Create and start a VM](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vms/create-a-vm/create-and-start.md.txt) instance that uses your image.
- [Create a boot disk](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vms/manage-vm-boot-disks/create-customized-boot-disk.md.txt) for your VM.