Repository files navigation

Our mission is to enable secure, multi-tenant, minimal-overhead execution ofcontainer and function workloads.

Read more about the Firecracker Charterhere.

Firecracker is an open source virtualization technology that is purpose-builtfor creating and managing secure, multi-tenant container and function-basedservices that provide serverless operational models. Firecracker runs workloadsin lightweight virtual machines, called microVMs, which combine the security andisolation properties provided by hardware virtualization technology with thespeed and flexibility of containers.

The main component of Firecracker is a virtual machine monitor (VMM) that usesthe Linux Kernel Virtual Machine (KVM) to create and run microVMs. Firecrackerhas a minimalist design. It excludes unnecessary devices and guest-facingfunctionality to reduce the memory footprint and attack surface area of eachmicroVM. This improves security, decreases the startup time, and increaseshardware utilization. Firecracker has also been integrated in container runtimes,for exampleKata ContainersandWeaveworks Ignite.

Firecracker was developed at Amazon Web Services to accelerate the speed andefficiency of services likeAWS Lambda andAWS Fargate. Firecracker is opensourced underApache version 2.0.

To read more about Firecracker, check outfirecracker-microvm.io.

To get started with Firecracker, download the latestrelease binariesor build it from source.

You can build Firecracker on any Unix/Linux system that has Docker running(we use a development container) andbash installed, as follows:

git clone https://github.com/firecracker-microvm/firecrackercd firecrackertools/devtool buildtoolchain="$(uname -m)-unknown-linux-musl"

The Firecracker binary will be placed atbuild/cargo_target/${toolchain}/debug/firecracker. For more information onbuilding, testing, and running Firecracker, go to thequickstart guide.

The overall security of Firecracker microVMs, including the ability to meet thecriteria for safe multi-tenant computing, depends on a well configured Linuxhost operating system. A configuration that we believe meets this bar isincluded inthe production host setup document.

Firecracker is already running production workloads within AWS, but it's stillDay 1 on the journey guided by ourmission. There's a lot more tobuild and we welcome all contributions.

To contribute to Firecracker, check out the development setup section in thegetting started guide and then the Firecrackercontribution guidelines.

New Firecracker versions are released via the GitHub repositoryreleases page,typically every two or three months. A history of changes is recorded in ourchangelog.

The Firecracker release policy is detailedhere.

Firecracker's overall architecture is described inthe design document.

Firecracker consists of a single micro Virtual Machine Manager process thatexposes an API endpoint to the host once started. The API isspecified in OpenAPI format. Read moreabout it in theAPI docs.

TheAPI endpoint can be used to:

• Configure the microvm by:
  • Setting the number of vCPUs (the default is 1).
  • Setting the memory size (the default is 128 MiB).
  • Configuring aCPU template.
• Add one or more network interfaces to the microVM.
• Add one or more read-write or read-only disks to the microVM, each representedby a file-backed block device.
• Trigger a block device re-scan while the guest is running. This enables theguest OS to pick up size changes to the block device's backing file.
• Change the backing file for a block device, before or after the guest boots.
• Configure rate limiters for virtio devices which can limit the bandwidth,operations per second, or both.
• Configure the logging and metric system.
• [BETA] Configure the data tree of the guest-facing metadata service. Theservice is only available to the guest if this resource is configured.
• Add avsock socket to the microVM.
• Add aentropy device to the microVM.
• Start the microVM using a given kernel image, root file system, and bootarguments.
• [x86_64 only] Stop the microVM.

Built-in Capabilities:

• Demand fault paging and CPU oversubscription enabled by default.
• Advanced, thread-specific seccomp filters for enhanced security.
• Jailer process for starting Firecracker in productionscenarios; applies a cgroup/namespace isolation barrier and thendrops privileges.

We test all combinations of:

• TheSendCtrlAltDel API requestis not supported for aarch64 enabled microVMs.
• If a CPU template is not used on x86_64, overwrites ofMSR_IA32_TSX_CTRL MSRvalue will not be preserved after restoring from a snapshot.
• Thepl031 RTC device on aarch64 does not support interrupts, so guestprograms which use an RTC alarm (e.g.hwclock) will not work.
• Issues and limitations related to snapshots are described in aseparate document.

Firecracker's performance characteristics are listed as part of thespecification documentation. All specifications are a partof our commitment to supporting container and function workloads in serverlessoperational models, and are therefore enforced via continuous integrationtesting.

The security of Firecracker is our top priority. If you suspect you haveuncovered a vulnerability, contact us privately, as outlined in oursecurity policy document; we will immediately prioritizeyour disclosure.

Frequently asked questions are collected in ourFAQ doc.

You can get in touch with the Firecracker community in the following ways:

• Security-related issues, see oursecurity policy document.
• Chat with us on ourSlack workspaceNote: most of the maintainers are on a European time zone.
• Open a GitHub issue in this repository.
• Email the maintainers atfirecracker-maintainers@amazon.com.

When communicating within the Firecracker community, please mind ourcode of conduct.