README
¶
firecracker-containerd
This repository enables the use of a container runtime, containerd, to manage Firecracker microVMs. Like traditional containers, Firecracker microVMs offer fast start-up and shut-down and minimal overhead. Unlike traditional containers, however, they can provide an additional layer of isolation via the KVM hypervisor.
Potential use cases of Firecracker-based containers include:
- Sandbox a partially or fully untrusted third party container in its own microVM. This would reduce the likelihood of leaking secrets via the third party container, for example.
- Bin-pack disparate container workloads on the same host, while maintaining a high level of isolation between containers. Because the overhead of Firecracker is low, the achievable container density per host should be comparable to running containers using kernel-based container runtimes, without the isolation compromise of such solutions. Multi-tenant hosts would particularly benefit from this use case.
To maintain compatibility with the container ecosystem, where possible, we use container standards such as the OCI image format.
There are several components in this repository that enable containerd to use Firecracker microVMs to run containers:
- A control plugin managing the lifecycle of the runtime and implementing our control API to manage the lifecycle of microVMs. The control plugin is compiled in to the containerd binary since building a Go plugin out-of-tree is hard, which requires us to build a specialized containerd binary for firecracker-containerd.
- A runtime linking containerd (outside the microVM) to the Firecracker virtual machine monitor (VMM). The runtime is implemented as an out-of-process shim runtime communicating over ttrpc.
- An agent running inside the microVM, which invokes
runC via containerd's
containerd-shim-runc-v1to create standard Linux containers inside the microVM. - A root file filesystem image builder that constructs a firecracker microVM root filesystem containing runc and the firecracker-containerd agent.
For more detailed information on the components and how they work, see architecture.md.
Roadmap
To support the widest variety of workloads, firecracker-containerd has to work with popular container orchestration frameworks such as Kubernetes and Amazon ECS, so we will work to ensure that the software is conformant or compatible where necessary. The project currently allows you to launch a few containers colocated in the same microVM, and we are exploring how to raise the number of containers. We recently added support for configuring networking at the microVM level with CNI plugins and provide a CNI plugin suitable for chaining called "tc-redirect-tap". Our short term roadmap includes constraining or "jailing" the Firecracker VMM process to improve the host security posture. Our longer-term roadmap includes polishing, packaging, and generally making firecracker-containerd easier to run as well as exploring CRI conformance and compatibility with Kubernetes.
Details of specific roadmap items are tracked in GitHub issues.
Usage
For detailed instructions on building and running firecracker-containerd, see the getting started guide and the quickstart guide.
Questions?
Please use GitHub issues to report problems, discuss roadmap items, or make feature requests.
If you've discovered an issue that may have security implications to users or developers of this software, please do not report it using GitHub issues, but instead follow Firecracker's security reporting guidelines.
Other discussion: For general discussion, please join us in the #containerd
channel on the Firecracker Slack.
License
This library is licensed under the Apache 2.0 License.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package client contains helpers for working with containers managed by firecracker-containerd, such as computing rootfs paths inside a microVM.
|
Package client contains helpers for working with containers managed by firecracker-containerd, such as computing rootfs paths inside a microVM. |
|
Package config defines configuration structures and helpers used by firecracker-containerd, including loading and validating config files.
|
Package config defines configuration structures and helpers used by firecracker-containerd, including loading and validating config files. |
|
docker-credential-mmds
module
|
|
|
Package eventbridge implements an event forwarding bridge that translates and relays containerd events to firecracker-containerd components.
|
Package eventbridge implements an event forwarding bridge that translates and relays containerd events to firecracker-containerd components. |
|
Package service defines common constants shared by the firecracker-control service implementation, such as plugin identifiers.
|
Package service defines common constants shared by the firecracker-control service implementation, such as plugin identifiers. |
|
client
Package client implements a Go client for interacting with the firecracker-control service, providing access to VM and lifecycle management APIs.
|
Package client implements a Go client for interacting with the firecracker-control service, providing access to VM and lifecycle management APIs. |
|
cmd/containerd
command
|
|
|
Package internal contains shared helpers and internal utilities used across firecracker-containerd components.
|
Package internal contains shared helpers and internal utilities used across firecracker-containerd components. |
|
bundle
Package bundle implements some helper functions for firecracker-containerd's interaction with bundle dirs, both inside the VM and outside on the host.
|
Package bundle implements some helper functions for firecracker-containerd's interaction with bundle dirs, both inside the VM and outside on the host. |
|
cmd/test-bridged-tap
command
This is a bare-bones CNI plugin (with only ADD actually implemented, other methods are no-ops) used to setup a network bridge w/ tap in order to compare performance of a bridge-based VM network w/ a TC-based approach, such as that created by the tc-redirect-tap plugin.
|
This is a bare-bones CNI plugin (with only ADD actually implemented, other methods are no-ops) used to setup a network bridge w/ tap in order to compare performance of a bridge-based VM network w/ a TC-based approach, such as that created by the tc-redirect-tap plugin. |
|
debug
Package debug provides helpers for configuring firecracker-containerd logging and managing debug log levels across components.
|
Package debug provides helpers for configuring firecracker-containerd logging and managing debug log levels across components. |
|
event
Package event provides internal event exchange utilities, supporting publish/subscribe patterns for firecracker-containerd components.
|
Package event provides internal event exchange utilities, supporting publish/subscribe patterns for firecracker-containerd components. |
|
integtest
Package integtest provides shared configuration and utilities for integration tests across firecracker-containerd.
|
Package integtest provides shared configuration and utilities for integration tests across firecracker-containerd. |
|
shim
Package shim provides helpers for working with the containerd shim, including construction of Firecracker control socket addresses.
|
Package shim provides helpers for working with the containerd shim, including construction of Firecracker control socket addresses. |
|
vm
Package vm provides helpers for managing Firecracker VMs, including agent-related IO handling utilities.
|
Package vm provides helpers for managing Firecracker VMs, including agent-related IO handling utilities. |
|
service/drivemount/ttrpc
Code generated by protoc-gen-go-ttrpc.
|
Code generated by protoc-gen-go-ttrpc. |
|
service/fccontrol/ttrpc
Code generated by protoc-gen-go-ttrpc.
|
Code generated by protoc-gen-go-ttrpc. |
|
service/ioproxy/ttrpc
Code generated by protoc-gen-go-ttrpc.
|
Code generated by protoc-gen-go-ttrpc. |
|
cpuset
Package cpuset provides helpers for constructing and managing cpusets used by Firecracker VMs and container workloads.
|
Package cpuset provides helpers for constructing and managing cpusets used by Firecracker VMs and container workloads. |
|
firecrackeroci
Package firecrackeroci defines OCI annotations and related helpers used by the Firecracker runtime integration.
|
Package firecrackeroci defines OCI annotations and related helpers used by the Firecracker runtime integration. |
|
vm
Package vm contains Firecracker VM runtime helpers, including utilities for preparing and managing container filesystem mounts inside VMs.
|
Package vm contains Firecracker VM runtime helpers, including utilities for preparing and managing container filesystem mounts inside VMs. |
|
app
Package app implements the application layer for the snapshotter, including service initialization and GRPC wiring.
|
Package app implements the application layer for the snapshotter, including service initialization and GRPC wiring. |
|
config
Package config defines configuration structures and helpers for the demux snapshotter, including loading configuration from TOML files.
|
Package config defines configuration structures and helpers for the demux snapshotter, including loading configuration from TOML files. |
|
demux
Package demux implements the demux snapshotter, which routes snapshotter operations to remote backends based on image configuration.
|
Package demux implements the demux snapshotter, which routes snapshotter operations to remote backends based on image configuration. |
|
demux/cache
Package cache implements a cache of remote snapshotters used by the demux snapshotter for routing requests and service discovery.
|
Package cache implements a cache of remote snapshotters used by the demux snapshotter for routing requests and service discovery. |
|
demux/internal
Package internal contains internal test and helper implementations for the demux snapshotter, including a snapshotter that intentionally fails for error-path validation.
|
Package internal contains internal test and helper implementations for the demux snapshotter, including a snapshotter that intentionally fails for error-path validation. |
|
demux/metrics
Package metrics exposes Prometheus metrics for the demux snapshotter's proxy operations, providing visibility into request handling and failures.
|
Package metrics exposes Prometheus metrics for the demux snapshotter's proxy operations, providing visibility into request handling and failures. |
|
demux/metrics/discovery
Package discovery provides metrics and helpers for discovering remote snapshotter services used by the demux snapshotter.
|
Package discovery provides metrics and helpers for discovering remote snapshotter services used by the demux snapshotter. |
|
demux/proxy
Package proxy implements the proxy snapshotter used by the demux snapshotter to route requests to remote snapshotter backends.
|
Package proxy implements the proxy snapshotter used by the demux snapshotter to route requests to remote snapshotter backends. |
|
demux/proxy/address
Package address defines resolvers for locating proxy network addresses used by the demux snapshotter's HTTP services.
|
Package address defines resolvers for locating proxy network addresses used by the demux snapshotter's HTTP services. |
|
internal
command
http-address-resolver runs a small HTTP service that resolves snapshotter namespaces to proxy addresses for the demux snapshotter.
|
http-address-resolver runs a small HTTP service that resolves snapshotter namespaces to proxy addresses for the demux snapshotter. |
|
internal/integtest/stargz/fs/config
Package config defines labels used to configure the Stargz remote snapshotter behavior in integration tests.
|
Package config defines labels used to configure the Stargz remote snapshotter behavior in integration tests. |
|
internal/integtest/stargz/fs/source
Package source builds source information for stargz-based remote snapshots in integration tests by annotating image descriptors.
|
Package source builds source information for stargz-based remote snapshots in integration tests by annotating image descriptors. |
|
internal/mount
Package mount provides helpers for working with collections of containerd mounts.
|
Package mount provides helpers for working with collections of containerd mounts. |
|
Package volume provides volumes like Docker and Amazon ECS.
|
Package volume provides volumes like Docker and Amazon ECS. |
|
cmd/volume-init
command
volume-init reads volume mapping configuration from stdin and copies the requested directories into the guest volume image.
|
volume-init reads volume mapping configuration from stdin and copies the requested directories into the guest volume image. |
Click to show internal directories.
Click to hide internal directories.