This solution reference implementation outlines a customer-managed, shift-left strategy to manually import the SLES (SUSE Linux Enterprise Server) 16, 15SP7, and 15SP6 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 include
Virtio drivers (
virtio-netandvirtio-scsisupporting virtio-spec 1.0, plusvirtio_pciandvirtio_blk). Without these drivers, the VM fails to recognize its network interface and disk on the underlying KubeVirt hypervisor. - Base image: A downloaded SLES 16, 15SP6, or 15SP7
.qcow2cloud image, such as the GM-cloud evaluation image from the SUSE Linux Enterprise Server downloads page.
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 SLES 16,
15SP6 or 15SP7 base cloud image 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.
export VERSION=
# Load the network block device kernel module
sudo modprobe nbd
# Add 100Mb for agent and other packages
sudo qemu-img resize SLES${VERSION}.qcow2 +100M
# Connect the SLES 16, 15SP6 or 15SP7 image to the block device
sudo qemu-nbd -c /dev/nbd0 SLES${VERSION}.qcow2
# Identify the correct partition (usually partition 3)
sudo fdisk /dev/nbd0 -l
# Extend partition 3 to include the added 100Mb (or interactively via `sudo fdisk /dev/nbd0`:
# press d -> 3 -> n -> 3 -> accept default start/end sectors -> N to keep XFS signature -> w)
sudo parted -s /dev/nbd0 resizepart 3 100%
sudo partprobe /dev/nbd0
# Create a mount point and mount the identified partition
sudo mkdir -p /mnt/SLES${VERSION}
sudo mount /dev/nbd0p3 /mnt/SLES${VERSION}
# Resize the fs to recognize the added 100Mb
sudo xfs_growfs /mnt/SLES${VERSION}
# [OPTIONAL] Move the GDC agent rpm package to the mount path
sudo cp gdc-guest-agent-VERSION-x86_64.rpm /mnt/SLES${VERSION}/tmp/
# Enter the chroot environment to act as the root user inside the image
sudo chroot /mnt/SLES${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/initrd-*)
# then run
lsinitrd $INITRD | grep virtio
The expected output is similar to
virtiofs
-rw-r--r-- 1 root root 21127 Jul 16 2025 usr/lib/modules/6.12.0-160000.5-default/kernel/drivers/block/virtio_blk.ko.zst
-rw-r--r-- 1 root root 5479 Jul 16 2025 usr/lib/modules/6.12.0-160000.5-default/kernel/drivers/char/hw_random/virtio-rng.ko.zst
drwxr-xr-x 2 root root 0 Aug 12 2025 usr/lib/modules/6.12.0-160000.5-default/kernel/drivers/crypto/virtio
-rw-r--r-- 1 root root 26014 Jul 16 2025 usr/lib/modules/6.12.0-160000.5-default/kernel/drivers/crypto/virtio/virtio_crypto.ko.zst
-rw-r--r-- 1 root root 73267 Jul 16 2025 usr/lib/modules/6.12.0-160000.5-default/kernel/drivers/net/virtio_net.ko.zst
-rw-r--r-- 1 root root 20794 Jul 16 2025 usr/lib/modules/6.12.0-160000.5-default/kernel/drivers/scsi/virtio_scsi.ko.zst
drwxr-xr-x 2 root root 0 Aug 12 2025 usr/lib/modules/6.12.0-160000.5-default/kernel/drivers/virtio
-rw-r--r-- 1 root root 27515 Jul 16 2025 usr/lib/modules/6.12.0-160000.5-default/kernel/drivers/virtio/virtio_mem.ko.zst
-rw-r--r-- 1 root root 10997 Jul 16 2025 usr/lib/modules/6.12.0-160000.5-default/kernel/drivers/virtio/virtio_mmio.ko.zst
-rw-r--r-- 1 root root 10236 Jul 16 2025 usr/lib/modules/6.12.0-160000.5-default/kernel/drivers/virtio/virtio_vdpa.ko.zst
-rw-r--r-- 1 root root 26566 Jul 16 2025 usr/lib/modules/6.12.0-160000.5-default/kernel/fs/fuse/virtiofs.ko.zst
-rw-r--r-- 1 root root 12998 Jul 16 2025 usr/lib/modules/6.12.0-160000.5-default/kernel/net/9p/9pnet_virtio.ko.zst
-rwxr-xr-x 1 root root 204 Aug 12 2025 var/lib/dracut/hooks/cmdline/95-parse-virtiofs.sh
-rwxr-xr-x 1 root root 627 Aug 12 2025 var/lib/dracut/hooks/pre-mount/99-mount-virtiofs.sh
Then, check if chrony and cloud-init are installed and configured as expected
rpm -q chrony
rpm -q cloud-init
The expected output is similar to
chrony-4.6.1-160000.2.2.x86_64
cloud-init-25.1.3-160000.1.2.x86_64
Ensure that the nocloud datasource is not disabled. You can run the following
command within the chroot to ensure the nocloud datasource is enabled:
cat <<EOF | sudo 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:
zypper --no-gpg-checks install -y /tmp/gdc-guest-agent-VERSION-x86_64.rpm
rm /tmp/gdc-guest-agent-VERSION-x86_64.rpm
If zypper install does not work because it is an old package, add the
--oldpackage flag to the command.
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 and unmount.
sudo systemctl --root=/mnt/SLES${VERSION} enable guest-agent.service
sudo umount -l /mnt/SLES${VERSION}
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 sles-${VERSION}-custom \
--project YOUR_PROJECT_NAME \
--source-file=./SLES${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 sles-test-vm \
--project YOUR_PROJECT_NAME \
--image sles-$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 sles-test-vm \
--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 sles-test-vm --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 (sles compatible) 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 (sles-test-vm-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: sles-${VERSION}-golden-import
namespace: YOUR_PROJECT_NAME
spec:
source:
diskRef:
name: sles-test-vm-boot-disk
imageMetadata:
name: sles-${VERSION}-golden
operatingSystem: garden-linux
minimumDiskSize: 20G
EOF
This creates a new VirtualMachineImage named sles-${VERSION}-golden to use
when creating new VM instances. For example:
gdcloud compute instances create my-final-workload-vm \
--project YOUR_PROJECT_NAME \
--image sles-${VERSION}-golden \
--boot-disk-size 20GB \
--machine-type n3-standard-2-gdc \
--enable-external-access