mirror of
https://github.com/edgelesssys/constellation.git
synced 2024-09-19 15:56:03 +00:00
Brush over MiniConstellation in docs and README (#285)
* Pass over mini-constellation * Update version 2.1 * Update README
This commit is contained in:
Felix Schuster
GitHub
parent
dd95b83e2b
commit
c4d8fa54a6
@ -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>
|
||||
|
||||
* 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]
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
143
docs/docs/getting-started/first-steps-local.md
Normal file
143
docs/docs/getting-started/first-steps-local.md
Normal 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
|
||||
```
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
```
|
||||
@ -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
|
||||
|
||||
@ -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',
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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).
|
||||
|
||||
|
||||
@ -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
|
||||
```
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
```
|
||||
@ -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
|
||||
|
||||
@ -64,7 +64,7 @@
|
||||
{
|
||||
"type": "doc",
|
||||
"label": "First steps (local)",
|
||||
"id": "getting-started/mini-constellation"
|
||||
"id": "getting-started/first-steps-local"
|
||||
},
|
||||
{
|
||||
"type": "category",
|
||||
|
||||
Loading…
Reference in New Issue
Block a user