flintlock

Flintlock is a service designed to create and manage the lifecycle of microVMs on a host machine. It is backed by containerd and currently supports [Firecracker][firecracker], with plans to support [Cloud Hypervisor][ch] in the future.

Its primary use case is providing microVM nodes for virtualized Kubernetes clusters on bare-metal hosts. It serves as a core component of [Liquid Metal][liquid-metal] and is intended to be driven by the [Cluster API Provider Microvm][capmvm].

Flintlock provides management capabilities for microVMs via gRPC or HTTP API requests. Key features include:

• Lifecycle Management: Create, update, and delete microVMs (currently using Firecracker).
• State Control: Start, stop, and pause microVMs.
• Configuration: Configure microVM metadata using tools like cloud-init or ignition.
• Image Support: Use OCI images for microVM volumes, kernels, and initrd.
• Networking (Coming Soon): Support for CNI to configure microVM networks.

Flintlock generates network device names on the host using a random value rather than deriving them from the MicroVM name or Namespace. This approach avoids the 15-byte character limit imposed by the Linux kernel for network interface names.

To minimize collisions on hosts with many network devices, Flintlock attempts to generate a unique name up to 5 times if the initial name is already in use.

The MicroVMStatus object provides the runtime state of a MicroVM.

MicroVMState values:

• PENDING (0)
• CREATED (1)
• FAILED (2)
• DELETING (3)

Status Details:

• vsock_path: The host unix-domain socket path for the guest-agent. This is only populated if allow_guest_agent was set to true in the spec. Use this with the vsock-connect host helper.
• volumes: Status of attached volumes, including their Mount information.
• network_interfaces: Status of interfaces, including host_device_name (tuntap or macvtap), index, and mac_address.

Flintlock does not support in-place updates for running MicroVMs. If you need to change the MicroVM specification (e.g., modifying resources, network, or storage), you must recreate the MicroVM rather than patching an existing one.

This design decision is driven by the limitations of the Firecracker MicroVM provider, which restricts most operations (such as volume hot-swapping or network configuration) once a MicroVM has started. Consequently, any changes to the MicroVM spec will result in the destruction of the old instance and the creation of a new one.

If the gRPC API has changed, you must update the documentation hosted on buf.build by pushing a new tag.

1. Login: Use buf registry login. The username is liquidmetal-dev and the key is a generated token.
2. Push Tag: Use buf push --tag "${RELEASE_VERSION}" to update the registry.

Note: If you receive the message The latest commit has the same content; not creating a new commit., it indicates no API changes were detected and no update was necessary.

If you need to build the custom Firecracker binaries yourself, you can use the feature/macvtap branch. This build process uses a Docker container, so a local Rust installation is not required.

After building, copy the firecracker and jailer binaries to a directory in your $PATH (e.g., ~/local/bin).

git clone https://github.com/liquidmetal-dev/firecracker.git
git fetch origin feature/macvtap
git checkout -b feature/macvtap origin/feature/macvtap

# This will build it in a docker container, no rust installation required.
tools/devtool build

# Any directories on $PATH.
TARGET=~/local/bin
toolbox=$(uname -m)-unknown-linux-musl

cp build/cargo_target/${toolbox}/debug/{firecracker,jailer} ${TARGET}

For a minimal experience, you can use grpcurl combined with the provided ./hack/scripts/send.sh script to send payloads to the Flintlock server.

./hack/scripts/send.sh \
  --method CreateMicroVM

To provide networking for MicroVMs, create a network configuration XML file. You can adjust the IP range and bridge name to avoid conflicts with existing networks.

After creating the XML file, use virsh to define and start the network. You can also enable autostart so the network persists across reboots.

BRIDGE=flbr0
cat << EOF >flintlock-net.xml
<network>
  <name>flintlock</name>
  <forward mode='nat'>
    <nat>
      <port start='1024' end='65535'/>
    </nat>
  </forward>
  <bridge name="$BRIDGE" stp='on' delay='0'/>
  <ip address='192.168.100.1' netmask='255.255.255.0'>
    <dhcp>
      <range start='192.168.100.10' end='192.168.100.254'/>
    </dhcp>
  </ip>
</network>
EOF

sudo virsh net-define flintlock.xml
sudo virsh net-start flintlock
sudo virsh net-autostart flintlock

To use the BloomRPC GUI to test Flintlock endpoints, you must import the service definitions:

1. Click Import Paths on the left-hand menu bar and add the absolute path to the <repo-root>/api directory.
2. Click the import + button and select flintlock/api/services/microvm/v1alpha1/microvms.proto.

Once imported, all available endpoints will appear in a tree view.