/frag-falcon

Firecracker VM management. Run Docker images as micro VMs

Primary LanguageJavaOtherNOASSERTION

frag-falcon

Firecracker VM management. Run Docker images as micro VMs.

Quick start

Grab the latest release here.

To run flc, you need:

  • A glibc based Linux distribution with virtualization support. Support for musl is being considered.
  • The tun and kvm (intel or amd) kernel modules loaded.
  • A Linux bridge VMs can attach to. The bridge needs to be attached to a router that can provide DHCP addresses.
  • A Linux kernel. You can grab this one we use for testing, or compile your own.
  • The latest firecracker release.

Make a directory to store kernels and virtual machines, and place at least one kernel in the kernels directory.

localhost:~/flc# tree
.
├── kernels
└── virtual-machines
3 directories, 0 files

Note: if you plan to run flc as a non-root user, you'll need to setcap on the flc binary to grant network management capabilities. See here for details.

Start flc:

flc \
  --api-host=0.0.0.0 \
  --vm-dir=./virtual-machines \
  --krn-dir=./kernels \
  --fc-path=/usr/local/bin/firecracker

Open a browser and go to http://<your-host>:7070

Use the integrated UI to create a test VM using your target Linux kernel and network bridge.

Screenshot 2024-08-19 at 10 37 48 PM

You can also create a VM with an API call too:

curl -i -X POST \
   -H "Content-Type:application/json" \
   -d \
'{
  "vm": {
    "tag": {
      "id": "new",
      "label": "test-vm-01",
      "description": "Test VM 01"
    },
    "image": { "source": "docker.io/hashicorp/http-echo:latest" },
    "config": {
      "bootsource": { "kernel_image_path": "/root/flc/kernels/vmlinux-6.1.98" },
      "machineconfig": { "vcpu_count": 1, "mem_size_mib": 512 }
    }
  },
  "network": { "dhcp": true, "brIf": "br0" },
  "rebuildInitRamFs": false
}' \
 'http://<your-host>:7070/api/v1/vm'

You will then have a list of VMs that you can start, stop, and inspect logs on.

Screenshot 2024-08-19 at 10 56 55 PM

The test VM I am running is using the hashicorp/http-echo:latest image. So I can curl it's IP address, just like any other machine in my internal network:

% curl http://172.16.4.107:5678
hello-world

Building/Development

Requires Gradle 8 or later.

Besides the usual gradle clean build, create a file with the following content at ~/.gsOrgConfig.json:

{
  "orgId": "vacco-oss",
  "orgConfigUrl": "https://vacco-oss.s3.us-east-2.amazonaws.com/vacco-oss.json"
}

Note: there's still a lot of tests with local paths I need to document/refactor.

Resources/credits