mirror of
https://github.com/edgelesssys/constellation.git
synced 2024-10-01 01:36:09 -04:00
docs: publish
This commit is contained in:
parent
050fccc591
commit
69464bca4b
@ -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
|
||||
|
@ -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>
|
||||
|
@ -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,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`
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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>
|
||||
|
@ -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.
|
||||
:::
|
||||
|
@ -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
|
||||
|
Loading…
Reference in New Issue
Block a user