chainguard-server-hypervisor-aws

packaged by Chainguard

Chainguard Container for chainguard-server-hypervisor-aws

Chainguard Server Hypervisor bootc OS image for AWS EC2 (amd64 and arm64): a minimal, immutable host for Chainguard MicroVMs.

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-aws: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-aws 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 an EC2 AMI and is delivered to running instances via atomic bootc upgrade on top of composefs. It sits beside the chainguard-desktop-workstation-{rpi,qemu} and chainguard-server-workstation-gcp family: same Vendor/Class axes, Hypervisor form factor, AWS (Nitro) 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 -aws subpackage's Firecracker dependency and EC2 instance-store scratch provisioning. The package itself is generic, with one subpackage per hardware platform. Units ship disabled.
2. This image (containers/images/chainguard-server-hypervisor-aws/): composition only — package list, kernel selection, composefs paths, annotations, and unit enablement via paths: symlinks (the chainguard-hypervisor-scratch-aws.service wants-link).
3. The disk/AMI (wolfi-vm/configs/aws-server-hypervisor): partitioning, filesystems, bootloader, and AMI 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 an EC2 instance runs from once bootstrapped. Key properties:

• Architecture: amd64 (c7i/m7i and x86 *.metal) and arm64 (Graviton metal: c7g.metal, m7g.metal). Graviton needed no bootloader work because it is UEFI and exposes KVM natively.
• Init: /sbin/init (systemd).
• Boot chain: EC2 UEFI (Nitro) → systemd-boot → Linux (via linux-aws-6.18-bootc-boot-installed). The -bootc kernel variant ships an initramfs with composefs support and a bootctl-identifiable vmlinuz, both required by bootc install.
• Root filesystem: composefs-backed ostree deployment. The image declares /sysroot, /sysroot/ostree, and /ostree so bootc install --composefs-backend can populate them at bootstrap time.
• Container annotations: containers.bootc="1" (required by the bootc container linter) and dev.chainguard.vm.bootable="1" (the wolfi-vm container-installer gates on this before installing a pulled image).

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-aws-6.18-bootc-boot-installed (EC2/Nitro host kernel with the composefs-aware initramfs), systemd-boot + systemd-boot-installed, and systemd-repart-rootfs-xfs (grows the root xfs to fill the EBS boot volume 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-aws (host contract + EC2 instance-store scratch provisioning), firecracker (primary VMM), qemu (mature fallback VMM; execs qemu-system-x86_64 on amd64 and qemu-system-aarch64 on Graviton), 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).
• EC2 access tail (full aws-base operability stack for bring-up; trimmed toward SSM-only later): amazon-ssm-agent, ec2-instance-connect, cloud-init, ec2-user, amazon-ec2-net-utils, amazon-ec2-utils, chrony-aws, aws-configs, cloud-ssh-keys-fetcher, OpenSSH client and server.
• SELinux: installed (libselinux, libsemanage, libsepol, policycoreutils, selinux-policy) but disabled at cmdline/config for now.
• Base userspace: the same shared server base as the GCP sibling (systemd cluster, udev, shadow, sudo-rs, coreutils/findutils/grep/sed, xfsprogs/e2fsprogs/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 EC2 API.

Getting Started

This image is not run directly with docker run — it is the root filesystem for a bootc-managed EC2 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 an EC2 instance whose boot volume was staged from this image — so the way to get started with it is to launch one.

An AMI is registered from this container and shared with named AWS accounts. It is not a public AMI: access is granted per-account. Contact Chainguard to request access.

1. Find the AMI

The published AMI is named chainguard-server-hypervisor-<arch>-<timestamp> and registered in us-east-1. It is not a public AMI; it is shared with named accounts.

That has a consequence worth stating plainly, because the failure is silent: an AMI that is not shared with your account is invisible to describe-images, and the response is identical to one for an AMI that does not exist. An empty result therefore tells you nothing about which of the two you are looking at — contact Chainguard rather than guessing.

aws ec2 describe-images --region us-east-1 \
  --filters 'Name=name,Values=chainguard-server-hypervisor-x86_64-*' \
  --query 'reverse(sort_by(Images,&CreationDate))[0].ImageId' --output text

Swap x86_64 for arm64 on Graviton. The name is distinctive enough to match on its own; if you would rather pin the query to the publishing account with --owners, Chainguard can give you that ID.

2. Launch an instance

Dev loop — a virtualized instance. NestedVirtualization=enabled is what gives the hypervisor a /dev/kvm on a virtualized shape. It is Intel-virtualized-only, so the instance type matters; c7i.large is known good:

aws ec2 run-instances --region us-east-1 \
  --image-id ami-XXXXXXXX \
  --instance-type c7i.large \
  --cpu-options NestedVirtualization=enabled \
  --metadata-options HttpTokens=required \
  --block-device-mappings 'DeviceName=/dev/xvda,Ebs={VolumeSize=100}' \
  --key-name YOUR_KEY

Bare metal — the production posture. Metal instances provide KVM directly, so there is no nested-virtualization option to set (and passing one fails):

aws ec2 run-instances --region us-east-1 \
  --image-id ami-XXXXXXXX \
  --instance-type m5zn.metal \
  --metadata-options HttpTokens=required \
  --block-device-mappings 'DeviceName=/dev/xvda,Ebs={VolumeSize=200}' \
  --key-name YOUR_KEY

On Graviton use m7g.metal with the arm64 AMI. Metal instances take 8–15 minutes to reach SSH — considerably longer than a VM — so a connection failure in the first few minutes is expected rather than a fault.

Two registration details that shape what boots where. The x86_64 AMI is registered uefi-preferred, not uefi, so one AMI serves both classes: every x86 EC2 .metal type reports SupportedBootModes: [legacy-bios] while systemd-boot is UEFI-only, so metal falls back to the GRUB installed alongside it. The arm64 AMI is plain uefi, because Graviton metal boots UEFI. Neither registers tpm_support — NitroTPM does not work on .metal instances, and registering it would make the AMI unbootable there.

Access via SSM (amazon-ssm-agent ships in the image), EC2 Instance Connect, or SSH.

3. 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.

On x86 metal, note that the legacy-BIOS boot path has no Secure Boot, so there is no verified boot chain below composefs there. That gap is deliberate and documented; the UEFI path on virtualized instances does enroll Secure Boot keys.

4. 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-aws.service provisions /var/lib/microvm-scratch on instance-store NVMe when 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.

5. 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 — steps 1 and 2 happen once per host.

Inspecting the image without booting it

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

Documentation and Resources

• bootc project
• composefs
• Firecracker

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.