docs: add a qemu section (#1724)

dev-docs/workflows/qemu.md

@@ -94,6 +94,39 @@ Then restart libvirt
 sudo systemctl restart libvirtd
 ```
 
+### Connecting to a console
+
+Once you created a cluster via constellation you can connect to the virtual machines using the following commands. First, run
+
+```shell-session
+virsh -c qemu+tcp://localhost:16599/system
+```
+
+which gives you a new `virsh` shell. In this shell, you can run
+
+```shell-session
+list
+```
+
+ to see the created virtual machines, as well as their status. This should look something like this:
+
+```txt
+Id   Name                       State
+------------------------------------------
+1    constell-control-plane-0   running
+2    constell-worker-0          running
+```
+
+If you want to connect to one of those machines, run
+
+```shell-session
+console <ID>
+```
+
+where `<ID>` would be the id of your virtual machine as seen above (e.g. `1`). After that, press Enter another time and you should drop into a shell on the virtual machine.
+
+Please note that connecting via `qemu+tcp` is not encrypted and should not be used in a security relevant environment.
+
 ## Troubleshooting
 
 ### VMs are not properly cleaned up after a failed `constellation create` command

docs/docs/getting-started/first-steps-local.md

@@ -1,23 +1,11 @@
-# First steps with MiniConstellation
+# First steps with a local cluster
 
-<!-- vale off -->
+A local cluster lets you deploy and test Constellation without a cloud subscription.
-With the `constellation mini` command, you can deploy and test Constellation locally without a cloud subscription. This mode is called MiniConstellation. Conceptually, MiniConstellation is similar to [MicroK8s](https://microk8s.io/), [K3s](https://k3s.io/), and [minikube](https://minikube.sigs.k8s.io/docs/).
+You have two options:
-<!-- vale on -->
+* Use MiniConstellation to automatically deploy a two-node cluster.
+* For more fine-grained control, create the cluster using the QEMU provider.
 
-MiniConstellation uses virtualization to create a local cluster with one control-plane node and one worker node. It **doesn't** require hardware with Confidential VM (CVM) support. For attestation, MiniConstellation currently uses a software-based vTPM provided by KVM/QEMU.
+Both options use virtualization to create a local cluster with control-plane nodes and worker nodes. They **don't** require hardware with Confidential VM (CVM) support. For attestation, they currently use a software-based vTPM provided by KVM/QEMU.
-
-:::caution
-
-MiniConstellation has specific soft- and hardware requirements such as a Linux OS running on an x86-64 CPU. Pay attention to all [prerequisites](#prerequisites) when setting up.
-
-:::
-
-:::note
-
-Since MiniConstellation runs on your local system, cloud features such as load balancing,
-attaching persistent storage, or autoscaling aren't available.
-
-:::
 
 ## Prerequisites
 
@@ -39,7 +27,27 @@ attaching persistent storage, or autoscaling aren't available.
     sudo iptables -S | grep -q -- '-P FORWARD DROP'
     ```
 
-## Create your cluster
+## Create a cluster
+
+<tabs groupId="csp">
+<tabItem value="mini" label="MiniConstellation">
+
+<!-- vale off -->
+With the `constellation mini` command, you can deploy and test Constellation locally. This mode is called MiniConstellation. Conceptually, MiniConstellation is similar to [MicroK8s](https://microk8s.io/), [K3s](https://k3s.io/), and [minikube](https://minikube.sigs.k8s.io/docs/).
+<!-- vale on -->
+
+:::caution
+
+MiniConstellation has specific soft- and hardware requirements such as a Linux OS running on an x86-64 CPU. Pay attention to all [prerequisites](#prerequisites) when setting up.
+
+:::
+
+:::note
+
+Since MiniConstellation runs on your local system, cloud features such as load balancing,
+attaching persistent storage, or autoscaling aren't available.
+
+:::
 
 The following creates your MiniConstellation cluster (may take up to 10 minutes to complete):
 
@@ -50,13 +58,88 @@ constellation mini up
 This will configure your current directory as the [workspace](../architecture/orchestration.md#workspaces) for this cluster.
 All `constellation` commands concerning this cluster need to be issued from this directory.
 
-## Connect `kubectl`
+</tabItem>
+<tabItem value="qemu" label="QEMU">
 
-Configure `kubectl` to connect to your local Constellation cluster:
+With the QEMU provider, you can create a local Constellation cluster as if it were in the cloud. The provider uses [QEMU](https://www.qemu.org/) to create multiple VMs for the cluster nodes, which interact with each other.
 
-```bash
+:::caution
-export KUBECONFIG="$PWD/constellation-admin.conf"
+
-```
+Constellation on QEMU has specific soft- and hardware requirements such as a Linux OS running on an x86-64 CPU. Pay attention to all [prerequisites](#prerequisites) when setting up.
+
+:::
+
+:::note
+
+Since Constellation on QEMU runs on your local system, cloud features such as load balancing,
+attaching persistent storage, or autoscaling aren't available.
+
+:::
+
+1. To set up your local cluster, you need to create a configuration file for Constellation first.
+
+  ```bash
+  constellation config generate qemu
+  ```
+
+  This creates a [configuration file](../workflows/config.md) for QEMU called `constellation-conf.yaml`. After that, your current folder also becomes your [workspace](../architecture/orchestration.md#workspaces). All `constellation` commands for your cluster need to be executed from this directory.
+
+2. Now you can create your cluster and it's nodes. `constellation create` uses the options set in `constellation-conf.yaml`.
+
+  ```bash
+  constellation create --control-plane-nodes 1 --worker-nodes 1
+  ```
+
+  This will create 2 VMs: one worker node, and one control plane node.
+
+  The Output should look like the following:
+
+  ```shell-session
+  $ constellation create ...
+  Your Constellation cluster was created successfully.
+  ```
+
+3. Initialize the cluster
+
+  ```bash
+  constellation init
+  ```
+
+  This should give the following output:
+
+  ```shell-session
+  $ constellation init
+  Your Constellation master secret was successfully written to ./constellation-mastersecret.json
+  Initializing cluster ...
+  Your Constellation cluster was successfully initialized.
+
+  Constellation cluster identifier  g6iMP5wRU1b7mpOz2WEISlIYSfdAhB0oNaOg6XEwKFY=
+  Kubernetes configuration          constellation-admin.conf
+
+  You can now connect to your cluster by executing:
+          export KUBECONFIG="$PWD/constellation-admin.conf"
+  ```
+
+  The cluster's identifier will be different in your output.
+  Keep `constellation-mastersecret.json` somewhere safe.
+  This will allow you to [recover your cluster](../workflows/recovery.md) in case of a disaster.
+
+  :::info
+
+  Depending on your setup, `constellation init` may take 10+ minutes to complete.
+
+  :::
+
+4. Configure kubectl
+
+  ```bash
+  export KUBECONFIG="$PWD/constellation-admin.conf"
+  ```
+
+</tabItem>
+</tabs>
+
+## Connect to the cluster
 
 Your cluster initially consists of a single control-plane node:
 
@@ -107,6 +190,9 @@ worker-0          Ready    <none>          32s     v1.24.6
 
 ## Terminate your cluster
 
+<tabs groupId="csp">
+<tabItem value="mini" label="MiniConstellation">
+
 Once you are done, you can clean up the created resources using the following command:
 
 ```bash
@@ -116,6 +202,38 @@ constellation mini down
 This will destroy your cluster and clean up your workspace.
 The VM image and cluster configuration file (`constellation-conf.yaml`) will be kept and may be reused to create new clusters.
 
+</tabItem>
+<tabItem value="qemu" label="QEMU">
+
+Once you are done, you can clean up the created resources using the following command:
+
+```bash
+constellation terminate
+```
+
+This should give the following output:
+
+```shell-session
+$ constellation terminate
+You are about to terminate a Constellation cluster.
+All of its associated resources will be DESTROYED.
+This action is irreversible and ALL DATA WILL BE LOST.
+Do you want to continue? [y/n]:
+```
+
+Confirm with `y` to terminate the cluster:
+
+```shell-session
+Terminating ...
+Your Constellation cluster was terminated successfully.
+```
+
+This will destroy your cluster and clean up your workspace.
+The VM image and cluster configuration file (`constellation-conf.yaml`) will be kept and may be reused to create new clusters.
+
+</tabItem>
+</tabs>
+
 ## Troubleshooting
 
 Make sure to use the [latest release](https://github.com/edgelesssys/constellation/releases/latest) and check out the [known issues](https://github.com/edgelesssys/constellation/issues?q=is%3Aopen+is%3Aissue+label%3A%22known+issue%22).

docs/docs/getting-started/first-steps.md

@@ -4,7 +4,7 @@ The following steps guide you through the process of creating a cluster and depl
 and have access to a cloud subscription.
 
 :::tip
-If you don't have a cloud subscription, check out [MiniConstellation](first-steps-local.md), which lets you set up a local Constellation cluster using virtualization.
+If you don't have a cloud subscription, you can also set up a [local Constellation cluster using virtualization](../getting-started/first-steps-local.md) for testing.
 :::
 
 :::note

docs/docs/getting-started/install.md

@@ -103,7 +103,7 @@ The CLI supports autocompletion for various shells. To set it up, run `constella
 The CLI makes authenticated calls to the CSP API. Therefore, you need to set up Constellation with the credentials for your CSP.
 
 :::tip
-If you don't have a cloud subscription, you can try [MiniConstellation](first-steps-local.md), which lets you set up a local Constellation cluster using virtualization.
+If you don't have a cloud subscription, you can also set up a [local Constellation cluster using virtualization](../getting-started/first-steps-local.md) for testing.
 :::
 
 ### Required permissions

docs/docs/workflows/create.md

@@ -16,7 +16,7 @@ Creating your cluster requires two steps:
 See the [architecture](../architecture/orchestration.md) section for details on the inner workings of this process.
 
 :::tip
-If you don't have a cloud subscription, check out [MiniConstellation](../getting-started/first-steps-local.md), which lets you set up a local Constellation cluster using virtualization.
+If you don't have a cloud subscription, you can also set up a [local Constellation cluster using virtualization](../getting-started/first-steps-local.md) for testing.
 :::
 
 ## The *create* step

docs/styles/Vocab/constellation/accept.txt

@@ -51,6 +51,7 @@ systemd
 unspoofable
 updatable
 proxied
+QEMU
 virsh
 [Ww]alkthrough
 whitepaper

rfc/reproducible-builds.md

@@ -59,7 +59,7 @@ This seems to happen more or less regularly. We should try to avoid a build syst
 * Eliminate dependencies on libraries (make executable static)
 
 Striping metadata from the binary can be done in the building process.
-This can be achieved by setting the appropriate compiler and linker flags (see [`go tool link`](https://pkg.go.dev/cmd/link) and [`go help build`](https://pkg.go.dev/cmd/go).
+This can be achieved by setting the appropriate compiler and linker flags (see [`go tool link`](https://pkg.go.dev/cmd/link) and [`go help build`](https://pkg.go.dev/cmd/go)).
 
 * `buildvcs=false`: Omit version control information
 * `-trimpath`: Remove file system paths from executable