* ADRs based on discussions with Alyssa * A note on ADRs to architecture.adoc Signed-off-by: Ville Ilvonen <ville.ilvonen@unikie.com> --- Documentation/architecture.adoc | 13 ++++++++++ ...architecture-decision-record-template.adoc | 13 ++++++++++ .../decisions/001-host-update-mechanism.adoc | 19 ++++++++++++++ .../decisions/002-install-options.adoc | 18 +++++++++++++ Documentation/decisions/003-partitioning.adoc | 25 +++++++++++++++++++ .../004-data-at-rest-encryption.adoc | 16 ++++++++++++ .../005-virtual-machine-manager.adoc | 24 ++++++++++++++++++ .../decisions/006-drivers-on-host.adoc | 17 +++++++++++++ .../decisions/007-USB-virtual-machine.adoc | 14 +++++++++++ ...008-Inter-VM-communication-mechanisms.adoc | 18 +++++++++++++ 10 files changed, 177 insertions(+) create mode 100644 Documentation/decisions/000-lightweight-architecture-decision-record-template.adoc create mode 100644 Documentation/decisions/001-host-update-mechanism.adoc create mode 100644 Documentation/decisions/002-install-options.adoc create mode 100644 Documentation/decisions/003-partitioning.adoc create mode 100644 Documentation/decisions/004-data-at-rest-encryption.adoc create mode 100644 Documentation/decisions/005-virtual-machine-manager.adoc create mode 100644 Documentation/decisions/006-drivers-on-host.adoc create mode 100644 Documentation/decisions/007-USB-virtual-machine.adoc create mode 100644 Documentation/decisions/008-Inter-VM-communication-mechanisms.adoc diff --git a/Documentation/architecture.adoc b/Documentation/architecture.adoc index 157907f..185740c 100644 --- a/Documentation/architecture.adoc +++ b/Documentation/architecture.adoc @@ -20,6 +20,19 @@ devices and provides network services to application VMs). Refer to xref:creating-vms.adoc[Creating VMs] and xref:running-vms.adoc[Running VMs] for more information about using VMs in Spectrum. +== Architecture Decision Record (ADR) + +https://adr.github.io/[Architecturally significant decisions] are +recorded as https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-by-michael-nygard/index.md[light-weight ADRs] + +Status of Spectrum OS ADRs: +Accepted - Implemented and likely not to change. +Proposed - Designed and possibly partially implmented. May change. +Other - Not yet in use. + +Comments and contributions to ADRs are welcome. ADRs can be found at +Documentation/decisions + == The Spectrum host system Compartmentalization is implemented using diff --git a/Documentation/decisions/000-lightweight-architecture-decision-record-template.adoc b/Documentation/decisions/000-lightweight-architecture-decision-record-template.adoc new file mode 100644 index 0000000..087ec44 --- /dev/null +++ b/Documentation/decisions/000-lightweight-architecture-decision-record-template.adoc @@ -0,0 +1,13 @@ +# Title + +## Status +What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.? + +## Context +What is the issue that we're seeing that is motivating this decision or change? + +## Decision +What is the change that we're proposing and/or doing? + +## Consequences +What becomes easier or more difficult to do because of this change? diff --git a/Documentation/decisions/001-host-update-mechanism.adoc b/Documentation/decisions/001-host-update-mechanism.adoc new file mode 100644 index 0000000..03bbae2 --- /dev/null +++ b/Documentation/decisions/001-host-update-mechanism.adoc @@ -0,0 +1,19 @@ +# Host update mechanism + +## Status +Proposed + +## Context +Spectrum OS has no implementation for software update. The host - consisting of +Linux kernel, KVM, cloud-hypervisor and minimal user space tools - software +updates are required to support feature development and security fixes. + +## Decision +A-B partitioning created by Spectrum installer Installer sets up the system on +partition A of the block device A-B update scheme where user (or installer) +writes the update image to partition B Bootloader provides four boot options: +A, A mutable, B, B mutable + +## Consequences +Default boot selection, incremental updates (e.g. overlays), network update +postponed for later. diff --git a/Documentation/decisions/002-install-options.adoc b/Documentation/decisions/002-install-options.adoc new file mode 100644 index 0000000..f5857c5 --- /dev/null +++ b/Documentation/decisions/002-install-options.adoc @@ -0,0 +1,18 @@ +# Install options + +## Status +Proposed + +## Context +Based on identified different audiences for the Spectrum OS release it is +proposed we support three base configurations to use with Spectrum OS in the +first boot. + +## Decision +* Minimal - Spectrum OS host + system VMs: netvm, guivm, usbvm + home-directory +(optionally encrypted - see 004-disk-encryption.md) +* Common - Minimal + browser app VM + 2-3 selected app VMs +* Power - Common + NixOS VM + +## Consequences +Requires first-boot-vm (like wizard) to support user to get started. diff --git a/Documentation/decisions/003-partitioning.adoc b/Documentation/decisions/003-partitioning.adoc new file mode 100644 index 0000000..345619f --- /dev/null +++ b/Documentation/decisions/003-partitioning.adoc @@ -0,0 +1,25 @@ +# Partitioning + +## Status +Proposed + +## Context +Partitions are required to install the Spectrum OS, VMs and store user data. + +## Decision +---- +<blockdevice> # EFI system partition +<blockdevice> # XBOOTLDR +<blockdevice> # A +<blockdevice> # B +# first 32 GB are reserved for Spectrum system +# rest of the disk is reserved for user data +<blockdevice>n-1 # bootstrap user data +<blockdevice>n to the end of disk # user data +---- + +## Consequences +LVM may support resizing - both increasing and decreasing with some limitation +when there's alreay data on volume(s). Does LVM work with all disk types? We +have to implement XBOOTLDR to support EFI system partition created by Windows - +to support dual boot diff --git a/Documentation/decisions/004-data-at-rest-encryption.adoc b/Documentation/decisions/004-data-at-rest-encryption.adoc new file mode 100644 index 0000000..3ed9abb --- /dev/null +++ b/Documentation/decisions/004-data-at-rest-encryption.adoc @@ -0,0 +1,16 @@ +# Data at rest encryption + +## Status +Proposed + +## Context +To support user data and privacy protection, encryption of data at rest is +required. + +## Decision +User data is encrypted. + +## Consequences +Spectrum OS needs to come with enough SW to get the encryption key via different +methods (password, usb, fido, etc.) Can we use dm-crypt for everything instead +of LUKS? diff --git a/Documentation/decisions/005-virtual-machine-manager.adoc b/Documentation/decisions/005-virtual-machine-manager.adoc new file mode 100644 index 0000000..b4af595 --- /dev/null +++ b/Documentation/decisions/005-virtual-machine-manager.adoc @@ -0,0 +1,24 @@ +# Virtual Machine Manager + +## Status +Accepted + +## Context +rust-vmm-based VMM provides memory and concurrency safe solution. +cloud-hypervisor was chosen because firecrack does not support other +virtio-devices than net or block. crosvm was not chosen because cloud-hypervisor +has more flexible IPC mechanisms, more engaging community as LF-project. +cloud-hypervisor has more core features - such as snapshotting, live migration +and more general hot plugging. crosvm supports more devices we will also need. +It was seen easier to port devices from crosvm to cloud-hypervisor than to port +core features from cloud-hypervisor to crosvm. + +## Decision +Spectrum OS design and implementation decision is to use cloud-hypervisor as the +primary VMM. + +## Consequences +We gotta port some stuff from crosvm to cloud-hypervisor. It's easier for +Spectrum to handle virtualization dynamically with cloud-hypervisor. If the +primary VMM, cloud-hypervisor, is exchanged for trials etc. functionality is +expected to break or not supported. diff --git a/Documentation/decisions/006-drivers-on-host.adoc b/Documentation/decisions/006-drivers-on-host.adoc new file mode 100644 index 0000000..052b596 --- /dev/null +++ b/Documentation/decisions/006-drivers-on-host.adoc @@ -0,0 +1,17 @@ +# Drivers on host + +## Status +Accepted + +## Context +To harden the trusted computing base and make it more minimal, the target is to +minimize the amount of drivers on the Spectrum host kernel. + +## Decision +We are aiming to have as few drivers as possible on the host. + +## Consequences +No networking on the host. Responsibilities of the host are expected to get +smaller over time. More flexible management of devices. We need to decouple +device classes - like net, usb, bluetooth and gui - from host to their +respective VMs. diff --git a/Documentation/decisions/007-USB-virtual-machine.adoc b/Documentation/decisions/007-USB-virtual-machine.adoc new file mode 100644 index 0000000..2072427 --- /dev/null +++ b/Documentation/decisions/007-USB-virtual-machine.adoc @@ -0,0 +1,14 @@ +# USB Virtual Machine + +## Status +Proposed + +## Context +To support specific USB devices on specific VMs + +## Decision +The decision is to pass-through USB controller to a VM with authorization +controls inside the VMs to forward a specific USB device using USBIP. + +## Consequences +We need to modify the upstream USBIP daemon to support authorization. diff --git a/Documentation/decisions/008-Inter-VM-communication-mechanisms.adoc b/Documentation/decisions/008-Inter-VM-communication-mechanisms.adoc new file mode 100644 index 0000000..1007037 --- /dev/null +++ b/Documentation/decisions/008-Inter-VM-communication-mechanisms.adoc @@ -0,0 +1,18 @@ +### Inter VM communication mechanisms + +### Status +Proposed + +### Context +Guest VM software needs to communicate with software in other guest VMs + +### Decision +Spectrum provides two mechanism +- TCP/IP with virtio-net +- Wayland with virtio-gpu (nevermind the semantics) for streamed IPC protocol to + send references to shared memory + + +### Consequences +- Examples required on how to write applications which communicate over + virtio-gpu -- 2.36.0