Git-Mirrors/constellation
1
0
Fork 0
mirror of https://github.com/edgelesssys/constellation.git synced 2024-12-24 23:19:39 -05:00
Code Issues Packages Projects Releases Wiki Activity

Brush over MiniConstellation in docs and README (#285)

Browse Source 
* Pass over mini-constellation
* Update version 2.1
* Update README
This commit is contained in:
Felix Schuster 2022-10-17 16:41:56 +02:00 committed by GitHub
parent dd95b83e2b
commit c4d8fa54a6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
15 changed files with 308 additions and 410 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
README.md
View File

@ -56,14 +56,15 @@ Encrypting your K8s is good for:
<a href="https://landscape.cncf.io/?selected=constellation"><img src="https://raw.githubusercontent.com/cncf/artwork/1c1a10d9cc7de24235e07c8831923874331ef233/projects/kubernetes/certified-kubernetes/versionless/color/certified-kubernetes-color.svg" align="right" width="100px"></a> <a href="https://landscape.cncf.io/?selected=constellation"><img src="https://raw.githubusercontent.com/cncf/artwork/1c1a10d9cc7de24235e07c8831923874331ef233/projects/kubernetes/certified-kubernetes/versionless/color/certified-kubernetes-color.svg" align="right" width="100px"></a>
* 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. * 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 ## Getting started
If you're already familiar with Kubernetes, it's easy to get started with Constellation: If you're already familiar with Kubernetes, it's easy to get started with Constellation:
1. 📦 [Install the CLI][install] 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] 3. 🏎️ [Run your app][examples]
![Constellation Shell](docs/static/img/shell-windowframe.svg) ![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 [confidential-kubernetes]: https://docs.edgeless.systems/constellation/overview/confidential-kubernetes
[discord]: https://discord.gg/rH8QTH56JN [discord]: https://discord.gg/rH8QTH56JN
[enterprise-support]: https://www.edgeless.systems/products/constellation/ [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 [documentation]: https://docs.edgeless.systems/constellation/latest
[examples]: https://docs.edgeless.systems/constellation/getting-started/examples [examples]: https://docs.edgeless.systems/constellation/getting-started/examples
[github-issues]: https://github.com/edgelesssys/constellation/issues [github-issues]: https://github.com/edgelesssys/constellation/issues

143
docs/docs/getting-started/first-steps-local.md Normal file
View File

@ -0,0 +1,143 @@
# First steps with MiniConstellation
<!-- 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 -->
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 <none> 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
```

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

@ -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), 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. and have access to a cloud subscription.
:::tip :::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 ## Create a cluster

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. The CLI makes authenticated calls to the CSP API. Therefore, you need to set up Constellation with the credentials for your CSP.
:::tip :::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 ### Required permissions

197
docs/docs/getting-started/mini-constellation.md
View File

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

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

@ -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. See the [architecture](../architecture/orchestration.md) section for details on the inner workings of this process.
:::tip :::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 ## The *create* step

2
docs/sidebars.js
View File

@ -82,7 +82,7 @@ const sidebars = {
{ {
type: 'doc', type: 'doc',
label: 'First steps (local)', label: 'First steps (local)',
id: 'getting-started/mini-constellation', id: 'getting-started/first-steps-local',
}, },
{ {
type: 'category', type: 'category',

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

@ -21,25 +21,29 @@ Gbps
iam iam
IAM IAM
initramfs initramfs
[Kk]3s
Kata Kata
kubeadm kubeadm
kubectl kubectl
kubelet kubelet
libcryptsetup libcryptsetup
MicroK8s
[Mm]inikube
namespace namespace
Nginx
[Pp]laintext [Pp]laintext
Rekor Rekor
resizable resizable
rollout
sigstore sigstore
systemd systemd
[Uu]nencrypted [Uu]nencrypted
unspoofable unspoofable
updatable updatable
proxied proxied
virsh
[Ww]alkthrough [Ww]alkthrough
whitepaper whitepaper
WireGuard WireGuard
Xeon Xeon
Nginx
rollout
xsltproc xsltproc

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

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

143
docs/versioned_docs/version-2.1/getting-started/first-steps-local.md Normal file
View File

@ -0,0 +1,143 @@
# First steps with MiniConstellation
<!-- 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 -->
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 <none> 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
```

4
docs/versioned_docs/version-2.1/getting-started/first-steps.md
View File

@ -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), 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. and have access to a cloud subscription.
:::tip :::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 ## Create a cluster

2
docs/versioned_docs/version-2.1/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. The CLI makes authenticated calls to the CSP API. Therefore, you need to set up Constellation with the credentials for your CSP.
:::tip :::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 ### Required permissions

197
docs/versioned_docs/version-2.1/getting-started/mini-constellation.md
View File

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

2
docs/versioned_docs/version-2.1/workflows/create.md
View File

@ -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. See the [architecture](../architecture/orchestration.md) section for details on the inner workings of this process.
:::tip :::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 ## The *create* step

2
docs/versioned_sidebars/version-2.1-sidebars.json
View File

@ -64,7 +64,7 @@
{ {
"type": "doc", "type": "doc",
"label": "First steps (local)", "label": "First steps (local)",
"id": "getting-started/mini-constellation" "id": "getting-started/first-steps-local"
}, },
{ {
"type": "category", "type": "category",