From c4d8fa54a6c0b91d8b4ccaf62dc852a2e9ac6d18 Mon Sep 17 00:00:00 2001
From: Felix Schuster <1911679+flxflx@users.noreply.github.com>
Date: Mon, 17 Oct 2022 16:41:56 +0200
Subject: [PATCH] Brush over MiniConstellation in docs and README (#285)
* Pass over mini-constellation
* Update version 2.1
* Update README
---
README.md | 8 +-
.../docs/getting-started/first-steps-local.md | 143 +++++++++++++
docs/docs/getting-started/first-steps.md | 4 +-
docs/docs/getting-started/install.md | 2 +-
.../getting-started/mini-constellation.md | 197 ------------------
docs/docs/workflows/create.md | 2 +-
docs/sidebars.js | 2 +-
docs/styles/Vocab/constellation/accept.txt | 8 +-
.../getting-started/first-steps.md | 2 +-
.../getting-started/first-steps-local.md | 143 +++++++++++++
.../getting-started/first-steps.md | 4 +-
.../version-2.1/getting-started/install.md | 2 +-
.../getting-started/mini-constellation.md | 197 ------------------
.../version-2.1/workflows/create.md | 2 +-
.../version-2.1-sidebars.json | 2 +-
15 files changed, 308 insertions(+), 410 deletions(-)
create mode 100644 docs/docs/getting-started/first-steps-local.md
delete mode 100644 docs/docs/getting-started/mini-constellation.md
create mode 100644 docs/versioned_docs/version-2.1/getting-started/first-steps-local.md
delete mode 100644 docs/versioned_docs/version-2.1/getting-started/mini-constellation.md
diff --git a/README.md b/README.md
index 0391f3a5c..f9d097376 100644
--- a/README.md
+++ b/README.md
@@ -56,14 +56,15 @@ Encrypting your K8s is good for:
* Constellation is a [CNCF-certified][certified] Kubernetes. It's aligned to Kubernetes' [version support policy][k8s-version-support] and will likely work with your existing workloads and tools.
-* Support for Azure and GCP, more to come.
+* Support for Azure and GCP (more to come).
+* Support for local installations with [MiniConstellation][first-steps-local].
## Getting started
If you're already familiar with Kubernetes, it's easy to get started with Constellation:
1. 📦 [Install the CLI][install]
-2. ⌨️ [Create a Constellation cluster][create-cluster]
+2. ⌨️ Create a Constellation cluster in the [cloud][first-steps] or [locally][first-steps-local]
3. 🏎️ [Run your app][examples]
![Constellation Shell](docs/static/img/shell-windowframe.svg)
@@ -104,7 +105,8 @@ The Constellation source code is licensed under the [GNU Affero General Public L
[confidential-kubernetes]: https://docs.edgeless.systems/constellation/overview/confidential-kubernetes
[discord]: https://discord.gg/rH8QTH56JN
[enterprise-support]: https://www.edgeless.systems/products/constellation/
-[create-cluster]: https://docs.edgeless.systems/constellation/workflows/create
+[first-steps]: https://docs.edgeless.systems/constellation/getting-started/first-steps
+[first-steps-local]: https://docs.edgeless.systems/constellation/getting-started/first-steps-local
[documentation]: https://docs.edgeless.systems/constellation/latest
[examples]: https://docs.edgeless.systems/constellation/getting-started/examples
[github-issues]: https://github.com/edgelesssys/constellation/issues
diff --git a/docs/docs/getting-started/first-steps-local.md b/docs/docs/getting-started/first-steps-local.md
new file mode 100644
index 000000000..cc7638025
--- /dev/null
+++ b/docs/docs/getting-started/first-steps-local.md
@@ -0,0 +1,143 @@
+# First steps with MiniConstellation
+
+
+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/).
+
+
+MiniConstellation uses virtualization to create a local cluster with one control-plane node and one worker node.
+
+:::info
+
+MiniConstellation **doesn't** require hardware with Confidential VM (CVM) support.
+For attestation, MiniConstellation currently uses the software-based vTPM provided by KVM/QEMU.
+
+:::
+
+:::note
+
+Since MiniConstellation runs on your local system, cloud features such as load balancing,
+attaching persistent storage, or autoscaling aren't available.
+
+:::
+
+## Prerequisites
+
+* A Linux OS with the following components installed
+ * [Constellation CLI](./install.md#install-the-constellation-cli)
+ * [KVM kernel module](https://www.linux-kvm.org/page/Main_Page)
+ * [Docker](https://docs.docker.com/engine/install/)
+ * [xsltproc](https://gitlab.gnome.org/GNOME/libxslt/-/wikis/home)
+ * (Optional) [virsh](https://www.libvirt.org/manpages/virsh.html) to observe and access your nodes
+* Other system requirements
+ * An x86-64 CPU with at least 4 cores (6 cores are recommended)
+ * At least 4 GB RAM (6 GB are recommended)
+ * 20 GB of free disk space
+ * Hardware virtualization enabled in the BIOS/UEFI (often referred to as Intel VT-x or AMD-V/SVM)
+
+## Create your cluster
+
+The following creates your MiniConstellation cluster (may take up to 10 minutes to complete):
+
+```bash
+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`
+
+Configure `kubectl` to connect to your local Constellation cluster:
+
+```bash
+export KUBECONFIG="$PWD/constellation-admin.conf"
+```
+
+Your cluster initially consists of a single control-plane node:
+
+```shell-session
+$ kubectl get nodes
+NAME STATUS ROLES AGE VERSION
+control-plane-0 Ready control-plane 66s v1.24.6
+```
+
+A worker node will request to join the cluster shortly. Before the new worker node is allowed to join the cluster, its state is verified using remote attestation by the [JoinService](../architecture/components.md#joinservice).
+If verification passes successfully, the new node receives keys and certificates to join the cluster.
+
+You can follow this process by viewing the logs of the JoinService:
+
+```shell-session
+$ kubectl logs -n kube-system daemonsets/join-service -f
+{"level":"INFO","ts":"2022-10-14T09:32:20Z","caller":"cmd/main.go:48","msg":"Constellation Node Join Service","version":"2.1.0","cloudProvider":"qemu"}
+{"level":"INFO","ts":"2022-10-14T09:32:20Z","logger":"validator","caller":"watcher/validator.go:96","msg":"Updating expected measurements"}
+...
+```
+
+Once the worker node has joined your cluster, it may take a couple of minutes for all resources to become available.
+You can check on the state of your cluster by running the following:
+
+```shell-session
+$ kubectl get nodes
+NAME STATUS ROLES AGE VERSION
+control-plane-0 Ready control-plane 2m59s v1.24.6
+worker-0 Ready 32s v1.24.6
+```
+
+## 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:
+
+```bash
+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.
+
+## Troubleshooting
+
+### VMs have no internet access
+
+`iptables` rules may prevent your VMs from accessing the internet.
+Make sure your rules aren't dropping forwarded packages.
+
+List your rules:
+
+```bash
+sudo iptables -S
+```
+
+The output may look similar to the following:
+
+```shell-session
+-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 need to update your rules:
+
+```bash
+sudo iptables -P FORWARD ACCEPT
+```
diff --git a/docs/docs/getting-started/first-steps.md b/docs/docs/getting-started/first-steps.md
index 49445b89f..7e15a2cc9 100644
--- a/docs/docs/getting-started/first-steps.md
+++ b/docs/docs/getting-started/first-steps.md
@@ -1,10 +1,10 @@
-# First steps
+# First steps with Constellation
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.
:::tip
-If you don't have a cloud subscription, check out [MiniConstellation](mini-constellation.md), which lets you set up a local Constellation cluster using virtualization.
+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.
:::
## Create a cluster
diff --git a/docs/docs/getting-started/install.md b/docs/docs/getting-started/install.md
index bdd602d26..56029b806 100644
--- a/docs/docs/getting-started/install.md
+++ b/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](mini-constellation.md), which lets you set up a local Constellation cluster using virtualization.
+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.
:::
### Required permissions
diff --git a/docs/docs/getting-started/mini-constellation.md b/docs/docs/getting-started/mini-constellation.md
deleted file mode 100644
index e76d240ff..000000000
--- a/docs/docs/getting-started/mini-constellation.md
+++ /dev/null
@@ -1,197 +0,0 @@
-# MiniConstellation
-
-With `constellation mini`, you can deploy and test Constellation locally without a cloud subscription.
-
-The command uses virtualization to create a local cluster with one control-plane and one worker node.
-
-:::info
-
-Since MiniConstellation is running on your local system, common cloud features, such as load-balancing,
-attaching persistent storage, or autoscaling, are unavailable.
-
-:::
-
-## Prerequisites
-
-* [Constellation CLI](./install.md#install-the-constellation-cli)
-* An 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 MiniConstellation cluster is as easy as running the following command:
-
-```bash
-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.
-
-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-session
-$ 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"
-```
-
-Configure `kubectl` to connect to your local Constellation cluster:
-
-```bash
-export KUBECONFIG="$PWD/constellation-admin.conf"
-```
-
-Your cluster initially consists of a single control-plane node:
-
-```shell-session
-$ kubectl get nodes
-NAME STATUS ROLES AGE VERSION
-control-plane-0 Ready control-plane 66s v1.24.6
-```
-
-A worker node will request to join the cluster shortly.
-
-Before the new worker node is allowed to join the cluster, its state is verified using remote attestation by the [JoinService](../architecture/components.md#joinservice).
-If verification passes successfully, the new node receives keys and certificates to join the cluster.
-
-You can follow this process by viewing the logs of the JoinService:
-
-```shell-session
-$ kubectl logs -n kube-system daemonsets/join-service -f
-{"level":"INFO","ts":"2022-10-14T09:32:20Z","caller":"cmd/main.go:48","msg":"Constellation Node Join Service","version":"2.1.0","cloudProvider":"qemu"}
-{"level":"INFO","ts":"2022-10-14T09:32:20Z","logger":"validator","caller":"watcher/validator.go:96","msg":"Updating expected measurements"}
-{"level":"INFO","ts":"2022-10-14T09:32:20Z","logger":"server","caller":"server/server.go:73","msg":"Starting join service on [::]:9090"}
-{"level":"INFO","ts":"2022-10-14T09:32:20Z","caller":"cmd/main.go:103","msg":"starting file watcher for measurements file /var/config/measurements"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"server","caller":"server/server.go:86","msg":"IssueJoinTicket called","peerAddress":"10.42.2.100:59988"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"server","caller":"server/server.go:88","msg":"Requesting measurement secret","peerAddress":"10.42.2.100:59988"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kms","caller":"kms/kms.go:41","msg":"Connecting to KMS at kms.kube-system:9000","keyID":"measurementSecret","endpoint":"kms.kube-system:9000"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kms","caller":"kms/kms.go:48","msg":"Requesting data key","keyID":"measurementSecret","endpoint":"kms.kube-system:9000"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kms","caller":"kms/kms.go:61","msg":"Data key request successful","keyID":"measurementSecret","endpoint":"kms.kube-system:9000"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"server","caller":"server/server.go:95","msg":"Requesting disk encryption key","peerAddress":"10.42.2.100:59988"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kms","caller":"kms/kms.go:41","msg":"Connecting to KMS at kms.kube-system:9000","keyID":"0f87c61f-31e7-466d-be22-e7300e7d9e76","endpoint":"kms.kube-system:9000"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kms","caller":"kms/kms.go:48","msg":"Requesting data key","keyID":"0f87c61f-31e7-466d-be22-e7300e7d9e76","endpoint":"kms.kube-system:9000"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kms","caller":"kms/kms.go:61","msg":"Data key request successful","keyID":"0f87c61f-31e7-466d-be22-e7300e7d9e76","endpoint":"kms.kube-system:9000"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"server","caller":"server/server.go:102","msg":"Creating Kubernetes join token","peerAddress":"10.42.2.100:59988"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kubeadm","caller":"kubeadm/kubeadm.go:63","msg":"Generating new random bootstrap token"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kubeadm","caller":"kubeadm/kubeadm.go:81","msg":"Creating bootstrap token in Kubernetes"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kubeadm","caller":"kubeadm/kubeadm.go:87","msg":"Preparing join token for new node"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kubeadm","caller":"kubeadm/kubeadm.go:109","msg":"Join token creation successful"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"server","caller":"server/server.go:109","msg":"Querying K8sVersion ConfigMap","peerAddress":"10.42.2.100:59988"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"server","caller":"server/server.go:115","msg":"Creating signed kubelet certificate","peerAddress":"10.42.2.100:59988"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"certificateAuthority","caller":"kubernetesca/kubernetesca.go:84","msg":"Creating kubelet certificate"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"server","caller":"server/server.go:138","msg":"IssueJoinTicket successful","peerAddress":"10.42.2.100:59988"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"server.gRPC","caller":"zap/server_interceptors.go:39","msg":"finished unary call with code OK","grpc.start_time":"2022-10-14T09:32:21Z","grpc.request.deadline":"2022-10-14T09:32:51Z","system":"grpc","span.kind":"server","grpc.service":"join.API","grpc.method":"IssueJoinTicket","peer.address":"10.42.2.100:59988","grpc.code":"OK","grpc.time_ms":27.715}
-```
-
-Once the worker node has joined your cluster, it may take a couple of minutes for all 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-session
-$ kubectl get nodes
-NAME STATUS ROLES AGE VERSION
-control-plane-0 Ready control-plane 2m59s v1.24.6
-worker-0 Ready 32s v1.24.6
-```
-
-## 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:
-
-```bash
-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.
-
-## Troubleshooting
-
-### VMs have no internet access
-
-`iptables` rules may prevent your VMs from accessing the internet.
-Make sure your rules aren't dropping forwarded packages.
-
-List your rules:
-
-```bash
-sudo iptables -S
-```
-
-The output may look similar to the following:
-
-```shell-session
--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 need to update your rules:
-
-```bash
-sudo iptables -P FORWARD ACCEPT
-```
diff --git a/docs/docs/workflows/create.md b/docs/docs/workflows/create.md
index 4c587603c..a567c5d23 100644
--- a/docs/docs/workflows/create.md
+++ b/docs/docs/workflows/create.md
@@ -8,7 +8,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/mini-constellation.md), which lets you set up a local Constellation cluster using virtualization.
+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.
:::
## The *create* step
diff --git a/docs/sidebars.js b/docs/sidebars.js
index f85b27b43..d845c0921 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -82,7 +82,7 @@ const sidebars = {
{
type: 'doc',
label: 'First steps (local)',
- id: 'getting-started/mini-constellation',
+ id: 'getting-started/first-steps-local',
},
{
type: 'category',
diff --git a/docs/styles/Vocab/constellation/accept.txt b/docs/styles/Vocab/constellation/accept.txt
index e5480f2ba..4715a81ba 100644
--- a/docs/styles/Vocab/constellation/accept.txt
+++ b/docs/styles/Vocab/constellation/accept.txt
@@ -21,25 +21,29 @@ Gbps
iam
IAM
initramfs
+[Kk]3s
Kata
kubeadm
kubectl
kubelet
libcryptsetup
+MicroK8s
+[Mm]inikube
namespace
+Nginx
[Pp]laintext
Rekor
resizable
+rollout
sigstore
systemd
[Uu]nencrypted
unspoofable
updatable
proxied
+virsh
[Ww]alkthrough
whitepaper
WireGuard
Xeon
-Nginx
-rollout
xsltproc
diff --git a/docs/versioned_docs/version-2.0/getting-started/first-steps.md b/docs/versioned_docs/version-2.0/getting-started/first-steps.md
index a96641ab8..c1ea63679 100644
--- a/docs/versioned_docs/version-2.0/getting-started/first-steps.md
+++ b/docs/versioned_docs/version-2.0/getting-started/first-steps.md
@@ -1,4 +1,4 @@
-# First steps
+# First steps (cloud)
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).
diff --git a/docs/versioned_docs/version-2.1/getting-started/first-steps-local.md b/docs/versioned_docs/version-2.1/getting-started/first-steps-local.md
new file mode 100644
index 000000000..cc7638025
--- /dev/null
+++ b/docs/versioned_docs/version-2.1/getting-started/first-steps-local.md
@@ -0,0 +1,143 @@
+# First steps with MiniConstellation
+
+
+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/).
+
+
+MiniConstellation uses virtualization to create a local cluster with one control-plane node and one worker node.
+
+:::info
+
+MiniConstellation **doesn't** require hardware with Confidential VM (CVM) support.
+For attestation, MiniConstellation currently uses the software-based vTPM provided by KVM/QEMU.
+
+:::
+
+:::note
+
+Since MiniConstellation runs on your local system, cloud features such as load balancing,
+attaching persistent storage, or autoscaling aren't available.
+
+:::
+
+## Prerequisites
+
+* A Linux OS with the following components installed
+ * [Constellation CLI](./install.md#install-the-constellation-cli)
+ * [KVM kernel module](https://www.linux-kvm.org/page/Main_Page)
+ * [Docker](https://docs.docker.com/engine/install/)
+ * [xsltproc](https://gitlab.gnome.org/GNOME/libxslt/-/wikis/home)
+ * (Optional) [virsh](https://www.libvirt.org/manpages/virsh.html) to observe and access your nodes
+* Other system requirements
+ * An x86-64 CPU with at least 4 cores (6 cores are recommended)
+ * At least 4 GB RAM (6 GB are recommended)
+ * 20 GB of free disk space
+ * Hardware virtualization enabled in the BIOS/UEFI (often referred to as Intel VT-x or AMD-V/SVM)
+
+## Create your cluster
+
+The following creates your MiniConstellation cluster (may take up to 10 minutes to complete):
+
+```bash
+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`
+
+Configure `kubectl` to connect to your local Constellation cluster:
+
+```bash
+export KUBECONFIG="$PWD/constellation-admin.conf"
+```
+
+Your cluster initially consists of a single control-plane node:
+
+```shell-session
+$ kubectl get nodes
+NAME STATUS ROLES AGE VERSION
+control-plane-0 Ready control-plane 66s v1.24.6
+```
+
+A worker node will request to join the cluster shortly. Before the new worker node is allowed to join the cluster, its state is verified using remote attestation by the [JoinService](../architecture/components.md#joinservice).
+If verification passes successfully, the new node receives keys and certificates to join the cluster.
+
+You can follow this process by viewing the logs of the JoinService:
+
+```shell-session
+$ kubectl logs -n kube-system daemonsets/join-service -f
+{"level":"INFO","ts":"2022-10-14T09:32:20Z","caller":"cmd/main.go:48","msg":"Constellation Node Join Service","version":"2.1.0","cloudProvider":"qemu"}
+{"level":"INFO","ts":"2022-10-14T09:32:20Z","logger":"validator","caller":"watcher/validator.go:96","msg":"Updating expected measurements"}
+...
+```
+
+Once the worker node has joined your cluster, it may take a couple of minutes for all resources to become available.
+You can check on the state of your cluster by running the following:
+
+```shell-session
+$ kubectl get nodes
+NAME STATUS ROLES AGE VERSION
+control-plane-0 Ready control-plane 2m59s v1.24.6
+worker-0 Ready 32s v1.24.6
+```
+
+## 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:
+
+```bash
+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.
+
+## Troubleshooting
+
+### VMs have no internet access
+
+`iptables` rules may prevent your VMs from accessing the internet.
+Make sure your rules aren't dropping forwarded packages.
+
+List your rules:
+
+```bash
+sudo iptables -S
+```
+
+The output may look similar to the following:
+
+```shell-session
+-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 need to update your rules:
+
+```bash
+sudo iptables -P FORWARD ACCEPT
+```
diff --git a/docs/versioned_docs/version-2.1/getting-started/first-steps.md b/docs/versioned_docs/version-2.1/getting-started/first-steps.md
index 49445b89f..7e15a2cc9 100644
--- a/docs/versioned_docs/version-2.1/getting-started/first-steps.md
+++ b/docs/versioned_docs/version-2.1/getting-started/first-steps.md
@@ -1,10 +1,10 @@
-# First steps
+# First steps with Constellation
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.
:::tip
-If you don't have a cloud subscription, check out [MiniConstellation](mini-constellation.md), which lets you set up a local Constellation cluster using virtualization.
+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.
:::
## Create a cluster
diff --git a/docs/versioned_docs/version-2.1/getting-started/install.md b/docs/versioned_docs/version-2.1/getting-started/install.md
index bdd602d26..56029b806 100644
--- a/docs/versioned_docs/version-2.1/getting-started/install.md
+++ b/docs/versioned_docs/version-2.1/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](mini-constellation.md), which lets you set up a local Constellation cluster using virtualization.
+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.
:::
### Required permissions
diff --git a/docs/versioned_docs/version-2.1/getting-started/mini-constellation.md b/docs/versioned_docs/version-2.1/getting-started/mini-constellation.md
deleted file mode 100644
index e76d240ff..000000000
--- a/docs/versioned_docs/version-2.1/getting-started/mini-constellation.md
+++ /dev/null
@@ -1,197 +0,0 @@
-# MiniConstellation
-
-With `constellation mini`, you can deploy and test Constellation locally without a cloud subscription.
-
-The command uses virtualization to create a local cluster with one control-plane and one worker node.
-
-:::info
-
-Since MiniConstellation is running on your local system, common cloud features, such as load-balancing,
-attaching persistent storage, or autoscaling, are unavailable.
-
-:::
-
-## Prerequisites
-
-* [Constellation CLI](./install.md#install-the-constellation-cli)
-* An 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 MiniConstellation cluster is as easy as running the following command:
-
-```bash
-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.
-
-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-session
-$ 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"
-```
-
-Configure `kubectl` to connect to your local Constellation cluster:
-
-```bash
-export KUBECONFIG="$PWD/constellation-admin.conf"
-```
-
-Your cluster initially consists of a single control-plane node:
-
-```shell-session
-$ kubectl get nodes
-NAME STATUS ROLES AGE VERSION
-control-plane-0 Ready control-plane 66s v1.24.6
-```
-
-A worker node will request to join the cluster shortly.
-
-Before the new worker node is allowed to join the cluster, its state is verified using remote attestation by the [JoinService](../architecture/components.md#joinservice).
-If verification passes successfully, the new node receives keys and certificates to join the cluster.
-
-You can follow this process by viewing the logs of the JoinService:
-
-```shell-session
-$ kubectl logs -n kube-system daemonsets/join-service -f
-{"level":"INFO","ts":"2022-10-14T09:32:20Z","caller":"cmd/main.go:48","msg":"Constellation Node Join Service","version":"2.1.0","cloudProvider":"qemu"}
-{"level":"INFO","ts":"2022-10-14T09:32:20Z","logger":"validator","caller":"watcher/validator.go:96","msg":"Updating expected measurements"}
-{"level":"INFO","ts":"2022-10-14T09:32:20Z","logger":"server","caller":"server/server.go:73","msg":"Starting join service on [::]:9090"}
-{"level":"INFO","ts":"2022-10-14T09:32:20Z","caller":"cmd/main.go:103","msg":"starting file watcher for measurements file /var/config/measurements"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"server","caller":"server/server.go:86","msg":"IssueJoinTicket called","peerAddress":"10.42.2.100:59988"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"server","caller":"server/server.go:88","msg":"Requesting measurement secret","peerAddress":"10.42.2.100:59988"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kms","caller":"kms/kms.go:41","msg":"Connecting to KMS at kms.kube-system:9000","keyID":"measurementSecret","endpoint":"kms.kube-system:9000"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kms","caller":"kms/kms.go:48","msg":"Requesting data key","keyID":"measurementSecret","endpoint":"kms.kube-system:9000"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kms","caller":"kms/kms.go:61","msg":"Data key request successful","keyID":"measurementSecret","endpoint":"kms.kube-system:9000"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"server","caller":"server/server.go:95","msg":"Requesting disk encryption key","peerAddress":"10.42.2.100:59988"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kms","caller":"kms/kms.go:41","msg":"Connecting to KMS at kms.kube-system:9000","keyID":"0f87c61f-31e7-466d-be22-e7300e7d9e76","endpoint":"kms.kube-system:9000"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kms","caller":"kms/kms.go:48","msg":"Requesting data key","keyID":"0f87c61f-31e7-466d-be22-e7300e7d9e76","endpoint":"kms.kube-system:9000"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kms","caller":"kms/kms.go:61","msg":"Data key request successful","keyID":"0f87c61f-31e7-466d-be22-e7300e7d9e76","endpoint":"kms.kube-system:9000"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"server","caller":"server/server.go:102","msg":"Creating Kubernetes join token","peerAddress":"10.42.2.100:59988"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kubeadm","caller":"kubeadm/kubeadm.go:63","msg":"Generating new random bootstrap token"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kubeadm","caller":"kubeadm/kubeadm.go:81","msg":"Creating bootstrap token in Kubernetes"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kubeadm","caller":"kubeadm/kubeadm.go:87","msg":"Preparing join token for new node"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"kubeadm","caller":"kubeadm/kubeadm.go:109","msg":"Join token creation successful"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"server","caller":"server/server.go:109","msg":"Querying K8sVersion ConfigMap","peerAddress":"10.42.2.100:59988"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"server","caller":"server/server.go:115","msg":"Creating signed kubelet certificate","peerAddress":"10.42.2.100:59988"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"certificateAuthority","caller":"kubernetesca/kubernetesca.go:84","msg":"Creating kubelet certificate"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"server","caller":"server/server.go:138","msg":"IssueJoinTicket successful","peerAddress":"10.42.2.100:59988"}
-{"level":"INFO","ts":"2022-10-14T09:32:21Z","logger":"server.gRPC","caller":"zap/server_interceptors.go:39","msg":"finished unary call with code OK","grpc.start_time":"2022-10-14T09:32:21Z","grpc.request.deadline":"2022-10-14T09:32:51Z","system":"grpc","span.kind":"server","grpc.service":"join.API","grpc.method":"IssueJoinTicket","peer.address":"10.42.2.100:59988","grpc.code":"OK","grpc.time_ms":27.715}
-```
-
-Once the worker node has joined your cluster, it may take a couple of minutes for all 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-session
-$ kubectl get nodes
-NAME STATUS ROLES AGE VERSION
-control-plane-0 Ready control-plane 2m59s v1.24.6
-worker-0 Ready 32s v1.24.6
-```
-
-## 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:
-
-```bash
-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.
-
-## Troubleshooting
-
-### VMs have no internet access
-
-`iptables` rules may prevent your VMs from accessing the internet.
-Make sure your rules aren't dropping forwarded packages.
-
-List your rules:
-
-```bash
-sudo iptables -S
-```
-
-The output may look similar to the following:
-
-```shell-session
--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 need to update your rules:
-
-```bash
-sudo iptables -P FORWARD ACCEPT
-```
diff --git a/docs/versioned_docs/version-2.1/workflows/create.md b/docs/versioned_docs/version-2.1/workflows/create.md
index 4c587603c..a567c5d23 100644
--- a/docs/versioned_docs/version-2.1/workflows/create.md
+++ b/docs/versioned_docs/version-2.1/workflows/create.md
@@ -8,7 +8,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/mini-constellation.md), which lets you set up a local Constellation cluster using virtualization.
+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.
:::
## The *create* step
diff --git a/docs/versioned_sidebars/version-2.1-sidebars.json b/docs/versioned_sidebars/version-2.1-sidebars.json
index 760372c98..245f76d80 100644
--- a/docs/versioned_sidebars/version-2.1-sidebars.json
+++ b/docs/versioned_sidebars/version-2.1-sidebars.json
@@ -64,7 +64,7 @@
{
"type": "doc",
"label": "First steps (local)",
- "id": "getting-started/mini-constellation"
+ "id": "getting-started/first-steps-local"
},
{
"type": "category",