This how-to article explains how to integrate Firecracker microVMs with Apache CloudStack using the XaaS Extensions Framework. Firecracker provides fast-booting, secure, and lightweight microVMs ideal for edge and ephemeral workloads.

This guide covers the following steps:
• Prepare the Host: Set up a VLAN-aware bridge, install Firecracker and the Firecracker Agent, and enable TLS/auth.
• Build the Base Image: Extract a vmlinux kernel from Ubuntu and create a minimal Alpine Linux root image.
• Configure CloudStack: Install and register the firecracker.py extension, create a cluster, add hosts, and register the template.
• Deploy MicroVMs: Launch Instances from the CloudStack UI or API like any other hypervisor.
• Optional UI: Each Firecracker host exposes a web UI for monitoring microVMs.
• Advanced Features: VLAN trunking, OVS support, LVM-thin, monolithic kernels, and production-grade TLS/auth.

Reference: The firecracker-agent.json configuration provides flexible options for networking, storage, and security. TLS and PAM auth are strongly recommended for production.

Running Firecracker MicroVMs with Apache CloudStack

Apache CloudStack now supports lightweight microVM orchestration through its XaaS Extensions Framework, enabling operators to extend the platform with external hypervisors like Firecracker.

Firecracker is designed to run secure, fast-booting microVMs ideal for edge computing, CI/CD pipelines, short-lived workloads, and scenarios where startup speed and density are critical. By integrating Firecracker as an external orchestrator, CloudStack can provision and manage these microVMs using its existing API and UI, giving operators the same level of control they have with traditional hypervisors like KVM or VMware.

Preparing Firecracker Host (Ubuntu 24.04)

Each physical host must be configured with network bridging, the Firecracker binary, and the Firecracker Agent, which exposes a REST API and UI.

Configure a VLAN-Aware Bridge

Create a persistent bridge cloudbr1 with eth1 as the uplink.

This allows VLAN-tagged tap interfaces to be attached dynamically as microVMs are provisioned.

/etc/systemd/network/10-cloudbr1.netdev
[NetDev]
Name=cloudbr1
Kind=bridge

[Bridge]
VLANFiltering=yes
DefaultPVID=0
MulticastSnooping=no

/etc/systemd/network/10-cloudbr1.network
[Match]
Name=cloudbr1

[Network]
DHCP=no
/etc/systemd/network/20-eth1.network
[Match]
Name=eth1

[Network]
Bridge=cloudbr1

[Link]
RequiredForOnline=no

Reload and enable the service:

systemctl enable systemd-networkd --now
systemctl restart systemd-networkd
bridge vlan show
cat /sys/class/net/cloudbr1/bridge/vlan_filtering

You should see:

cloudbr1 vlan_filtering 1

This confirms VLAN filtering is active and the bridge is ready for tap interfaces.

Install Firecracker

Download the Firecracker binary and place it under /usr/local/bin:

FIRECRACKER_VERSION=1.13.1
ARCH=$(uname -m)

curl -LO https://github.com/firecracker-microvm/firecracker/releases/download/v${FIRECRACKER_VERSION}/firecracker-v${FIRECRACKER_VERSION}-${ARCH}.tgz
tar -xzf firecracker-v${FIRECRACKER_VERSION}-${ARCH}.tgz
install -m 0755 release-v${FIRECRACKER_VERSION}-${ARCH}/firecracker-v${FIRECRACKER_VERSION}-${ARCH} /usr/local/bin/firecracker

firecracker --version

Expected output:

Firecracker v1.13.1

Install the Firecracker Agent

The Firecracker Agent provides the communication layer between CloudStack and the microVM runtime.

FIRECRACKER_AGENT_VERSION=0.4.0-7
cd /tmp
wget https://github.com/msinhore/cloudstack-firecracker-extension/releases/download/v${FIRECRACKER_AGENT_VERSION}/firecracker-cloudstack-agent_${FIRECRACKER_AGENT_VERSION}_all.deb
apt install -y /tmp/firecracker-cloudstack-agent_${FIRECRACKER_AGENT_VERSION}_all.deb

Configure the Agent

/etc/cloudstack/firecracker-agent.json
{
"bind_host": "0.0.0.0",
"bind_port": 8443,
"defaults": {
"host": {
"firecracker_bin": "/usr/local/bin/firecracker",
"kernel_dir": "/var/lib/firecracker/kernel",
"image_dir": "/var/lib/firecracker/images",
"conf_dir": "/var/lib/firecracker/conf",
"run_dir": "/var/run/firecracker",
"log_dir": "/var/log/firecracker",
"payload_dir": "/var/lib/firecracker/payload"
},
"storage": {
"driver": "file",
"volume_dir": "/var/lib/firecracker/volumes"
},
"net": {
"driver": "linux-bridge-vlan",
"host_bridge": "cloudbr1",
"uplink": "eth1"
},
"console": {
"bind_host": "0.0.0.0",
"port_min": 5900,
"port_max": 5999,
"geometry": "1024x768x24",
"xterm_geometry": "127x45",
"font_family": "Monospace",
"font_size": 10,
"read_only": false
}
},
"security": {
"tls": {
"enabled": true,
"cert_file": "/etc/cloudstack/tls-cert/server.crt",
"key_file": "/etc/cloudstack/tls-cert/server.key",
"ca_file": "/etc/cloudstack/tls-cert/ca.crt",
"client_auth": "none"
}
},
"auth": {
"enabled": true,
"service": "firecracker-agent"
},
"ui": {
"enabled": true,
"session_timeout_seconds": 1800
}
}

Enable and start the service:

systemctl enable --now firecracker-cloudstack-agent.service

Check health:

journalctl -u firecracker-cloudstack-agent -f
curl -ks https://127.0.0.1:8443/healthz

If the service is running properly, the health check will return {“status”:”healthy”}.

Creating a Base Kernel and Root Image

To launch Firecracker microVMs from Apache CloudStack, you need two main components:
• A decompressed kernel image (vmlinux) compatible with Firecracker.
• A minimal root filesystem image (ext4) to serve as the base template.
This section covers both.

Extracting a Decompressed Kernel from Ubuntu

Firecracker doesn’t work with the default compressed vmlinuz shipped with Ubuntu.

The quickest way to get a compatible kernel is to extract vmlinux from your current kernel.

Install dependencies:

apt update
apt install -y linux-image-$(uname -r) binutils zstd

Download and install the extraction script:

curl -fSL https://raw.githubusercontent.com/torvalds/linux/master/scripts/extract-vmlinux \
-o /usr/local/bin/extract-vmlinux
chmod +x /usr/local/bin/extract-vmlinux

Extract the kernel:

mkdir -p /var/lib/firecracker/kernel
/usr/local/bin/extract-vmlinux /boot/vmlinuz-$(uname -r) | tee \
/var/lib/firecracker/kernel/vmlinux-ubuntu-$(uname -r).bin >/dev/null

Verify the result:

file /var/lib/firecracker/kernel/vmlinux-ubuntu-$(uname -r).bin
ls -lh /var/lib/firecracker/kernel/

Expected output:

ELF 64-bit LSB executable, x86-64, ...

Result: vmlinux-ubuntu-<version>.bin ready for Firecracker.

Tip: For production or latency-sensitive workloads, you can compile your own monolithic kernel to minimize boot time. For testing and lab use, the extracted kernel works perfectly.

Building a Minimal Alpine Linux Root Image

Using Alpine Linux as a base image keeps boot times low and the footprint minimal.

Download the Alpine Mini RootFS (choose the right architecture for your host):

cd /tmp
wget https://dl-cdn.alpinelinux.org/alpine/v3.22/releases/x86_64/alpine-minirootfs-3.22.1-x86_64.tar.gz
mkdir -p /tmp/alpine-rootfs
tar -xzf alpine-minirootfs-3.22.1-x86_64.tar.gz -C /tmp/alpine-rootfs

Customizing the RootFS

Chroot into the root filesystem and configure basic networking, SSH, and serial console support:

mount --bind /dev /tmp/alpine-rootfs/dev
mount --bind /proc /tmp/alpine-rootfs/proc
mount --bind /sys /tmp/alpine-rootfs/sys
chroot /tmp/alpine-rootfs /bin/sh

Inside the chroot:

echo nameserver 8.8.8.8 > /etc/resolv.conf
apk update
apk add --no-cache openrc ifupdown-ng dhcpcd openssh iproute2 bash

# Enable DHCP on eth0
cat > /etc/network/interfaces <<'EOF'
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp
EOF

# Enable essential services
rc-update add devfs boot
rc-update add procfs boot
rc-update add sysfs boot
rc-update add bootmisc boot
rc-update add networking default
rc-update add sshd default

# Serial console for Firecracker
echo 'ttyS0::respawn:/sbin/getty -L ttyS0 115200 vt100' >> /etc/inittab

# Devpts for SSH
mkdir -p /dev/pts
mount -t devpts devpts /dev/pts || true
grep -q '^devpts ' /etc/fstab || echo 'devpts /dev/pts devpts defaults 0 0' >> /etc/fstab

# Set root password (lab use only)
echo 'root:alpine' | chpasswd
sed -i 's/^#\?PermitRootLogin.*/PermitRootLogin yes/' /etc/ssh/sshd_config
sed -i 's/^#\?PasswordAuthentication.*/PasswordAuthentication yes/' /etc/ssh/sshd_config

# Auto-generate SSH keys on first boot
mkdir -p /etc/local.d
cat > /etc/local.d/10-ssh-keys.start <<'EOF'
#!/bin/sh
if ! ls /etc/ssh/ssh_host_* >/dev/null 2>&1; then
ssh-keygen -A
rc-service sshd restart
fi
EOF
chmod +x /etc/local.d/10-ssh-keys.start
rc-update add local default

# Cleanup
rm -rf /var/cache/apk/* /tmp/* /var/tmp/*
find /var/log -type f -exec truncate -s 0 {} \;
rm -f /etc/ssh/ssh_host_* /etc/machine-id /var/lib/dbus/machine-id
> /root/.ash_history || true
exit

Unmount:

umount /tmp/alpine-rootfs/dev/pts
umount /tmp/alpine-rootfs/dev
umount /tmp/alpine-rootfs/proc
umount /tmp/alpine-rootfs/sys

Creating the ext4 Image

Build a 512 MiB image (you can adjust the size as needed):

mkdir -p /var/lib/firecracker/images /mnt/fcroot
cd /var/lib/firecracker/images

dd if=/dev/zero of=alpine-3.22.1.ext4 bs=1M count=512
mkfs.ext4 -F alpine-3.22.1.ext4 -L rootfs

mount -o loop alpine-3.22.1.ext4 /mnt/fcroot
rsync -aHAX /tmp/alpine-rootfs/ /mnt/fcroot/
umount /mnt/fcroot

(Optional) Zero-fill free space to improve compression:

mount -o loop alpine-3.22.1.ext4 /mnt/fcroot
dd if=/dev/zero of=/mnt/fcroot/zero.fill bs=1M || true
rm -f /mnt/fcroot/zero.fill
umount /mnt/fcroot

Result:

• Kernel: /var/lib/firecracker/kernel/vmlinux-ubuntu-$(uname -r).bin
• Image: /var/lib/firecracker/images/alpine-3.22.1.ext4

These will be referenced later in the Template definition inside CloudStack.

Preparing the Management Server

The CloudStack Management Server acts as the control plane for provisioning and managing Firecracker microVMs.
Unlike traditional hypervisors, Firecracker is integrated through CloudStack’s XaaS Extensions Framework, using a lightweight Python extension (firecracker.py) that forwards Instance lifecycle requests to the Firecracker Agent running on each host.

Install Requirements

The Firecracker extension only requires the Python requests library.

For Ubuntu:

apt update
apt install -y python3-requests

For RHEL:

dnf update
dnf install -y python3-requests

Install the Firecracker Extension Script

Download and install the extension in the CloudStack extensions directory:

wget https://raw.githubusercontent.com/msinhore/cloudstack-firecracker-extension/refs/heads/main/firecracker.py
mkdir -p /usr/share/cloudstack-management/extensions/firecracker
install -m 0755 firecracker.py /usr/share/cloudstack-management/extensions/firecracker/firecracker.py

Note: The directory structure under /usr/share/cloudstack-management/extensions/ allows you to organize multiple orchestrators. firecracker is simply the name assigned to this extension.

Register the Extension in CloudStack

You can register the extension either from the CloudStack UI or using the API.

From the UI:

1. Go to Extensions
2. Click Create Extension
3. Fill in the following fields:
• Name: Firecracker
• Path: firecracker.py
• Type: Orchestrator
• Enabled: Yes

You will see the Firecracker Extension included in the Extension list:

Using the API (optional alternative):

cmk create extension name=Firecracker path=firecracker.py type=Orchestrator enabled=true

Once registered, CloudStack will be able to orchestrate Firecracker microVM lifecycle events through the extension.

Configuring Clusters, Hosts and Templates in CloudStack

With the extension registered, the next step is to configure a dedicated Cluster, add your Firecracker Hosts, and register a minimal Template so that CloudStack can launch microVM Instances.

Create a Firecracker Cluster

In Apache CloudStack, go to:

Infrastructure → Clusters → Add Cluster

Fill in the following fields:
• Cluster name: firecracker-cluster
• Hypervisor: External
• Extension: Firecracker

Click OK to create the cluster.

Add Firecracker Hosts

Each Firecracker Host runs the Firecracker Agent, which receives and executes Instance lifecycle commands.

In the UI:

Infrastructure → Hosts → Add Host

Fill in:

• Select a Zone, Pod and Cluster you created in the previous step
• Host name: (a friendly label, e.g., firecracker-host-01)
• Configuration Details: yes
• Key/Values:
o url: https://firecracker-hostname_or_ip-address
o port: 8443
o username: root
o password: host_password
o skip_ssl_verification: true (only if you don’t have a real certs)

You can add multiple hosts to scale horizontally. Each host can run dozens or hundreds of microVMs depending on available resources.

Add an Alpine Linux Template

A Template provides the base image and kernel that CloudStack uses to deploy Instances.
Go to:

Images →Templates → Register Template from URL

Fill in:
• URL: (just include a fake one, e.g. firecracker)
• Name: Alpine Linux 3.22.1 (Firecracker)
• Zone: (select the zone where your Firecracker cluster lives)
• Hypervisor: External
• Extension: Firecracker
• External Details: true

o im: alpine-3.22.1.ext4 (or the image you created)
o kernel: vmlinux-ubuntu-6.8.0-35-generic.bin (or the kernel you generate)
o boot_args: console=ttyS0 reboot=k panic=1 pci=off ip=dhcp (Optional)
• OS Type: Linux 6.x Kernel (64-bit)
• Template type: User
• Arch: Intel/AMD 64 bits (x86_64)
• Featured: true
• HVM: true
• Public: true

• The boot_args line enables serial console and DHCP on eth0, which matches the network configuration set inside the Alpine image.
• For URL, you can specify a placeholder (e.g., fake.local) since the image is already on the host.

Click OK to register the Template.

Launch a Firecracker MicroVM

You can now deploy your first Firecracker Instance now.

Instances → Add Instance → Select Zone
→ Select Template: Alpine Linux 3.22.1 (Firecracker)
→ Select Compute Offering
→ Select SSH Key (optional)
→ Review and Launch

When the deployment starts, CloudStack sends the payload to the Firecracker Agent, which creates and boots the microVM.
Once running, you can:
• Access the serial console from the host using tmux.
• Connect via SSH (if you configured SSH keys).
• Manage lifecycle operations (start, stop, destroy) from the UI.

Host UI (Optional)

Each Firecracker Host exposes a small web UI at:

https://<host-ip>:8443/

• Authenticate using the PAM credentials configured in the Firecracker host.
• View running microVMs and their configurations.

This UI is useful for view the MicroVMs configurations.

At this point:

• Your Firecracker hosts and clusters are fully integrated with CloudStack.
• You can deploy and manage microVMs directly from the UI.
• Templates reference local kernel and image files.

Advanced Features and Next Steps

Once the basic integration is up and running, you can extend your Firecracker + Apache CloudStack environment with more advanced features to match production requirements:

• VLAN Trunking — Attach VLAN-tagged interfaces dynamically for tenant isolation.
• OVS Support — Use ovs-vlan as the network driver for better control and integration with existing SDN setups.
• LVM-thin Storage — Replace file-based volumes with thin-provisioned logical volumes to improve performance and scalability.

• Monolithic Kernels — Reduce boot times by compiling a custom kernel with only the required drivers.
• Secure TLS & Auth — Deploy valid certificates and PAM-backed authentication for production-grade deployments.
• Multiple Hosts — Scale horizontally by adding more Firecracker hosts to the cluster.

Firecracker Agent – Configuration Reference

Below is a complete reference table of the firecracker-agent.json configuration file.

Section	Key	Type	Default	Description
root	bind_host	String	0.0.0.0	Interface where the Agent server listens.
root	bind_port	Integer	8080	TCP port for the agent’s HTTPS/HTTP listener.
defaults.host	firecracker_bin	string (path)	–	Absolute path to the Firecracker binary used for every VM start. Required.
defaults.host	kernel_dir	string (path)	/var/lib/firecracker/kernel	Directory that stores kernel images referenced by VM specs.
defaults.host	image_dir	string (path)	/var/lib/firecracker/images	Directory that holds base/root disk images. Used when building config defaults and for UI metadata.
defaults.host	conf_dir	string (path)	/var/lib/firecracker/conf	Location where generated Firecracker JSON configs are written. Must be writable by the agent.
defaults.host	run_dir	string (path)	/var/run/firecracker	Runtime socket/state directory (Firecracker API sockets, console FIFOs, network config cache).
defaults.host	payload_dir	string (path)	/var/lib/firecracker/payload	Where the agent persists incoming CloudStack payloads (create-spec-*.json) for auditing and recovery.
defaults.storage	driver	string enum	file	Storage backend to use (file, lvm, or lvmthin). Determines which driver the agent instantiates.
defaults.storage	volume_dir	string (path)	/var/lib/firecracker/volumes	Base directory for volume files (used by file driver) and as a staging path for other drivers. Required for file-based storage.
defaults.net	driver	string enum	linux-bridge-vlan	Networking backend (linux-bridge-vlan or ovs-vlan). Controls how tap devices and VLANs are provisioned.
defaults.net	host_bridge	string	cloudbr1	Bridge (Linux or OVS) where VM tap interfaces are attached.
defaults.net	uplink	string	–	Optional physical uplink or parent interface the networking backend should use.
security.tls	enabled	boolean	true	Enables HTTPS for the API/UI. When false, the agent serves plain HTTP.
security.tls	cert_file	string (path)	/etc/cloudstack/tls-cert/server.crt	PEM certificate presented by the agent. Required if TLS is enabled.
security.tls	key_file	string (path)	/etc/cloudstack/tls-cert/server.key	Private key matching cert_file.
security.tls	client_auth	string enum	none	TLS client-auth policy (none, optional, required).
auth	enabled	boolean	true	Toggles HTTP Basic authentication. When false, all endpoints are unauthenticated.
auth	service	string	firecracker-agent	PAM service name used to validate credentials when auth is enabled.
ui	enabled	boolean	true	Controls whether the compiled Vue dashboard is mounted under /ui and whether / redirects to it.
ui	session_timeout_seconds	integer	1800	Idle timeout the server advertises to the UI; once elapsed, the front end clears credentials and forces a new login.
logging (optional)	level	string enum	INFO	Overrides the agent logger level (DEBUG, INFO, WARNING, etc.). Additional handlers can be added manually in future.

For production, it’s strongly recommended to enable TLS with valid certificates and use PAM authentication with a dedicated service account.

Final Notes

• Firecracker integration provides a lightweight, fast-booting alternative to traditional hypervisors, fully orchestrated through CloudStack.
• It’s ideal for ephemeral workloads, edge computing, and environments where high density and low startup latency are critical.
• All lifecycle operations — create, start, stop, destroy — are executed through the same CloudStack API and UI you already use.