How to use Ignite to run VMs¶
Ignite is a containerized Firecracker microVM administration tool. It runs and manages virtual machines in separate containers using Firecracker.
This is a quick guide on how to get started with Ignite. The guide will cover the following topics in order:
- How to use Ignite to run VMs
- Importing a VM base image
- Creating a new VM based on the imported image
- Starting a VM
- Inspecting VMs and their resources
- Accessing a VM
- SSH into the VM
- All in one
- Stopping a VM
- Removing a VM
- Removing other resources
Keep in mind that all Ignite commands require
root for now.
This will change later.
Importing a VM base image¶
A VM base image (or just
image) is an OCI container, which contains a filesystem
and has an init system installed. Ignite currently supports importing
Docker images, for which it has the following command:
# ignite image import <identifier>
The identifier can either be the UID of the image in Docker, or its name. If using the
name without specifying a tag,
:latest is automatically appended. Ignite can also match
a prefix of the given name/UID in any command provided that it's unique, so you can e.g.
enter just the three first letters of a name if they are unique to a single resource.
Go ahead and import the
weaveworks/ignite-ubuntu Docker image. If it isn't present locally,
Ignite will pull it for you:
# ignite image import weaveworks/ignite-ubuntu ... INFO Created image with ID "cae0ac317cca74ba" and name "weaveworks/ignite-ubuntu:latest"
weaveworks/ignite-ubuntu image is imported and ready for VM use.
Creating a new VM based on the imported image¶
images are read-only references of what every VM based on them should contain.
To create a functional
VM, Ignite uses
device mapper to overlay a writable snapshot
on top of the
image. All changes to the
VM will be saved in the snapshot.
Let's create a new VM with some options:
# ignite create weaveworks/ignite-ubuntu \ --name my-vm \ --cpus 2 \ --memory 1GB \ --size 6GB \ --ssh ... INFO Created VM with ID "3c5fa9a18682741f" and name "my-vm"
Options for VM generation¶
The previous example tells Ignite to create a
VM with the name
my-vm and that it should have
2 CPU cores, 1 GB of RAM, a writable snapshot size of 6 GB and have SSH access enabled.
The snapshot stores a delta compared to the base
image, so a
--size of "6GB" enables
storing 6 Gigabytes of data changes (addition or removal).
--ssh flag generates a new private/public key pair
VM and exports the public key it into the
This is used for
ignite ssh <identifier> later.
All available options can be listed with
ignite create --help.
Starting a VM¶
Starting a created
VM is very straight forward:
# ignite start my-vm
VM will be matched by its name or ID (useful if there are similarly named
If no error occured, your
VM is now running.
Inspecting VMs and their resources¶
Ignite currently manages three kinds of resources:
kernels are quite transparent, and get automatically imported from the docker
weaveworks/ignite-kernel:4.19.47 by default (overridable during
To list the available
# ignite kernels KERNEL ID NAME CREATED SIZE VERSION aefb459546315344 weaveworks/ignite-kernel:4.19.47 61m ago 49.0 MB 4.19.47
To list the imported
# ignite images IMAGE ID NAME CREATED SIZE cae0ac317cca74ba weaveworks/ignite-ubuntu:latest 82m ago 268.9 MB
And to list the running
# ignite ps VM ID IMAGE KERNEL CREATED SIZE CPUS MEMORY STATE IPS PORTS NAME 3c5fa9a18682741f weaveworks/ignite-ubuntu:latest weaveworks/ignite-kernel:4.19.47 63m ago 4.0 GB 2 1.0 GB Running 172.17.0.3 my-vm
To list all
VMs instead of just running ones, add the
-a flag to
Accessing a VM¶
Ignite has two ways to access a CLI in a
VM, the first option is to attach to the
and the other is to SSH into the
Attaching to the TTY¶
To attach to the running
VM's TTY, enter:
# ignite attach my-vm 3c5fa9a18682741f <enter> Ubuntu 18.04.2 LTS 3c5fa9a18682741f ttyS0 3c5fa9a18682741f login:
If nothing is displayed, hit Enter to re-display the login prompt.
Login using the credentials set in the
root with password
To detach from the TTY, enter the key combination ^P^Q (Ctrl + P + Q):
root@3c5fa9a18682741f:~# <^P^Q> INFO Detached $
SSH into the VM¶
NOTE: SSH works only if the
--ssh flag is specified during
create. Otherwise there are
no public keys imported into the
VM and most
images have password-based root logins
disabled for security reasons.
To SSH into a
# ignite ssh my-vm Welcome to Ubuntu 18.04.2 LTS (GNU/Linux 4.19.47 x86_64) ... root@3c5fa9a18682741f:~#
To exit SSH, just quit the shell process with
NOTE: Each SSH access spawns its own session, but TTY access
attach is shared, every attached user operates the same terminal.
All in one¶
Ignite has a shorthand for performing
start and possibly also
all in one command:
# ignite run weaveworks/ignite-ubuntu \ --name another-vm \ --cpus 2 \ --memory 1GB \ --size 6GB \ --ssh \ --interactive
This imports the given
image, creates a new
VM from it, starts the
VM and attaches to the
run accepts all the flags for
start. Using the
attach is performed right after the
VM has been started.
Stopping a VM¶
VMs can be stopped three ways:
- By running:
# ignite stop my-vm
- By running:
# ignite kill my-vm
- By issuing the
rebootcommand inside the VM
kernel has support for Firecracker's virtual keyboard,
stop will issue
Ctrl + Alt + Del to gracefully shut down the
VM. It will wait 20 seconds for Firecracker
to exit, after which the
VM will be forcibly killed.
kill is an alias for
stop -f, which force-kills the
VM. WARNING: The
VM is given
no time to close open resources, so this might lead to data loss or filesystem corruption.
reboot inside the
VM is the recommended way to stop a
VM that doesn't support
Firecracker's virtual keyboard. By rebooting the
VM Firecracker shuts itself down gracefully.
NOTE: Do not enter
halt inside the
VM, this will result in
Removing a VM¶
VMs in Ignite, use the following command:
# ignite rm my-vm
VM needs to not be running for this to succeed. Using the
--force flag (
-f for short)
VM can also be removed, it will be killed before removal.
This force option is also able to stop and remove zombie VMs.
# ignite rm -f my-vm
Removing other resources¶
To remove an
# ignite rmi weaveworks/ignite-ubuntu
And to remove a
# ignite rmk weaveworks/ignite-kernel:4.19.47
NOTE: To fully uninstall all Ignite data, remove the data directory
/var/lib/firecracker. Remember to stop all running
VMs before doing this.