flintlock

module
v0.17.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: MPL-2.0

README

Flintlock - Create and manage the lifecycle of MicroVMs, backed by containerd.

GitHub Tests Go Reference GitHub release

What is flintlock?

Flintlock is a service for creating and managing the lifecycle of microVMs on a host machine. We support the Cloud Hypervisor and Firecracker VMMs.

The original use case for flintlock was to create microVMs on a bare-metal host where the microVMs will be used as nodes in a virtualized Kubernetes cluster. It is an essential part of Liquid Metal and can be orchestrated by:

  • Battery: a warm pool manager that keeps pools of pre-booted microVMs ready to be claimed.
  • Brigade: a distributed orchestrator that schedules microVMs across a fleet of flintlock hosts.
  • Cluster API Provider Microvm: a Cluster API provider that creates Kubernetes clusters with microVMs as the nodes.

However, it's useful for many other use cases where lightweight virtualization is required (e.g. isolated workloads, pipelines).

Features

Using API requests (via gRPC or HTTP):

  • Create, get, list and delete microVMs
  • Run microVMs with Firecracker or Cloud Hypervisor, chosen per microVM
  • Configure microVM metadata via cloud-init, ignition etc
  • Use OCI images for microVM volumes, kernel and initrd
  • Attach network interfaces using TAP devices (optionally on a Linux bridge) or macvtap devices (Cloud Hypervisor only), with DHCP or static IP addresses
  • Share host directories with a microVM using virtiofs (Cloud Hypervisor only)
  • Customise the CPU features presented to the guest
  • Talk to a guest agent in the microVM over a vsock device
  • Expose microVM metrics for collection by Prometheus

Documentation

See our getting started with flintlock tutorial.

Contributing

Contributions are welcome. Please read the CONTRIBUTING.md and our Code Of Conduct.

You can reach out to the maintainers and other contributors using the #liquidmetal channel on the CNCF slack.

Other interesting resources include:

Getting Help

If you have any questions about, feedback for or problems with flintlock:

Your feedback is always welcome!

Compatibility

The table below shows you which versions of Firecracker are compatible with Flintlock:

Flintlock Firecracker Cloud Hypervisor
v0.17.0 Official v1.16+ v54.0+
v0.16.x Official v1.16+ v48.0 - v53.0
v0.9.x Official v1.11+ v41.0
v0.8.x Official v1.10+ v41.0
v0.7.0 Official v1.10+ v41.0
v0.6.0 Official v1.0+ or v1.0.0-macvtap v26.0
v0.5.0 Official v1.0+ or v1.0.0-macvtap v26.0
v0.4.0 Official v1.0+ or v1.0.0-macvtap Not Supported
v0.3.0 Official v1.0+ or v1.0.0-macvtap Not Supported
<= v0.2.0 <= v0.25.2-macvtap Not Supported
<= v0.1.0-alpha.6 <= v0.25.2-macvtap Not Supported
v0.1.0-alpha.7 Do not use Not Supported
v0.1.0-alpha.8 <= v0.25.2-macvtap Not Supported

NOTE: we no longer support using the Weaveworks fork (with macvtap) of Firecracker. If you want macvtap then please use Cloud Hypervisor as the vm provider.

NOTE: Cloud Hypervisor before v48.0 does not start on some hosts with newer Intel CPUs, see #1265.

License

MPL-2.0 License

Acknowledgements

The biggest acknowledgement goes to @Weaveworks who where pioneers in the early Kubernetes world and produced some fantastic open source that lives on despite the demise of the company. A big thank you to the company and everyone that worked there. It was the engineers at Weaveworks that originally created Liquid Metal. RIP Weaveworks.

Directories

Path Synopsis
api module
client module
cmd
flintlock-overlay-init command
flintlock-overlay-init is the init of the initrd that flintlock boots an overlay root volume with.
flintlock-overlay-init is the init of the initrd that flintlock boots an overlay root volume with.
flintlockd command
core
infrastructure
mock
Package mock is a generated GoMock package.
Package mock is a generated GoMock package.
volume/overlay
Package overlay provisions the drives of an overlay volume: a read-only EROFS base shared by every microvm of one image, and a writable ext4 disk per microvm.
Package overlay provisions the drives of an overlay volume: a read-only EROFS base shared by every microvm of one image, and a writable ext4 disk per microvm.
volume/probe
Package probe checks at startup which volume modes a host accepts.
Package probe checks at startup which volume modes a host accepts.
vsockexec
Package vsockexec runs one exec request against a guest-agent's control channel, translating its framed protocol into a small typed event stream for the gRPC layer to relay.
Package vsockexec runs one exec request against a guest-agent's control channel, translating its framed protocol into a small typed event stream for the gRPC layer to relay.
vsocksshproxy
Package vsocksshproxy opens a raw byte tunnel to a guest-agent's ssh port, which itself proxies straight to the guest's local sshd - no framing, no agent-level auth.
Package vsocksshproxy opens a raw byte tunnel to a guest-agent's ssh port, which itself proxies straight to the guest's local sshd - no framing, no agent-level auth.
internal
command/provision
Package provision wires the flintlock-provision cobra commands to the business logic in internal/provision.
Package provision wires the flintlock-provision cobra commands to the business logic in internal/provision.
overlayinit
Package overlayinit implements the logic of flintlock-overlay-init, the init of the initrd that flintlock boots an overlay root volume with.
Package overlayinit implements the logic of flintlock-overlay-init, the init of the initrd that flintlock boots an overlay root volume with.
provision
Package provision contains the business logic used to bootstrap a host for running flintlock: installing Firecracker/Cloud Hypervisor/containerd/ flintlockd, setting up their systemd services, and configuring a devicemapper thinpool.
Package provision contains the business logic used to bootstrap a host for running flintlock: installing Firecracker/Cloud Hypervisor/containerd/ flintlockd, setting up their systemd services, and configuring a devicemapper thinpool.
pkg
log
ptr
reflink
Package reflink checks whether a directory is on a filesystem that can clone files with the FICLONE ioctl.
Package reflink checks whether a directory is on a filesystem that can clone files with the FICLONE ioctl.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL