spark#

An extremely small Firecracker MicroVM management tool.

Basic Usage#

To get started with spark you'll first need to install firecracker.

$ spark system install
$ spark system doctor

After spark has installed and setup firecracker, you can add a rootfs and kernel.

$ spark kernel add linux:6.18.28 kata/kernels/vmlinuz-6.18.28-124
$ spark rootfs add alpine:3.24.0 alpine/images/rootfs-3.24.0.vfs

After adding your desired uncompressed kernel and rootfs, you can start a vm.

$ spark network create spark0 --subnet 10.1.0.0/16
$ spark vm create -n alpine -k linux:6.18.28 -r alpine:3.24.0 --network spark0 --cpus 2 --mem 2GiB

And finally, start it and optionally connect to it.

$ spark vm start alpine
$ spark vm shell alpine

Note that for spark vm shell to work it must run a service on a vsock port.

Compose (Declarative Deployments)#

Spark supports declarative multi-resource deployments via a spark.hcl file using HCL syntax.

Example `spark.hcl`#

project = "myapp"

network "backend" {
  subnet  = "172.30.0.0/24"
  gateway = "172.30.0.1"
  nat     = true
}

volume "data" {
  size       = "10GiB"
  filesystem = "ext4"
}

vm "web" {
  kernel  = "linux:6.18.28"
  rootfs  = "alpine:3.24.0"
  network = "backend"
  cpus    = 2
  mem     = "512MiB"
  volumes = ["data"]
}

Compose Commands#

# Validate and print the parsed configuration
$ spark compose config

# Create all resources and start VMs
$ spark compose up

# Stop VMs
$ spark compose down

# Stop and remove all resources
$ spark compose down --remove

# List VMs in the compose file
$ spark compose ps

The default compose file is ./spark.hcl. You can specify a different file with the -f flag or as a positional argument:

$ spark compose up ./staging.hcl
$ spark compose down -f ./staging.hcl

Environment#

SPARK_HOME — override all Spark directories for testing/custom installs
SPARK_FIRECRACKER_BIN — override the Firecracker binary path

Default XDG Directories#

config: ~/.config/spark
cache: ~/.cache/spark
state: ~/.local/state/spark
data: ~/.local/share/spark

Configure Feed