docs: kernel policy support

dianpopa · dianpopa · commit cd29c64b35f6 · 2022-01-18T13:33:05.000+02:00
Added the policy behind validating host/guest
kernel versions with Firecracker.

Signed-off-by: Diana Popa &lt;dpopa@amazon.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -30,6 +30,8 @@
   Accepted values are either `V1` or `V2`.
 - Added `GET` request on `/mmds/version` that provides the MMDS version.
   Default value is `V2`.
+- Support and validation for host and guest kernel 5.10.
+- A [kernel support policy](docs/kernel-policy.md).
 
 ### Changed
 
diff --git a/FAQ.md b/FAQ.md
@@ -70,10 +70,10 @@ and guest.
 
 ### What operating systems are supported by Firecracker?
 
-Firecracker supports Linux host and guest operating systems with kernel versions
-4.14 and above, as well as
+Firecracker supports Linux host and guest operating systems as well as
 [OSv](http://blog.osv.io/blog/2019/04/19/making-OSv-run-on-firecraker/) guests.
-The long-term support plan is still under discussion.
+Currently supported host/guest kernel versions can be found in the
+[kernel support policy](docs/kernel-policy.md).
 
 ### What is the open source license for Firecracker?
 
diff --git a/README.md b/README.md
@@ -141,6 +141,11 @@ Firecracker currently only supports little-endian platforms. Firecracker will
 not compile for big-endian architectures, and will not work correctly with
 big-endian configured guests.
 
+## Supported kernels
+
+For a list of supported host/guest kernels and future kernel related
+plans, check out our [kernel support policy](docs/kernel-policy.md).
+
 ## Known issues and Limitations
 
 - The [SendCtrlAltDel](docs/api_requests/actions.md#sendctrlaltdel) API request
diff --git a/docs/RELEASE_POLICY.md b/docs/RELEASE_POLICY.md
@@ -50,6 +50,9 @@ security issues when they are found, for:
 * any Firecracker `vMAJOR.MINOR` release for at least 6 months from release date;
 * for each `vMAJOR`, the latest `MINOR` for 1 year since release date;
 
+Starting with release v1.0, for each major and minor release, we will
+also be specifying the supported kernel versions.
+
 ### Examples
 
 1. Considering an example where the last Firecracker releases are:
diff --git a/docs/design.md b/docs/design.md
@@ -46,9 +46,11 @@ The following diagram depicts an example host running Firecracker microVMs.
 images/firecracker_host_integration.png?raw=true
 "Firecracker Host Integration")
 
-Firecracker runs on Linux hosts with 4.14 or newer kernels and with Linux
-guest OSs (from this point on, referred to as guests). In production
-environments, Firecracker should be started only via the `jailer` binary.
+Firecracker runs on Linux hosts and with Linux guest OSs (from this point on,
+referred to as guests). For a complete list of currently supported kernel
+versions, check out the [kernel support policy](kernel-policy.md).
+
+In production environments, Firecracker should be started only via the `jailer` binary.
 See [Sandboxing](#Sandboxing) for more details.
 
 After launching the process, users interact with the Firecracker API to
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -12,7 +12,7 @@
 
 ## Prerequisites
 
-If you need an opinionated way of running Firecracker, create an `i3.metal`
+If you need an opinionated way of running Firecracker, launch an `i3.metal`
 instance using Ubuntu 18.04 on EC2. Firecracker uses
 [KVM](https://www.linux-kvm.org) and needs read/write access that can be
 granted as shown below:
@@ -23,11 +23,10 @@ sudo setfacl -m u:${USER}:rw /dev/kvm
 
 The generic requirements are explained below:
 
-- **Linux 4.14+**
+- **Linux**
 
   Firecracker currently supports physical Linux **x86_64** and **aarch64**
-  hosts, running kernel version 4.14 or later. However, the **aarch64** support
-  is not feature complete (alpha stage).
+  hosts. The currently supported kernel versions can be found [here](kernel-policy.md).
 
 - **KVM**
 
diff --git a/docs/kernel-policy.md b/docs/kernel-policy.md
@@ -0,0 +1,88 @@
+# Firecracker's Kernel Support Policy
+
+Being a virtual machine monitor, Firecracker represents a component in a
+larger stack, one in which it is tightly coupled with the guest and host
+kernels on which it is run. The presented kernel support policy aims at
+offering customers predictability into future kernel related changes.
+
+As of right now, Firecracker code from main branch is being validated
+continuously on *4.14* and *5.10* host and guest kernels. While other
+versions and other kernel configs might work, they are not periodically
+validated in our test suite, and using them might result in unexpected behaviour.
+Once enabled, a kernel version is supported for a **minimum of 2 years**.
+
+We are validating the currently supported Firecracker releases as per
+[Firecracker’s release policy](../docs/RELEASE_POLICY.md).
+Starting with release `v1.0` each major and minor release will specify
+the supported kernel versions. Adding support for a new kernel version
+will result in a Firecracker release only if compatibility changes are
+required.
+
+The currently supported kernel versions can be seen in the table below.
+Based on our user requests, every year we are considering for enablement
+the latest LTS version.
+
+<table>
+  <tr>
+    <th></th>
+    <th>2022</th>
+  </tr>
+<tr>
+    <td>4.14</td>
+    <td style="background-color:mediumseagreen">full support</td>
+  </tr>
+  <tr>
+    <td>5.10</td>
+    <td style="background-color:mediumseagreen">full support</td>
+  </tr>
+</table>
+
+The guest kernel configs used in our validation pipelines
+can be found [here](../resources/guest_configs/) while a breakdown
+of the relevant guest kernel modules can be found in the next section.
+
+## Guest kernel modules
+
+Below is a per-functionality breakdown of guest kernel modules
+relevant to Firecracker for all platforms:
+
+* serial console - `CONFIG_SERIAL_8250_CONSOLE`, `CONFIG_PRINTK`
+* initrd support - `CONFIG_BLK_DEV_INITRD`
+* virtio devices - `CONFIG_VIRTIO_MMIO`
+  * balloon - `CONFIG_MEMORY_BALLOON`, `CONFIG_VIRTIO_BALLOON`
+  * block - `CONFIG_VIRTIO_BLK`
+    * partuuid support - `CONFIG_MSDOS_PARTITION`
+  * network - `CONFIG_VIRTIO_NET`
+  * vsock - `CONFIG_VIRTIO_VSOCKETS`
+
+There are also guest config options which are dependant on the platform
+on which Firecracker is run:
+
+### ARM
+
+* timekeeping - `CONFIG_ARM_AMBA`, `CONFIG_RTC_DRV_PL031`
+
+### x86_64
+
+* timekeeping - `CONFIG_KVM_GUEST` (which enables CONFIG_KVM_CLOCK)
+* high precision timekeeping - `CONFIG_PTP_1588_CLOCK`, `CONFIG_PTP_1588_CLOCK_KVM`
+* external clean shutdown - `CONFIG_SERIO_I8042`, `CONFIG_KEYBOARD_ATKBD`
+* virtio devices - `CONFIG_VIRTIO_MMIO_CMDLINE_DEVICES`
+
+#### Minimal boot requirements
+
+Depending on the source of boot (either from a block device or from an initrd),
+the minimally required guest kernel modules for a successful microVM boot are:
+
+* Booting with initrd:
+  * `CONFIG_BLK_DEV_INITRD`
+    * For aarch64, you also need `CONFIG_VIRTIO_MMIO` (for the serial device).
+    * For x86_64, you also need `CONFIG_KVM_GUEST`.
+
+* Booting with root block device:
+  * `CONFIG_VIRTIO_BLK`
+  * For x86_64, you also need `CONFIG_VIRTIO_MMIO_CMDLINE_DEVICES` and `CONFIG_KVM_GUEST`.
+
+If you wish to enable boot logs, make sure to also add
+`CONFIG_SERIAL_8250_CONSOLE` and `CONFIG_PRINTK` to the guest kernel config.
+
diff --git a/docs/prod-host-setup.md b/docs/prod-host-setup.md
@@ -373,7 +373,7 @@ spec_store_bypass_disable=seccomp
 which will apply SSB if seccomp is enabled by Firecracker.
 
 On aarch64 systems, it is enabled by Firecracker
-[using the `prctl` interface][3]. However, this is only availabe on host
+[using the `prctl` interface][3]. However, this is only available on host
 kernels Linux >=4.17 and also Amazon Linux 4.14. Alternatively, a global
 mitigation can be enabled by adding the following Linux kernel boot parameter:
 
diff --git a/docs/rootfs-and-kernel-setup.md b/docs/rootfs-and-kernel-setup.md
@@ -50,6 +50,9 @@ can boot:
 1. Upon a successful build, you can find the kernel image under `./vmlinux`
    (for x86) or `./arch/arm64/boot/Image` (for aarch64).
 
+For a list of currently supported kernel versions, check out the
+[kernel support policy](kernel-policy.md).
+
 ### Use the provided recipe
 
 The kernel images used in our CI to test Firecracker's features are obtained by
