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

You can also verify the downloaded file with --hash using a hex digest.
The hash algorithm is auto-detected by length: 40 chars = SHA-1, 64 = SHA-256, 128 = SHA-512.

$ spark kernel add linux:6.18.28 kata/kernels/vmlinuz-6.18.28-124 --hash 7b5c4f3a...
$ spark rootfs add alpine:3.24.0 alpine/images/rootfs-3.24.0.vfs --hash 2a9d8e7f...

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"

kernel "linux" {
  tag = "6.18.28" 
  source = "kata/kernels/vmlinuz-6.18.28-124"
  hash   = "7b5c4f3a..."
}

rootfs "alpine" {
  tag = "3.24.0"
  source = "alpine/images/rootfs-3.24.0.vfs"
  hash   = "2a9d8e7f..."
}

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