Git-Mirrors/constellation
1
0
Fork 0
mirror of https://github.com/edgelesssys/constellation.git synced 2024-12-28 17:09:30 -05:00
Code Issues Packages Projects Releases Wiki Activity

docs: publish

Browse Source
This commit is contained in:
Thomas Tendyck 2023-05-23 15:01:32 +02:00 committed by Thomas Tendyck
parent 050fccc591
commit 69464bca4b
8 changed files with 173 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -84,7 +84,7 @@ attaching persistent storage, or autoscaling aren't available.
This creates a [configuration file](../workflows/config.md) for QEMU called `constellation-conf.yaml`. After that, your current folder also becomes your [workspace](../architecture/orchestration.md#workspaces). All `constellation` commands for your cluster need to be executed from this directory.
2. Now you can create your cluster and it's nodes. `constellation create` uses the options set in `constellation-conf.yaml`.
2. Now you can create your cluster and its nodes. `constellation create` uses the options set in `constellation-conf.yaml`.
```bash
constellation create --control-plane-nodes 1 --worker-nodes 1

2
docs/docs/reference/config-migration.md
View File

@ -13,7 +13,7 @@ Use [`constellation config migrate`](./cli.md#constellation-config-migrate) to a
## Migrating from CLI versions before 2.3
- The `sshUsers` field was deprecated in v2.2 and has been removed from the configuration in v2.3.
As an alternative for SSH, check the workflow section [Connect to nodes](../workflows/troubleshooting.md#connect-to-nodes).
As an alternative for SSH, check the workflow section [Connect to nodes](../workflows/troubleshooting.md#node-shell-access).
- The `image` field for each cloud service provider has been replaced with a global `image` field. Use the following mapping to migrate your configuration:
<details>
<summary>Show all</summary>

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

@ -1,23 +1,11 @@
# First steps with MiniConstellation
# First steps with a local cluster
<!-- vale off -->
With the `constellation mini` command, you can deploy and test Constellation locally without a cloud subscription. This mode is called MiniConstellation. Conceptually, MiniConstellation is similar to [MicroK8s](https://microk8s.io/), [K3s](https://k3s.io/), and [minikube](https://minikube.sigs.k8s.io/docs/).
<!-- vale on -->
A local cluster lets you deploy and test Constellation without a cloud subscription.
You have two options:
* Use MiniConstellation to automatically deploy a two-node cluster.
* For more fine-grained control, create the cluster using the QEMU provider.
MiniConstellation uses virtualization to create a local cluster with one control-plane node and one worker node. It **doesn't** require hardware with Confidential VM (CVM) support. For attestation, MiniConstellation currently uses a software-based vTPM provided by KVM/QEMU.
:::caution
MiniConstellation has specific soft- and hardware requirements such as a Linux OS running on an x86-64 CPU. Pay attention to all [prerequisites](#prerequisites) when setting up.
:::
:::note
Since MiniConstellation runs on your local system, cloud features such as load balancing,
attaching persistent storage, or autoscaling aren't available.
:::
Both options use virtualization to create a local cluster with control-plane nodes and worker nodes. They **don't** require hardware with Confidential VM (CVM) support. For attestation, they currently use a software-based vTPM provided by KVM/QEMU.
## Prerequisites
@ -39,7 +27,27 @@ attaching persistent storage, or autoscaling aren't available.
sudo iptables -S | grep -q -- '-P FORWARD DROP'
```
## Create your cluster
## Create a cluster
<tabs groupId="csp">
<tabItem value="mini" label="MiniConstellation">
<!-- vale off -->
With the `constellation mini` command, you can deploy and test Constellation locally. This mode is called MiniConstellation. Conceptually, MiniConstellation is similar to [MicroK8s](https://microk8s.io/), [K3s](https://k3s.io/), and [minikube](https://minikube.sigs.k8s.io/docs/).
<!-- vale on -->
:::caution
MiniConstellation has specific soft- and hardware requirements such as a Linux OS running on an x86-64 CPU. Pay attention to all [prerequisites](#prerequisites) when setting up.
:::
:::note
Since MiniConstellation runs on your local system, cloud features such as load balancing,
attaching persistent storage, or autoscaling aren't available.
:::
The following creates your MiniConstellation cluster (may take up to 10 minutes to complete):
@ -50,13 +58,88 @@ constellation mini up
This will configure your current directory as the [workspace](../architecture/orchestration.md#workspaces) for this cluster.
All `constellation` commands concerning this cluster need to be issued from this directory.
## Connect `kubectl`
</tabItem>
<tabItem value="qemu" label="QEMU">
Configure `kubectl` to connect to your local Constellation cluster:
With the QEMU provider, you can create a local Constellation cluster as if it were in the cloud. The provider uses [QEMU](https://www.qemu.org/) to create multiple VMs for the cluster nodes, which interact with each other.
```bash
export KUBECONFIG="$PWD/constellation-admin.conf"
```
:::caution
Constellation on QEMU has specific soft- and hardware requirements such as a Linux OS running on an x86-64 CPU. Pay attention to all [prerequisites](#prerequisites) when setting up.
:::
:::note
Since Constellation on QEMU runs on your local system, cloud features such as load balancing,
attaching persistent storage, or autoscaling aren't available.
:::
1. To set up your local cluster, you need to create a configuration file for Constellation first.
```bash
constellation config generate qemu
```
This creates a [configuration file](../workflows/config.md) for QEMU called `constellation-conf.yaml`. After that, your current folder also becomes your [workspace](../architecture/orchestration.md#workspaces). All `constellation` commands for your cluster need to be executed from this directory.
2. Now you can create your cluster and its nodes. `constellation create` uses the options set in `constellation-conf.yaml`.
```bash
constellation create --control-plane-nodes 1 --worker-nodes 1
```
This will create 2 VMs: one worker node, and one control plane node.
The Output should look like the following:
```shell-session
$ constellation create ...
Your Constellation cluster was created successfully.
```
3. Initialize the cluster
```bash
constellation init
```
This should give the following output:
```shell-session
$ constellation init
Your Constellation master secret was successfully written to ./constellation-mastersecret.json
Initializing cluster ...
Your Constellation cluster was successfully initialized.
Constellation cluster identifier g6iMP5wRU1b7mpOz2WEISlIYSfdAhB0oNaOg6XEwKFY=
Kubernetes configuration constellation-admin.conf
You can now connect to your cluster by executing:
export KUBECONFIG="$PWD/constellation-admin.conf"
```
The cluster's identifier will be different in your output.
Keep `constellation-mastersecret.json` somewhere safe.
This will allow you to [recover your cluster](../workflows/recovery.md) in case of a disaster.
:::info
Depending on your setup, `constellation init` may take 10+ minutes to complete.
:::
4. Configure kubectl
```bash
export KUBECONFIG="$PWD/constellation-admin.conf"
```
</tabItem>
</tabs>
## Connect to the cluster
Your cluster initially consists of a single control-plane node:
@ -107,6 +190,9 @@ worker-0 Ready <none> 32s v1.24.6
## Terminate your cluster
<tabs groupId="csp">
<tabItem value="mini" label="MiniConstellation">
Once you are done, you can clean up the created resources using the following command:
```bash
@ -116,6 +202,38 @@ constellation mini down
This will destroy your cluster and clean up your workspace.
The VM image and cluster configuration file (`constellation-conf.yaml`) will be kept and may be reused to create new clusters.
</tabItem>
<tabItem value="qemu" label="QEMU">
Once you are done, you can clean up the created resources using the following command:
```bash
constellation terminate
```
This should give the following output:
```shell-session
$ constellation terminate
You are about to terminate a Constellation cluster.
All of its associated resources will be DESTROYED.
This action is irreversible and ALL DATA WILL BE LOST.
Do you want to continue? [y/n]:
```
Confirm with `y` to terminate the cluster:
```shell-session
Terminating ...
Your Constellation cluster was terminated successfully.
```
This will destroy your cluster and clean up your workspace.
The VM image and cluster configuration file (`constellation-conf.yaml`) will be kept and may be reused to create new clusters.
</tabItem>
</tabs>
## Troubleshooting
Make sure to use the [latest release](https://github.com/edgelesssys/constellation/releases/latest) and check out the [known issues](https://github.com/edgelesssys/constellation/issues?q=is%3Aopen+is%3Aissue+label%3A%22known+issue%22).

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

@ -4,7 +4,7 @@ The following steps guide you through the process of creating a cluster and depl
and have access to a cloud subscription.
:::tip
If you don't have a cloud subscription, check out [MiniConstellation](first-steps-local.md), which lets you set up a local Constellation cluster using virtualization.
If you don't have a cloud subscription, you can also set up a [local Constellation cluster using virtualization](../getting-started/first-steps-local.md) for testing.
:::
:::note
@ -57,6 +57,8 @@ If you encounter any problem with the following steps, make sure to use the [lat
Constellation OS images are currently replicated to the following regions:
* `eu-central-1`
* `eu-west-1`
* `eu-west-3`
* `us-east-2`
* `ap-south-1`

22
docs/versioned_docs/version-2.7/overview/clouds.md
View File

@ -11,14 +11,14 @@ For Constellation, the ideal environment provides the following:
(1) is a functional must-have. (2)--(4) are required for remote attestation that fully keeps the infrastructure/cloud out. Constellation can work without them or with approximations, but won't protect against certain privileged attackers anymore.
The following table summarizes the state of features for different infrastructures as of September 2022.
The following table summarizes the state of features for different infrastructures as of May 2023.
| **Feature** | **Azure** | **GCP** | **AWS** | **OpenStack (Yoga)** |
|-------------------------------|-----------|---------|---------|----------------------|
| **1. Custom images** | Yes | Yes | No | Yes |
| **2. SEV-SNP or TDX** | Yes | No | No | Depends on kernel/HV |
| **3. Raw guest attestation** | Yes | No | No | Depends on kernel/HV |
| **4. Reviewable firmware** | No* | No | No | Depends on kernel/HV |
| **1. Custom images** | Yes | Yes | Yes | Yes |
| **2. SEV-SNP or TDX** | Yes | Yes | Yes | Depends on kernel/HV |
| **3. Raw guest attestation** | Yes | Yes | Yes | Depends on kernel/HV |
| **4. Reviewable firmware** | No* | No | No* | Depends on kernel/HV |
## Microsoft Azure
@ -28,11 +28,19 @@ With its [CVM offering](https://docs.microsoft.com/en-us/azure/confidential-comp
## Google Cloud Platform (GCP)
The [CVMs available in GCP](https://cloud.google.com/compute/confidential-vm/docs/create-confidential-vm-instance) are based on AMD SEV but don't have SNP features enabled. This impacts attestation capabilities. Currently, GCP doesn't offer CVM-based attestation at all. Instead, GCP provides attestation statements based on its regular [vTPM](https://cloud.google.com/blog/products/identity-security/virtual-trusted-platform-module-for-shielded-vms-security-in-plaintext), which is managed by the hypervisor. On GCP, the hypervisor is thus currently part of Constellation's TCB.
The [CVMs Generally Available in GCP](https://cloud.google.com/compute/confidential-vm/docs/create-confidential-vm-instance) are based on AMD SEV but don't have SNP features enabled.
CVMs with SEV-SNP enabled are currently in [private preview](https://cloud.google.com/blog/products/identity-security/rsa-snp-vm-more-confidential). Regarding (3), with their SEV-SNP offering Google provides direct access to remote-attestation statements.
However, regarding (4), the CVMs still include closed-source firmware.
Intel and Google have [collaborated](https://cloud.google.com/blog/products/identity-security/rsa-google-intel-confidential-computing-more-secure) to enhance the security of TDX, and have recently [revealed](https://venturebeat.com/security/intel-launches-confidential-computing-solution-for-virtual-machines/) their plans to make TDX compatible with Google Cloud.
## Amazon Web Services (AWS)
Amazon EC2 [supports AMD SEV-SNP](https://aws.amazon.com/de/about-aws/whats-new/2023/04/amazon-ec2-amd-sev-snp/). Regarding (3), AWS provides direct access to remote-attestation statements.
However, attestation is partially based on the [NitroTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) for [measured boot](../architecture/attestation.md#measured-boot), which is a vTPM managed by the Nitro hypervisor. Hence, the hypervisor is currently part of Constellation's TCB.
\* Regarding (4), the CVMs include initial firmware inside the CVM based on [OVMF](https://github.com/tianocore/tianocore.github.io/wiki/OVMF). Once this firmware will be reproducible and therefore verifiable, (4) switches from *No* to *Yes*.
AWS currently doesn't offer CVMs. AWS proprietary Nitro Enclaves offer some related features but [are explicitly not designed to keep AWS itself out](https://aws.amazon.com/blogs/security/confidential-computing-an-aws-perspective/). Besides, they aren't suitable for running entire Kubernetes nodes inside them. Therefore, Constellation uses regular EC2 instances on AWS [Nitro](https://aws.amazon.com/ec2/nitro/) without runtime encryption. Attestation is based on the [NitroTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html), which is a vTPM managed by the Nitro hypervisor. Hence, the hypervisor is currently part of Constellation's TCB.
## OpenStack

2
docs/versioned_docs/version-2.7/reference/config-migration.md
View File

@ -5,7 +5,7 @@ This document describes breaking changes in the configuration file format betwee
## Migrating from CLI versions before 2.3
- The `sshUsers` field was deprecated in v2.2 and has been removed from the configuration in v2.3.
As an alternative for SSH, check the workflow section [Connect to nodes](../workflows/troubleshooting.md#connect-to-nodes).
As an alternative for SSH, check the workflow section [Connect to nodes](../workflows/troubleshooting.md#node-shell-access).
- The `image` field for each cloud service provider has been replaced with a global `image` field. Use the following mapping to migrate your configuration:
<details>
<summary>Show all</summary>

9
docs/versioned_docs/version-2.7/workflows/config.md
View File

@ -130,6 +130,8 @@ This command creates IAM configuration for the AWS zone `eu-central-1a` using th
Constellation OS images are currently replicated to the following regions:
* `eu-central-1`
* `eu-west-1`
* `eu-west-3`
* `us-east-2`
* `ap-south-1`
@ -226,6 +228,8 @@ The following describes the configuration fields and how you obtain the required
Constellation OS images are currently replicated to the following regions:
* `eu-central-1`
* `eu-west-1`
* `eu-west-3`
* `us-east-2`
* `ap-south-1`
@ -264,3 +268,8 @@ Delete the IAM configuration by executing the following command in the same dire
```bash
constellation iam destroy
```
:::caution
For Azure, deleting the IAM configuration by executing `constellation iam destroy` will delete the whole resource group created by `constellation iam create`.
This also includes any additional resources in the resource group that weren't created by Constellation.
:::

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

@ -16,7 +16,7 @@ Creating your cluster requires two steps:
See the [architecture](../architecture/orchestration.md) section for details on the inner workings of this process.
:::tip
If you don't have a cloud subscription, check out [MiniConstellation](../getting-started/first-steps-local.md), which lets you set up a local Constellation cluster using virtualization.
If you don't have a cloud subscription, you can also set up a [local Constellation cluster using virtualization](../getting-started/first-steps-local.md) for testing.
:::
## The *create* step