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. Typical lifecycle:

1. Bootstrap (one-off): build the AMI with the companion wolfi-vm/configs/aws-server-hypervisor pipeline, which pulls this published image and runs bootc install to-disk --target-imgref against it via the container-installer, then registers the resulting disk through awspub.

2. Boot on EC2: launch a c7i/m7i instance with --cpu-options NestedVirtualization=enabled (dev loop) or a *.metal instance (production posture). The instance boots into the composefs deployment of this image; access via SSM (amazon-ssm-agent), EC2 Instance Connect, or SSH.

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-aws.service (enabled by this image) provisions /var/lib/microvm-scratch on instance-store NVMe when present.

4. Upgrade (ongoing, on the running instance): pick up new digests of this image with

   sudo bootc upgrade --apply

   No re-imaging of the boot volume is required after the initial bootstrap.

To inspect the image contents from a workstation you can still pull and mount it read-only:

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.