Skip to content

Commit cfd4063

Browse files
raduweissandreeaflorescu
raduweiss
authored and
andreeaflorescu
committed
docs: v0.1 update for README.md
Signed-off-by: Radu Weiss <[email protected]>
1 parent d211633 commit cfd4063

File tree

1 file changed

+152
-20
lines changed

1 file changed

+152
-20
lines changed

‎README.md

Lines changed: 152 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,160 @@
1-
firecracker
2-
===========
1+
# What is Firecracker
32

4-
A virtualization technology implemented in [rust](https://www.rust-lang.org) that replaces the container runtime with a light weight
5-
*micro*-Virtual Machine (micro-VM). Micro-VMs combine the security and workload
6-
isolation properties of traditional VMs with the speed and resource efficiency of containers.
3+
Firecracker is a new virtualization technology that enables customers to deploy lightweight *micro* Virtual Machines or microVMs. Firecracker microVMs combine the security and workload isolation properties of traditional VMs with the speed and resource efficiency enabled by containers. MicroVMs can initiate user-space code execution in less than 150ms, have a footprint of less than 32 MiB of memory, and provide a secure, trusted environment for multi-tenant services. Customers can create microVMs with any combination of vCPU and memory to match their application requirements.
74

8-
## Usage
9-
Show what the library does as concisely as possible, developers should be able to figure out **how** your project solves their problem by looking at the code example. Make sure the API you are showing off is obvious, and that your code is short and concise.
10-
### Code Sample
5+
MicroVMs are created and managed by the Firecracker process, which implements a virtual machine manager based on Linux's Kernel-based Virtual Machine (KVM), the state of art for Linux virtualization. Firecracker provides the minimal required device emulation to the guest operating system while excluding non-essential functionality to enable faster startup time and a reduced memory footprint. The Firecracker process also provides a control API, enforces microVM sandboxing, and handles resource rate limiting for microVMs.
116

12-
## Motivation
13-
A short description of the motivation behind the creation and maintenance of the project. This should explain **why** the project exists.
7+
# Overview
148

15-
## Installation
16-
Provide code examples and explanations of how to get the project.
9+
This Readme currently pertains to the v0.1 release.
1710

18-
## API Reference
19-
Depending on the size of the project, if it is small and simple enough the reference docs can be added to the README. For medium size to larger projects it is important to at least provide a link to where the API reference docs live.
11+
Firecracker consists of single micro Virtual Machine Manager binary that will spawn a RESTful API endpoint when started. In v0.1, the API endpoint can be used to:
12+
* Add one or more vCPUs to the microVM.
13+
* Add memory to the microVM.
14+
* Add one or more network interfaces to the microVM.
15+
* Add one or more read/write disks (block devices) to the microVM.
16+
* Add one or more vSockets to the microVM.
17+
* Start the microVM using a given kernel image and root file system.
2018

21-
## Continuous Integration
22-
Describe and show how to run the tests with code examples.
19+
## What's Included in v0.1?
20+
* One-process virtual machine manager (one Firecracker per microVM).
21+
* RESTful API running on a unix socket. The API supported by v0.1 can be found at `api/swagger/firecracker-v0.1.yaml`.
22+
* Emulated keyboard (i8042) and serial console (UART). The microVM serial console input and output are connected to those of the Firecracker process (this allows direct console access to the guest OS).
23+
* The capability of mapping an existing host tun-tap device as a virtIO/net device into the microVM.
24+
* The capability of mapping an existing host file as a virtIO/block device into the microVM.
25+
* The capability of creating a virtIO/vsock between the host and the microVM.
26+
* Default demand fault paging & CPU oversubscription.
2327

24-
## Contributing
25-
Let people know how they can dive into the project, include important links to things like issue trackers, irc, twitter accounts if applicable.
28+
## Limits and Performance
2629

27-
## License
28-
Apache 2.0
30+
So far, no stress testing & benchmarking has been done. This is scheduled for a pater timeframe. A couple of manual tests indicate that at least 2000 Firecracker microVMs and 2000 TUN/TAP devices work (under no stress) on an i3p instance.
31+
32+
# Getting Started
33+
34+
## Build the Firecracker Binary
35+
Clone this repo and build it with Rust's: `cargo build --release`.
36+
37+
## Secure a Host with KVM Access
38+
To build, test, or run, Firecracker requires a host with a modern version of KVM (Linux kernel 4.11+) running on physical hardware (or a virtual machine with nested virtualization enabled).
39+
40+
## Firecracker's Take on Resources
41+
Firecracker expects network interfaces and drives to be created beforehand and passed by name. Ensure Firecracker will have the required permissions to open these resources. For example, if using a TUN/TAP device, you will need to create this beforehand, and call the `/network-interfaces` API with the name of the host TUN/TAP interface.
42+
43+
## Select the Guest Kernel and RootFS
44+
To run microVMs with Firecracker, you will need to have:
45+
* a guest kernel image that boots and runs with Firecracker's minimal/VirtIO device model, and
46+
* a guest root file system that boots with that kernel.
47+
* The guest RootFS can be an image file or drive.
48+
49+
## Runtime Dependencies
50+
* Firecracker needs rw access to `/dev/kvm`. You can grant these rights, e.g., to tall users, with: `sudo chmod a+rw /dev/kvm`
51+
* If you want to use vsocks between the Firecracker guest and host, Firecracker will need to be run with sudo rights.
52+
53+
## Start Firecracker & the Micro VM
54+
55+
The python-based toy example below will start a Firecracker microVM with 2 vCPUs, 256 MiB or RAM, two network interfaces, two disks (rootfs and temp), and a vsocket.
56+
57+
Currently, only the core parts of the API (`/actions`, `/machine-config`, `/boot-source`, `/network-interfaces`, `/drives`, and `/vsocks`) are implemented. See section [What's Included in v0.1?](https://quip-amazon.com/Y3RFAqZFxBwE#BGO9CAEkkRE) for more details. For the planned v1.0 API description see `/api/swagger/all.yaml`.
58+
59+
The toy example snapshot below uses a Python script to start a Firecracker instance. The Firecracker binary, as well as compatible kernel, root file system, and temp file system images are assumed to already exist. The TUN/TAP devices passed to the networking API are also assumed to already exist. Firecracker requires root privileges to open vsock interfaces on a host.
60+
61+
The full example can be found in [the examples directory](examples/hello_api/spawn_microvm.py)
62+
63+
```
64+
# Spawn a new Firecracker Virtual Machine Manager process.
65+
firecracker = Firecracker('0001')
66+
firecracker.spawn()
67+
68+
# Give the api time to come online since we don't handle retries here.
69+
time.sleep(0.0042)
70+
71+
# Configure the microVM CPU and memory.
72+
requests.put(firecracker.machine_config_url, json={'vcpu_count': 2})
73+
requests.put(firecracker.machine_config_url, json={'mem_size_mib': 256})
74+
75+
# Add a network interface to the microVM.
76+
# Firecracker will map this host network interface into the microVM.
77+
requests.put(
78+
firecracker.network_ifaces_url + '/1',
79+
json={
80+
'iface_id': '1',
81+
'host_dev_name': 'fc0001tap1',
82+
'state': 'Attached'
83+
}
84+
)
85+
86+
# Add another network interface to the microVM.
87+
# Firecracker will map this host network interface into the microVM.
88+
requests.put(
89+
firecracker.network_ifaces_url + '/2',
90+
json={
91+
'iface_id': '2',
92+
'host_dev_name': 'fc0001tap2',
93+
'state': 'Attached'
94+
}
95+
)
96+
97+
# Add a disk (block device) to the microVM.
98+
# This one will be flagged as the root file system.
99+
requests.put(
100+
firecracker.drives_url + '/1',
101+
json={
102+
'drive_id': '1',
103+
'path_on_host': '/tmp/firecracker0001/ami-rootfs.ext4',
104+
'state': 'Attached',
105+
'is_root_device': True
106+
}
107+
)
108+
109+
# Add another disk (block device) to the microVM.
110+
# This one is empty, usable for, e.g., guest scratch space.
111+
requests.put(
112+
firecracker.drives_url + '/2',
113+
json={
114+
'drive_id': '2',
115+
'path_on_host': '/tmp/firecracker0001/scratch.ext4',
116+
'state': 'Attached',
117+
'is_root_device': False
118+
}
119+
)
120+
121+
# Add a vsocket between the host and guest OSs (requiers both to be Linux).
122+
# Requires appropriate privileges, and both host and guest kernel support.
123+
requests.put(
124+
firecracker.vsocks_url + '/1',
125+
json={'vsock_id': '1', 'guest_cid': 10001, 'state': 'Attached'}
126+
)
127+
128+
# Specify a boot source: a kernel image.
129+
# Currently, only linux kernel images are supported.
130+
requests.put(
131+
firecracker.boot_source_url,
132+
json={
133+
'boot_source_id': '1',
134+
'source_type': 'LocalImage',
135+
'local_image': {'kernel_image_path': '/tmp/vmlinux.bin'},
136+
}
137+
)
138+
139+
# Start!
140+
requests.put(
141+
firecracker.actions_url + '/1',
142+
json={'action_id': '1', 'action_type': 'InstanceStart'}
143+
)
144+
```
145+
146+
## Notes for v0.1
147+
1. The Kernel and RootFS need to work together, and the Kernel needs to run with Firecracker's limited device model.
148+
2. Vsocket usage currently requires root privileges, and both host (`CONFIG_VHOST_VSOCK`) and guest (`CONFIG_VIRTIO_VSOCKETS`) kernel support.
149+
3. During bootup, an error will be displayed when mounting the disk: `[ERROR:devices/src/virtio/block.rs:209] failed executing disk request: Unsupported(8)`. This is because we don't currently create an ID in the virtio block device. It should be benign.
150+
4. When creating more than one Firecracker v0.1 microVM, make sure you will have separate copies of the file system images. All drives are currently mounted in read-write mode.
151+
5. Firecracker v0.1 uses default values for the following parameters:
152+
1. Kernel Command Line: `console=ttyS0 noapic reboot=k panic=1 pci=off nomodules`. This can be changed with a `PUT` request to `/boot-source`.
153+
2. Number of vCPUs: 1. This can be changed with a `PUT` request to `/machine-config`
154+
3. Memory Size: 128 Mib. This can be changed with a `PUT` request to `/machine-config`
155+
4. Unix domain socket: `/tmp/firecracker.socket`. This can be changed only when Firecracker is started, by using the command line parameter `--api-sock`.
156+
6. Firecracker v0.1 links the microVM serial console output to its stdout, and its stdin to the microVM serial console input. Therefore, you can interact with the microVM guest in the screen session.
157+
7. Important: The unix domain socket is not deleted when Firecracker v0.1 is stopped. You have to remove it yourself after stopping the Firecracker process.
158+
159+
## Shutting Down
160+
Firecracker v0.1 doesn't emulate a power management device, so poweroff doesn't work as expected (it leaves Firecracker hanging).

0 commit comments

Comments
 (0)