From: Ville Ilvonen <ville.ilvonen@unikie.com>
To: devel@spectrum-os.org
Cc: Ville Ilvonen <ville.ilvonen@unikie.com>
Subject: [PATCH] Documentation: Architecture Decision Record
Date: Fri, 8 Jul 2022 14:02:15 +0300 [thread overview]
Message-ID: <20220708110215.92996-1-ville.ilvonen@unikie.com> (raw)
* 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
next reply other threads:[~2022-07-08 11:02 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-07-08 11:02 Ville Ilvonen [this message]
2022-07-12 18:11 ` Alyssa Ross
2022-07-13 9:35 ` Ville Ilvonen
2022-07-13 9:53 ` Alyssa Ross
2022-07-13 11:04 ` Ville Ilvonen
2022-07-22 11:32 ` Alyssa Ross
2022-07-22 11:37 ` Alyssa Ross
2022-07-13 10:04 ` Alyssa Ross
2023-01-03 7:03 ` Adam Joseph
2023-01-06 13:27 ` Alyssa Ross
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20220708110215.92996-1-ville.ilvonen@unikie.com \
--to=ville.ilvonen@unikie.com \
--cc=devel@spectrum-os.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://spectrum-os.org/git/crosvm
https://spectrum-os.org/git/doc
https://spectrum-os.org/git/mktuntap
https://spectrum-os.org/git/nixpkgs
https://spectrum-os.org/git/spectrum
https://spectrum-os.org/git/ucspi-vsock
https://spectrum-os.org/git/www
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).