AB#2425 Constellation mini docs (#214)

Signed-off-by: Daniel Weiße <dw@edgeless.systems>

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

@@ -1,6 +1,8 @@
 # First steps
 
-The following steps guide you through the process of creating a cluster and deploying a sample app. This example assumes that you have successfully [installed and set up Constellation](install.md).
+The following steps guide you through the process of creating a cluster and deploying a sample app. This example assumes that you have successfully [installed and set up Constellation](install.md),
+and have access to a cloud subscription.
+For setting up a local Constellation cluster, check out [mini Constellation](mini-constellation.md).
 
 ## Create a cluster
 

docs/docs/getting-started/install.md

@@ -102,6 +102,8 @@ 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.
 
+If you don't have a cloud subscription, you can try [mini Constellation](mini-constellation.md), which lets you set up a local Constellation cluster using virtualization.
+
 ### Required permissions
 
 <tabs groupId="csp">

docs/docs/getting-started/mini-constellation.md

@@ -0,0 +1,155 @@
+# Mini Constellation
+
+With `constellation mini`, users can deploy and test Constellation locally without the need for a cloud subscription.
+
+The command uses virtualization to create a local cluster with one control-plane and one worker node.
+
+:::info
+
+Since mini Constellation is running on your local system, please note that common cloud features, such as load-balancing,
+attaching persistent storage, or autoscaling, are unavailable.
+
+:::
+
+## Prerequisites
+
+* [Constellation CLI](./install.md#install-the-constellation-cli)
+* A x86-64 CPU with at least 4 cores
+  * Recommended are 6 cores or more
+* Hardware virtualization enabled in the BIOS/UEFI (often referred to as Intel VT-x or AMD-V/SVM)
+* At least 4 GB RAM
+  * Recommend are 6 GB or more
+* 20 GB of free disk space
+* a Linux operating system
+* [KVM kernel module](https://www.linux-kvm.org/page/Main_Page) enabled
+* [Docker](https://docs.docker.com/engine/install/)
+* [xsltproc](https://gitlab.gnome.org/GNOME/libxslt/-/wikis/home)
+  * Install on Ubuntu:
+
+    ```bash
+    sudo apt install xsltproc
+    ```
+
+  * Install on Fedora
+
+    ```bash
+    sudo dnf install xsltproc
+    ```
+
+* (Optional) [`virsh`](https://www.libvirt.org/manpages/virsh.html) to observe and access your nodes
+
+## Create your cluster
+
+Setting up your mini Constellation cluster is as easy as running the following command:
+
+```bash
+constellation mini up
+```
+
+This will configure your current directory as the working directory for Constellation.
+All `constellation` commands concerning this cluster need to be issued from this directory.
+
+The command will create your cluster and initialize it. Depending on your system, this may take up to 10 minutes.
+The output should look like the following:
+
+```shell
+$ constellation mini up
+Downloading image to ./constellation.qcow2
+Done.
+
+Creating cluster in QEMU ...
+Cluster successfully created.
+Connect to the VMs by executing:
+        virsh -c qemu+tcp://localhost:16599/system
+
+Your Constellation master secret was successfully written to ./constellation-mastersecret.json
+Initializing cluster ...
+Your Constellation cluster was successfully initialized.
+
+Constellation cluster identifier  hmrRaTJEKHk6zlM6wcTCGxZ+7HAA16ec4T9CmKs12uQ=
+Kubernetes configuration          constellation-admin.conf
+
+You can now connect to your cluster by executing:
+        export KUBECONFIG="$PWD/constellation-admin.conf"
+```
+
+You can now configure `kubectl` to connect to your local Constellation cluster:
+
+```bash
+export KUBECONFIG="$PWD/constellation-admin.conf"
+```
+
+It may take a couple of minutes for all cluster resources to be available.
+You can check on the state of your cluster by running the following:
+
+```bash
+kubectl get nodes
+```
+
+If your cluster is running as expected the output should look like the following:
+
+```shell
+$ kubectl get nodes
+NAME              STATUS   ROLES                  AGE     VERSION
+control-plane-0   Ready    control-plane,master   2m59s   v1.23.9
+worker-0          Ready    <none>                 32s     v1.23.9
+```
+
+## Deploy a sample application
+
+1. Deploy the [emojivoto app](https://github.com/BuoyantIO/emojivoto)
+
+  ```bash
+  kubectl apply -k github.com/BuoyantIO/emojivoto/kustomize/deployment
+  ```
+
+2. Expose the frontend service locally
+
+  ```bash
+  kubectl wait --for=condition=available --timeout=60s -n emojivoto --all deployments
+  kubectl -n emojivoto port-forward svc/web-svc 8080:80 &
+  curl http://localhost:8080
+  kill %1
+  ```
+
+## Terminate your cluster
+
+Once you are done, you can clean up the created resources using the following command:
+
+```shell
+constellation mini down
+```
+
+This will destroy your cluster and clean up the your working directory.
+The VM image and cluster configuration file (`constellation-conf.yaml`) will be left behind and may be reused to create new clusters.
+
+## Troubleshooting
+
+### VMs have no internet access
+
+`iptables` rules may prevent your VMs form properly accessing the internet.
+Make sure your rules are'nt dropping forwarded packages.
+
+List your rules:
+
+```shell
+sudo iptables -S
+```
+
+The output may look similar to the following:
+
+```shell
+-P INPUT ACCEPT
+-P FORWARD DROP
+-P OUTPUT ACCEPT
+-N DOCKER
+-N DOCKER-ISOLATION-STAGE-1
+-N DOCKER-ISOLATION-STAGE-2
+-N DOCKER-USER
+```
+
+If your `FORWARD` chain is set to `DROP`, you will need to update your rules:
+
+```shell
+sudo iptables -P FORWARD ACCEPT
+```

docs/sidebars.js

@@ -79,6 +79,11 @@ const sidebars = {
           label: 'First steps',
           id: 'getting-started/first-steps',
         },
+        {
+          type: 'doc',
+          label: 'Mini Constellation',
+          id: 'getting-started/mini-constellation',
+        },
         {
           type: 'category',
           label: 'Examples',

docs/styles/Vocab/constellation/accept.txt

@@ -42,3 +42,4 @@ WireGuard
 Xeon
 Nginx
 rollout
+xsltproc