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

- Image Preparation Unit: Offline modification of the
.qcow2disk viaqemu-nbdandchrooton a local workstation. - GDC Import Interface: Using the
gdcloudCLI with the--os=garden-linuxflag 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
VirtualMachineImageartifact to provide a scalable foundation for future deployments.
Before you begin
Ensure all prerequisites are met before beginning the offline image surgery:
- 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)
- Virtual Machine Project Admin (
- Workstation Requirements: A Linux development workstation connected to
the GDC environment network with the
qemu-utilspackage installed. - OS Compatibility (Virtio Drivers): The base image kernel must support
and include Virtio drivers (
virtio-netandvirtio-scsisupporting virtio-spec 1.0, plusvirtio_pciandvirtio_blk). Without these, the VM will fail to recognize its network card and hard drive on GDC's underlying KubeVirt hypervisor. - Base Image: A downloaded Oracle Linux 8 or 9
.qcow2cloud 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