image-builder

Create Firecracker VM images for use with firecracker-containerd

Debian root image

Overview

The image builder component of firecracker-containerd will build a microVM image including the necessary components to support container management inside the microVM. In particular, the firecracker-containerd runtime agent and runc binary will be installed in the image.

The image is generated as a read-only squashfs image. A read/write overlay layer is supported via the /sbin/overlay-init program, which should be used as init (e.g. by passing init=/sbin/overlay-init as a kernel boot parameter). By default, overlay-init allocates a tmpfs filesystem for use as the upper layer, but a block device can be provided via the overlay_root kernel parameter, e.g. overlay_root=vdc. This device should already contain a (possibly empty) ext4 filesystem. By using a block device, it is possible to preserve the filesystem state beyond the termination of the VM, and potentially re-use it for subsequent VM execution.

Generation

There are two alternatives for providing the build environment. You can perform the image build in Docker, in which case the only build-time dependency is that you can launch Docker container directly (i.e. without sudo, etc). To build an image in this configuration, run from the root of the firecracker-containerd package:

$ make image

Alternatively, to build outside a container, you'll need:

• To pre-build the agent binary, set appropriate permissions and place it under the rootfs builder directory.
  • For example, run make agent from the root of the firecracker-containerd package and copy agent/agent to tools/image-builder/files_ephemeral/usr/local/bin/agent.
• To pre-build the runc binary, set appropriate permissions and place it under the rootfs builder directory.
  • For example, run make -C _submodules/runc static from the root of the firecracker-containerd package and copy _submodules/runc/runc to tools/image-builder/files_ephemeral/usr/local/bin/runc
• debootstrap (Install via the package of the same name on Debian and Ubuntu)
• mksquashfs, available in the squashfs-tools package on Debian and Ubuntu.
• To run the image build process as root.

Then execute make rootfs.img from this directory (tools/image-builder)

Usage

The generated root filesystem contains all the components necessary for use with firecracker-containerd, including the runc and agent binaries.

You can tell the firecracker-containerd runtime component where to find the root filesystem image by setting the root_drive value in /etc/containerd/firecracker-runtime.json to the complete path to the generated image file.

In order to start the agent at VM startup, systemd should be instructed to boot to the firecracker.target via the kernel command line.

In order to use the root filesystem as a reusable "lower layer" for an overlay-based based filesystem, init=/sbin/overlay-init should be the final parameter passed on the kernel command line.

A complete command line, settable via the kernel_args setting in /etc/containerd/firecracker-runtime.json, is:

ro console=ttyS0 noapic reboot=k panic=1 pci=off nomodules systemd.journald.forward_to_console systemd.unit=firecracker.target init=/sbin/overlay-init

Security

In order to ensure sufficient entropy is consistently available within the VM, the rootfs is configured to start the haveged daemon during boot. More information on its method of operation and other details can be found in its FAQ. Users of the image created by this utility are encouraged to evaluate haveged against their security requirements before running any cryptographically-sensitive workloads inside their microVMs and containers.