Oracle Linux 8 and 9 OS image import in GDC air-gapped

This solution reference implementation outlines a customer-managed, shift-left strategy to manually import the Oracle Linux 8 and 9 operating system into Google Distributed Cloud (GDC) air-gapped. Standard automated tools fail on unsupported OSes because the automated image translation and agent injection processes break.

This technical guide solves the issue by performing an offline image surgery on a local workstation using QEMU utilities. By modifying the .qcow2 virtual disk, configuring required settings like NTP, optionally installing the GDC guest agent and cloud-init inside the chroot environment, and using the --os=garden-linux flag during import, the platform's native translation engine is completely bypassed. Finally, the configured VM can be captured as a reusable Golden Image (VirtualMachineImage) to ensure scalable deployments with native startup script support.

Architecture

Oracle Linux 8 and 9 OS image import architecture diagram.

  • Image Preparation Unit: Offline modification of the .qcow2 disk via qemu-nbd and chroot on a local workstation.
  • GDC Import Interface: Using the gdcloud CLI with the --os=garden-linux flag to safely ingest the image into GDC by bypassing automated processes.
  • Network & Access Management: Utilizing the GDC Serial Console for initial VM access, allowing the setup of the GDC guest agent and SSH keys.
  • Golden Image Capture Pipeline (Optional): Converting the custom-staged preparation VM into a VirtualMachineImage artifact to provide a scalable foundation for future deployments.

Before you begin

Ensure all prerequisites are met before beginning the offline image surgery:

  1. Project roles: To get the permissions that you need to manage VMs and VM images, ask your Project IAM Admin to grant you the following roles in your project namespace:
    • Virtual Machine Project Admin (project-vm-admin)
    • Project Viewer (project-viewer)
    • Virtual Machine Image Project Admin (project-vm-image-admin)
  2. Workstation Requirements: A Linux development workstation connected to the GDC environment network with the qemu-utils package installed.
  3. OS Compatibility (Virtio Drivers): The base image kernel must support and include Virtio drivers (virtio-net and virtio-scsi supporting virtio-spec 1.0, plus virtio_pci and virtio_blk). Without these, the VM will fail to recognize its network card and hard drive on GDC's underlying KubeVirt hypervisor.
  4. Base Image: A downloaded Oracle Linux 8 or 9 .qcow2 cloud image. For example, download the images from https://yum.oracle.com/oracle-linux-templates.html in qcow2 format.

Procedure

Optional: Obtain the GDC agent from a Rocky Linux VM

This step is needed only if GDC-managed SSH is required or wanted. If SSH access is managed manually by the customer, this step can be skipped.

Create a VM in the project you are using (YOUR_PROJECT_NAME) with a Rocky Linux image, and follow Connect to a Linux VM to connect to it. Once in it

dnf download gdc-guest-agent

The output should be similar to the following:

Rocky Linux 8 - AppStream - GDCH                                        11 MB/s |  19 MB     00:01
Rocky Linux 8 - BaseOS - GDCH                                           11 MB/s |  30 MB     00:02
Rocky Linux 8 - GDCH                                                   6.1 kB/s | 1.0 kB     00:00
gdc-guest-agent-1.15.0.21-x86_64.rpm

The output will be a package named gdc-guest-agent-VERSION-x86_64.rpm and this file should be transferred to the local workstation, for example by following Transfer Files from VM.

At this stage you should have on your local machine the downloaded Oracle Linux images in .qcow2 format and the GDC guest agent rpm package.

Mount the downloaded image locally

To locally mount the image, use the qemu-nbd utility, which maps the virtual file into a physical block device path.

First, in some images, a resize is needed to be able to install the agent and eventually more packages. Then we prepare for chroot.

# call the downloaded images oraclelinux8.qcow2 and oraclelinux9.qcow2
export VERSION= # can be 8 or 9

# Load the network block device kernel module
sudo modprobe nbd

# Connect device to qcow2 image
sudo qemu-nbd -c /dev/nbd0 oraclelinux${VERSION}.qcow2
# verify that boot partition is #3 and LVM partition is #4
sudo parted /dev/nbd0 print

# Detect LVM
sudo vgchange -ay

# Create a mount point
sudo mkdir -p /mnt/oracle${VERSION}

# Mount the LVM partition
sudo mount /dev/mapper/vg_main-lv_root /mnt/oracle${VERSION}
sudo mount -t proc /proc /mnt/oracle${VERSION}/proc
sudo mount -t sysfs /sys /mnt/oracle${VERSION}/sys
sudo mount -o bind /dev /mnt/oracle${VERSION}/dev
sudo mount -o bind /dev/pts /mnt/oracle${VERSION}/dev/pts
sudo mount -o bind /run /mnt/oracle${VERSION}/run

# mount the boot partition
sudo mount /dev/nbd0p3 /mnt/oracle${VERSION}/boot

# [OPTIONAL] Move the GDC agent rpm package to the mount path
sudo cp gdc-guest-agent-VERSION-x86_64.rpm /mnt/oracle${VERSION}/tmp/

# Enter the chroot environment to act as the root user inside the image
sudo chroot /mnt/oracle${VERSION}

After this command you are acting as root in the image and be able to make all the checks and needed changes.

Check dependencies (Virtio, chrony, cloud-init)

Verify that Virtio drivers are present in the image

# find version by doing
export INITRD=$(ls /boot/initramfs-*.img | grep -v kdump | head -n 1)

# then run
lsinitrd $INITRD | grep virtio

The expected output is similar to

-rw-r--r--   1 root     root        21004 Dec 18 04:52 usr/lib/modules/5.15.0-316.196.4.1.el8uek.x86_64/kernel/drivers/block/virtio_blk.ko.xz
-rw-r--r--   1 root     root        12424 Dec 18 04:52 usr/lib/modules/5.15.0-316.196.4.1.el8uek.x86_64/kernel/drivers/char/hw_random/virtio-rng.ko.xz
-rw-r--r--   1 root     root        27428 Dec 18 04:52 usr/lib/modules/5.15.0-316.196.4.1.el8uek.x86_64/kernel/drivers/char/virtio_console.ko.xz
drwxr-xr-x   2 root     root            0 Dec 18 04:52 usr/lib/modules/5.15.0-316.196.4.1.el8uek.x86_64/kernel/drivers/crypto/virtio
-rw-r--r--   1 root     root        20204 Dec 18 04:52 usr/lib/modules/5.15.0-316.196.4.1.el8uek.x86_64/kernel/drivers/crypto/virtio/virtio_crypto.ko.xz
-rw-r--r--   1 root     root        56012 Dec 18 04:52 usr/lib/modules/5.15.0-316.196.4.1.el8uek.x86_64/kernel/drivers/net/virtio_net.ko.xz
-rw-r--r--   1 root     root        17744 Dec 18 04:52 usr/lib/modules/5.15.0-316.196.4.1.el8uek.x86_64/kernel/drivers/scsi/virtio_scsi.ko.xz
drwxr-xr-x   2 root     root            0 Dec 18 04:52 usr/lib/modules/5.15.0-316.196.4.1.el8uek.x86_64/kernel/drivers/virtio
-rw-r--r--   1 root     root        16412 Dec 18 04:52 usr/lib/modules/5.15.0-316.196.4.1.el8uek.x86_64/kernel/drivers/virtio/virtio_pci.ko.xz
-rw-r--r--   1 root     root        12628 Dec 18 04:52 usr/lib/modules/5.15.0-316.196.4.1.el8uek.x86_64/kernel/drivers/virtio/virtio_pci_legacy_dev.ko.xz
-rw-r--r--   1 root     root        15600 Dec 18 04:52 usr/lib/modules/5.15.0-316.196.4.1.el8uek.x86_64/kernel/drivers/virtio/virtio_pci_modern_dev.ko.xz
-rw-r--r--   1 root     root        28344 Dec 18 04:52 usr/lib/modules/5.15.0-316.196.4.1.el8uek.x86_64/kernel/drivers/virtio/virtio_vdpa.ko.xz

Then, check if chrony and cloud-init are installed and configured as expected

rpm -qa | grep -E "chrony|cloud-init"

The expected output is similar to

chrony-4.5-2.0.2.el8_10.x86_64
cloud-init-23.4-7.0.2.el8_10.10.noarch

Ensure that the NoCloud data source is enabled within the chroot:

cat <<EOF | tee /etc/cloud/cloud.cfg.d/99_nocloud.cfg
datasource_list: [ NoCloud, ConfigDrive, None ]
EOF

Configure NTP, serial access and SSH

Configure the NTP server addresses with chrony

cat <<EOF > /etc/chrony.conf
server ntp1.org.internal iburst
server ntp2.org.internal iburst
server ntp3.org.internal iburst
server ntp4.org.internal iburst
server ntp5.org.internal iburst
server ntp6.org.internal iburst
EOF

Setup the initial serial console access

echo "root:gdchpassword" | chpasswd

Optional: Install the GDC agent package:

dnf install -y /tmp/gdc-guest-agent-<version>-x86_64.rpm
rm /tmp/gdc-guest-agent-<version>-x86_64.rpm

Optional: Manual SSH setup

If SSH is managed by the customer and the GDC agent is not installed, configure initial root SSH access as follows:

mkdir -p /root/.ssh
chmod 700 /root/.ssh
echo "[YOUR_PUBLIC_KEY]" > /root/.ssh/authorized_keys
chmod 600 /root/.ssh/authorized_keys

This step can be done also from serial console when the VM is running for the first time.

Unmount and import the image

After the offline modifications are complete, safely detach the virtual disk. Import the image to GDC using the --os=garden-linux flag. This flag is mandatory; it prevents the GDC translation engine from attempting automated configuration that causes unsupported OSes to fail.

First, exit from chroot

exit

Then ensure that all changes are written to the disk, unmount all bind mounts, deactivate the LVM volume group, and disconnect the block device:

sudo systemctl --root=/mnt/oracle${VERSION} enable guest-agent.service
sync
sudo umount -R /mnt/oracle${VERSION}
sudo vgchange -an vg_main
sudo qemu-nbd -d /dev/nbd0
sync

Last, log into GDC and import the custom image with garden linux os flag.

gdcloud auth login

gdcloud compute images import ol${VERSION}-custom \
  --project YOUR_PROJECT_NAME \
  --source-file=./oraclelinux${VERSION}.qcow2 \
  --os=garden-linux \
  --timeout=60m

Make sure to have all needed roles as in prerequisites.

Launch the VM with the custom image and connect

At this point you are already able to deploy a VM using the imported image. This can be done via UI or using gdcloud

gdcloud compute instances create ol$VERSION-test \
  --project YOUR_PROJECT_NAME \
  --image ol$VERSION-custom \
  --boot-disk-size 20GB \
  --machine-type n3-standard-2-gdc \
  --enable-external-access

Wait until the VM gets into running state, then you can:

  • Access Serial Console, in case you setup the credentials
  • SSH using customer-managed keys, in case you set them up
  • SSH using GDC-managed guest, in case GDC agent has been installed

Serial console access

gdcloud compute connect-to-serial-port ol$VERSION-test \
  --project YOUR_PROJECT_NAME

When prompted, insert the credentials set in the chroot configuration.

Customer-managed SSH

ssh -i my_key root@VM_IP

This will work with the root user: if you need more users to access, create users in the VM and upload their public keys as authorized keys.

GDC-managed SSH

gdcloud compute ssh ol$VERSION-test --project YOUR_PROJECT_NAME

This will work only if the GDC agent is properly configured and active, and the login user will be the same used when authenticating in GDC.

What you have now

At this stage, you have a VM image with the desired OS.

If you configured the cloud-init and installed the GDC agent, you can benefit from GDC-managed SSH and startup scripts. If you choose not to use GDC agent, you can manage the SSH using the serial console access or the root access.

However, a manual offline setup is not horizontally scalable. Since this base VM may be insufficient for scaling purposes as you may need to onboard the same users on multiple VMs, or have the same packages installed on multiple VMs, or may want to reduce the SSH keys management, or similar common use cases, it may be a good idea to install all you need in the created VM, and configure it properly once, and then use it as a model for the following VMs with same OS.

If this is the goal, then follow the next section to create a Golden Image.

Optional: Customize and create a golden image

Now, you can customize the VM as you prefer, based on your requirements. Connect to the VM, and transfer the needed rpm packages into it.

Once the VM has all the necessary configuration and packages, use it to create a new VM image to be used afterwards.

First, stop the VM: perform a clean shutdown to ensure complete disk consistency. You can do this from the VM terminal (sudo shutdown -h now) or using the GDC console.

Then, create the custom Golden Image using the GDC console or the Virtual Machine Manager API by capturing the stopped VM's boot disk (ol${VERSION}-test-boot-disk) into a new VirtualMachineImage:

kubectl --kubeconfig MANAGEMENT_API_SERVER \
  -n YOUR_PROJECT_NAME \
  apply -f - <<EOF
apiVersion: virtualmachine.gdc.goog/v1
kind: VirtualMachineImageImport
metadata:
  name: ol${VERSION}-golden-import
  namespace: YOUR_PROJECT_NAME
spec:
  source:
    diskRef:
      name: ol${VERSION}-test-boot-disk
  imageMetadata:
    name: ol${VERSION}-golden
    operatingSystem: garden-linux
    minimumDiskSize: 20G
EOF

This creates a new VirtualMachineImage named ol${VERSION}-golden to use when creating new VM instances. For example:

gdcloud compute instances create my-final-workload-vm \
  --project YOUR_PROJECT_NAME \
  --image ol$VERSION-golden \
  --boot-disk-size 50GB \
  --machine-type n3-standard-2-gdc \
  --enable-external-access