Using Firecracker in the Application Catalog

This guide presents internal technical information about using Firecracker with the application catalog.

This guide is a companion to the "Behind the Scenes with the Application Catalog". It details how to use Firecracker to run Unikraft applications. Firecracker is not yet fully support by KraftKit: building can be done with KraftKit, but running is to be done manually.

Note that Firecracker requires hardware virtualization support (KVM). Because of that, it can't be used in a virtual machine to run Unikraft applications. You have to run in a native Linux install.

Installing Firecracker#

To use Firecracker, you need to download a Firecracker release. For this guide we use the 1.4.0 release:

cd /tmp
wget https://github.com/firecracker-microvm/firecracker/releases/download/v1.4.0/firecracker-v1.4.0-x86_64.tgz
tar xzf firecracker-v1.4.0-x86_64.tgz

You can use the command below to make the firecracker-x86_64 executable available globally in the command line:

sudo cp release-v1.4.0-x86_64/firecracker-v1.4.0-x86_64 /usr/local/bin/firecracker-x86_64

Similar to the "Application Catalog: Behind the Scenes" guide, we will use two applications:

NGINX#

Use the steps below to build and run the NGINX binary-compatible application:

If not already configured, configure the BuildKit container:

docker run -d --name buildkitd --privileged moby/buildkit:latest
export KRAFTKIT_BUILDKIT_HOST=docker-container://buildkitd

Enter the NGINX binary-compatible directory:
```
cd catalog/library/nginx/1.25
```
Build the application for the Firecracker (fc) platform:
```
kraft build --plat fc --arch x86_64
```
The resulting kernel file is .unikraft/build/nginx_fc-x86_64.

As root (prefix with sudo if required), create a network tap interface:

ip tuntap add dev tap0 mode tap
ip address add 172.45.0.1/24 dev tap0
ip link set dev tap0 up

Create the Firecracker JSON configuration file fc-x86_64.json:

{
  "boot-source": {
    "kernel_image_path": ".unikraft/build/nginx_fc-x86_64",
    "boot_args": ".unikraft/build/nginx_fc-x86_64 netdev.ip=172.45.0.2/24:172.45.0.1 -- /usr/bin/nginx"
  },
  "drives": [],
  "machine-config": {
    "vcpu_count": 1,
    "mem_size_mib": 128,
    "smt": false,
    "track_dirty_pages": false
  },
  "cpu-config": null,
  "balloon": null,
  "network-interfaces": [
    {
      "iface_id": "net1",
      "guest_mac":  "06:00:ac:10:00:02",
      "host_dev_name": "tap0"
    }
  ],
  "vsock": null,
  "logger": {
    "log_path": "/tmp/firecracker.log",
    "level": "Debug",
    "show_level": true,
    "show_log_origin": true
  },
  "metrics": null,
  "mmds-config": null,
  "entropy": null
}

Run as root (prefix with sudo if required):

rm -f /tmp/firecracker.log
touch /tmp/firecracker.log
rm -f /tmp/firecracker.socket
firecracker-x86_64 --api-sock /tmp/firecracker.socket --config-file fc-x86_64.json

Query the unikernel instance:
```
curl http://172.45.0.2
```

To close the running Firecracker instance, kill the corresponding process. In another console, run as root (prefix with sudo if required):

pkill -f firecracker

HTTP Go Server#

Use the steps below to build and run the HTTP Go server as a binary-compatible application.

If not already configured, configure the BuildKit container:

docker run -d --name buildkitd --privileged moby/buildkit:latest
export KRAFTKIT_BUILDKIT_HOST=docker-container://buildkitd

Enter the HTTP Go server example directory:
```
cd catalog/examples/http-go1.21/
```

Pull the unikernel base image for the Firecracker (fc) platform:

kraft pkg pull -w base unikraft.org/base:latest --plat fc --arch x86_64

Use kraft run to trigger the build the root filesystem as an initrd:

sudo KRAFTKIT_BUILDKIT_HOST=docker-container://buildkitd kraft run --plat fc --arch x86_64 .

Note that this will cause an error similar to the one below, as KraftKit does not yet support running Firecracker:

E  [PUT /actions][400] createSyncActionBadRequest  &{FaultMessage:The requested operation is not supported after starting the microVM.}

However, the filesystem initird is created in .unikraft/build/initramfs-x86_64.cpio:

$ ls -lh .unikraft/build/initramfs-x86_64.cpio

-rw-r--r-- 1 razvand razvand 9.7M Jan 26 18:50 .unikraft/build/initramfs-x86_64.cpio

We will use the initrd for a manual run of Firecracker.