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",