chainguard-server-hypervisor-gcp

packaged by Chainguard

Chainguard Container for chainguard-server-hypervisor-gcp

Chainguard Server Hypervisor bootc OS image for GCE (amd64 + arm64): a minimal, immutable host for Chainguard MicroVMs, including GCE bare metal.

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/chainguard-server-hypervisor-gcp:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

The chainguard-server-hypervisor-gcp container image is a Chainguard-native bootc OS image, not a repackaged application. It is a minimal, immutable, bootc-managed host OS whose only job is to run Chainguard MicroVMs (mono/microvm) — conceptually VMware ESXi, not a general-purpose server. It ships as the root filesystem behind a GCE image and is delivered to running instances via atomic bootc upgrade on top of composefs. It is the GCP sibling of chainguard-server-hypervisor-aws, and sits beside the chainguard-desktop-workstation-{rpi,qemu} and chainguard-server-workstation-gcp family: same Vendor/Class axes, Hypervisor form factor, GCE hardware target.

The build is split into three stages, each with a single job:

1. The package (enterprise-packages/chainguard-server-hypervisor.yaml): the only stage that ships file content — the host contract (udev rule for /dev/kvm, tun modules-load, microvm sysusers, state/scratch tmpfiles, the microvm-manager@ privilege template) plus the -gcp subpackage's Firecracker dependency and GCE Local SSD scratch provisioning. The package itself is generic, with one subpackage per hardware platform.
2. This image (containers/images/chainguard-server-hypervisor-gcp/): composition only — package list, kernel selection, composefs paths and annotations. Note that unlike the -aws sibling it does not enable the scratch unit with a paths: symlink; the -gcp subpackage's systemd preset does that, because preset creates both enablement links where a paths: entry creates only the one it names.
3. The disk/GCE image (wolfi-vm/configs/gcp-server-hypervisor): partitioning, filesystems, bootloader, and GCE image registration. It installs from this published image via the wolfi-vm container-installer (bootc install --target-imgref), so install and upgrade share one source of truth.

Scope of this image is the container: the composefs root a GCE instance runs from once bootstrapped. Key properties:

• Architecture: amd64 and arm64. Both are real targets. GCE has one arm64 bare-metal shape, c4a-highmem-96-metal (Axion), and it is the strategically important one — see the Secure Boot note below.
• Init: /sbin/init (systemd).
• Boot chain: GCE UEFI → systemd-boot → Linux (via linux-gcp-6.18-bootc-boot-installed). GCE has no legacy-BIOS path at all, on any shape including bare metal, so this image needs none of the GRUB/blscfg machinery the AWS x86 sibling carries — that exists solely because every x86 EC2 .metal type reports SupportedBootModes: [legacy-bios].
• Root filesystem: composefs-backed ostree deployment on ext4, with fs-verity enforced. bootc treats only ext4 and btrfs as fs-verity-capable and silently installs with verity disabled on anything else, so wolfi-vm's builder-bootc installs with --filesystem=ext4 and then verifies the built disk's composefs= karg carries no ? prefix.
• Container annotations: containers.bootc="1" (required by the bootc container linter), dev.chainguard.vm.bootable="1" (the wolfi-vm container-installer gates on this before installing a pulled image), and dev.chainguard.vm.secureboot="1" (makes it enroll Secure Boot certs on the ESP).

Bare metal on GCE

Two platform facts shape this image, and neither has an AWS analogue:

• BARE_METAL_LINUX_COMPATIBLE and IDPF. GCE bare-metal instances use the Intel IDPF network driver and do not offer gVNIC, so only OS images that support IDPF can boot there. The linux-gcp-6.18 kernel enables CONFIG_IDPF=m (config-gcp-generic), which is what makes this image bootable on metal at all. The corresponding BARE_METAL_LINUX_COMPATIBLE guest OS feature is set at GCE image registration time, in the wolfi-vm publish stage — not here.
• Secure Boot is available on arm64 metal, and only there. GCE bare metal forfeits vTPM and Shielded VM on every machine series except C4A and A4X Max. So c4a-highmem-96-metal can enforce the Secure Boot certs this image asks the installer to enroll, which makes it the only bare-metal target in the Chainguard-on-Chainguard fleet with a verified boot chain below composefs. On the x86 metal shapes (C3/C4/C4D/X4/Z3) the enrolled certs are simply not enforced by firmware — harmless, and one image still serves every shape.

Scratch storage

chainguard-hypervisor-scratch-gcp.service provisions /var/lib/microvm-scratch from one of two backends, tried in the order given by SCRATCH_ORDER:

Hyperdisk is tried first by default, for three reasons: it is the only scratch that exists on most GCE metal shapes (c3-*-metal, c4d-*-metal, x4-*-metal and c4a-highmem-96-metal have no Local SSD at all); it survives instance stop/start, so the scratch filesystem is reclaimed by label rather than rebuilt; and it only exists because an operator deliberately attached it, which is a stronger signal of intent than a device that came with the shape. Flip to local-ssd hyperdisk on a shape where you have both and want the directly-attached NVMe.

Attach a scratch Hyperdisk like this — the device name is what matters, not the disk resource name:

gcloud compute instances attach-disk INSTANCE \
  --disk=my-scratch-disk --device-name=microvm-scratch

That name is the entire safety contract for this backend. The boot volume is also a Hyperdisk and is indistinguishable from a data Hyperdisk by device model, so "some blank nvme_card-pd" is not a safe selector and the provisioner never uses one; only a disk named for the purpose is eligible. Naming persistent-disk-0 — the boot disk's default device name — is refused outright.

Configure it in /etc/chainguard-server-hypervisor/scratch-gcp.conf; shipped defaults are documented in /usr/lib/chainguard-server-hypervisor/scratch-gcp.conf. Setting SCRATCH_ORDER="" disables provisioning entirely.

If neither backend yields a device the service is a clean no-op and /var/lib/microvm-scratch stays on the boot volume. That is a supported configuration, not a degraded one — and with no scratch disk attached to a c3-*-metal or c4a-highmem-96-metal host, it is the default one.

What is in the Image

Hypervisor-appliance profile — the shared bootc server base without the ~105-package developer toolset the workstation siblings carry:

• Kernel + boot chain: linux-gcp-6.18-bootc-boot-installed (GCE host kernel with the composefs-aware initramfs and CONFIG_IDPF for bare metal), systemd-boot + systemd-boot-installed, and systemd-repart-rootfs-ext4 (grows the root ext4 to fill the GCE boot disk on first boot).
• Bootc runtime: bootc-system — pulls bootc-binary, bootc-systemd-units, podman, and the systemd/boot deps that make the installed image an actual bootc-managed system.
• Hypervisor payload: chainguard-server-hypervisor + chainguard-server-hypervisor-gcp (host contract + GCE Local SSD scratch provisioning), firecracker (primary VMM), qemu (mature fallback VMM — the bare metapackage, so each arch gets its native emulator), and the baked guest kernels linux-firecracker-6.18 and linux-qemu-melange (guest kernels move atomically with bootc upgrade; no runtime credential or egress needed).
• GCE access tail: google-guest-agent, google-guest-config, google-compute-engine-oslogin, chrony-gcp, OpenSSH client and server. Shorter than the AWS sibling's: there is no cloud-init here, because google-guest-agent owns SSH-key metadata and account creation on GCE.
• SELinux: installed (libselinux, libsemanage, libsepol, policycoreutils, selinux-policy) but disabled at cmdline/config for now.
• Base userspace: the same shared server base as the AWS sibling (systemd cluster, udev, shadow, sudo-rs, coreutils/findutils/grep/sed, e2fsprogs/xfsprogs/dosfstools/parted, chainguard-baselayout, wolfi-baselayout, ca-certificates, ...).

There is deliberately no developer toolset (no docker, no go, no editors beyond vim, no cloud SDKs) and no apk-tools — this is an appliance managed through bootc upgrade and the GCE API.

Getting Started

This image is not run directly with docker run — it is the root filesystem for a bootc-managed GCE instance. Its declared entrypoint is /sbin/init (systemd PID 1), which requires cgroup delegation, a writable /sys/fs/cgroup, and a fully owned PID namespace: none of which a plain unprivileged container provides, so there is no meaningful boot test under docker. A real boot happens on a GCE instance whose boot disk was staged from this image — so the way to get started with it is to launch one.

A GCE image is built from this container and published into a Chainguard project. It is not a public image: access is granted per-customer. Contact Chainguard to request access.

1. Launch an instance

The published GCE images are referenced as image families, so you always get the newest build:

Substitute the Chainguard project you have been given access to for --image-project below.

Dev loop — a virtualized instance. Cheap, and exercises everything except the metal-specific hardware paths. --enable-nested-virtualization is what gives the hypervisor a /dev/kvm to work with on a virtualized shape:

gcloud compute instances create my-hypervisor \
  --project=YOUR_PROJECT --zone=us-central1-a \
  --image-family=chainguard-server-hypervisor-amd64 \
  --image-project=CHAINGUARD_IMAGE_PROJECT \
  --machine-type=n2-standard-8 \
  --enable-nested-virtualization \
  --boot-disk-type=pd-balanced --boot-disk-size=100GB

Bare metal — the production posture. Metal instances cannot live migrate, so --maintenance-policy=TERMINATE is mandatory rather than advisory, and C3/C4/C4A metal boot disks must be Hyperdisk:

gcloud compute instances create my-hypervisor-metal \
  --project=YOUR_PROJECT --zone=us-central1-a \
  --image-family=chainguard-server-hypervisor-amd64 \
  --image-project=CHAINGUARD_IMAGE_PROJECT \
  --machine-type=c3-standard-192-metal \
  --maintenance-policy=TERMINATE \
  --boot-disk-type=hyperdisk-balanced --boot-disk-size=200GB

For arm64 metal use --machine-type=c4a-highmem-96-metal with the -arm64 image family. No nested-virtualization flag on metal — the hardware is the hypervisor.

The published image declares BARE_METAL_LINUX_COMPATIBLE, which GCE requires before it will boot an image on a *-metal shape, and the metal kernel arguments ship inside the image at /usr/lib/bootc/kargs.d/20-gce-metal.toml so they survive an upgrade rather than being frozen into a bootloader config.

Access the instance with OS Login or SSH as usual.

2. Confirm it came up

bootc status                      # the deployment and its origin
systemctl is-system-running       # expect: running
ls -l /dev/kvm                    # the hypervisor's reason for existing
findmnt -no OPTIONS /             # expect ro,...,verity=require

verity=require is the one worth checking: the root is an fs-verity-backed composefs, and that flag is the difference between verification being enforced and merely attempted.

3. Run MicroVMs

The chainguard-server-hypervisor host contract provides /dev/kvm group access, tun, the unprivileged microvm user, and the microvm-manager@ privilege template. chainguard-hypervisor-scratch-gcp.service (enabled by the package's preset) provisions /var/lib/microvm-scratch on an attached Hyperdisk, or on Local SSD where the shape has it.

Firecracker is the primary VMM and qemu the fallback; guest kernels ship in the image, so starting a guest needs no registry credential and no egress.

4. Upgrade in place

New digests of this container become new deployments on the running host:

sudo bootc upgrade --apply

No re-imaging, and bootc rollback returns to the previous deployment if an upgrade misbehaves. This is the steady state — step 1 happens once per host.

Inspecting the image without booting it

docker pull cgr.dev/ORGANIZATION/chainguard-server-hypervisor-gcp:latest
docker run --rm -it --entrypoint /bin/sh \
  cgr.dev/ORGANIZATION/chainguard-server-hypervisor-gcp:latest

Documentation and Resources

• bootc project
• composefs
• Firecracker
• GCE bare metal instances
• GCE guest OS features

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.