Git-Mirrors/constellation
1
0
Fork 0
mirror of https://github.com/edgelesssys/constellation.git synced 2024-10-01 01:36:09 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: add a qemu section (#1724)

Browse Source
This commit is contained in:
miampf 2023-05-17 13:21:35 +00:00 committed by GitHub
parent 6252193879
commit e7b7a544f0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 180 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
dev-docs/workflows/qemu.md
View File

@ -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

166
docs/docs/getting-started/first-steps-local.md
View File

@ -1,23 +1,11 @@
# First steps with MiniConstellation
# First steps with a local cluster
<!-- vale off -->
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/).
<!-- vale on -->
A local cluster lets you deploy and test Constellation without a cloud subscription.
You have two options:
* 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.
:::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.
:::
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.
## 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
export KUBECONFIG="$PWD/constellation-admin.conf"
```
:::caution
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).

2
docs/docs/getting-started/first-steps.md
View File

@ -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

2
docs/docs/getting-started/install.md
View File

@ -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

2
docs/docs/workflows/create.md
View File

@ -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

1
docs/styles/Vocab/constellation/accept.txt
View File

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

2
rfc/reproducible-builds.md
View File

@ -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