mirror of
https://github.com/edgelesssys/constellation.git
synced 2024-10-01 01:36:09 -04:00
Overwrite v2.0 in docs (#144)
This commit is contained in:
Felix Schuster
GitHub
parent
0165a6be43
commit
d5d5448935
@ -112,7 +112,7 @@ Those correspond to measurements of closed-source firmware components and other
|
||||
While not being directly verifiable, they can be compared against previously observed values.
|
||||
As part of the [signed image measurements](#chain-of-trust), Constellation provides measurements that are known, previously observed values.
|
||||
Thereby, Constellation enables users to identify changes and deviations and allows them to act accordingly.
|
||||
See how to [fetch](../workflows/verify.md#fetch-measurements) the latest measurements and verify a cluster.
|
||||
See how to [fetch](../workflows/verify-cluster.md#fetch-measurements) the latest measurements and verify a cluster.
|
||||
|
||||
Second, are the measurements produced by the Constellation bootloader and boot chain itself.
|
||||
The Constellation Bootloader is the first part of the Constellation stack that takes over from the CVM firmware and measures the rest of the boot chain.
|
||||
@ -205,7 +205,7 @@ When an initialized node tries to join another cluster, its measurements inevita
|
||||
### User-facing attestation
|
||||
|
||||
The [*VerificationService*](components.md#verificationservice) provides an endpoint for obtaining its hardware-based remote attestation statement, which includes the runtime measurements.
|
||||
A user can [verify](../workflows/verify.md) this statement and compare the measurements against the configured ground truth and, thus, verify the identity and integrity of all Constellation components and the cluster configuration. Subsequently, the user knows that the entire cluster is in the expected state and is trustworthy.
|
||||
A user can [verify](../workflows/verify-cluster.md) this statement and compare the measurements against the configured ground truth and, thus, verify the identity and integrity of all Constellation components and the cluster configuration. Subsequently, the user knows that the entire cluster is in the expected state and is trustworthy.
|
||||
|
||||
## Chain of trust
|
||||
|
||||
|
||||
@ -67,7 +67,7 @@ sequenceDiagram
|
||||
|
||||
The *VerificationService* runs as DaemonSet on each node.
|
||||
It provides user-facing functionality for remote attestation during the cluster's lifetime via an endpoint for [verifying the cluster](attestation.md#cluster-attestation).
|
||||
Read more about the hardware-based [attestation feature](attestation.md) of Constellation and how to [verify](../workflows/verify.md) a cluster on the client side.
|
||||
Read more about the hardware-based [attestation feature](attestation.md) of Constellation and how to [verify](../workflows/verify-cluster.md) a cluster on the client side.
|
||||
|
||||
## KMS
|
||||
|
||||
|
||||
@ -70,7 +70,7 @@ You can read more about these values and their meaning in the guide on [cluster
|
||||
The *master secret* must be kept secret and can be used to [recover your cluster](../workflows/recovery.md).
|
||||
Instead of managing this secret manually, you can [use your key management solution of choice](keys.md#user-managed-key-management) with Constellation.
|
||||
|
||||
The *clusterID* uniquely identifies a cluster and can be used to [verify your cluster](../workflows/verify.md).
|
||||
The *clusterID* uniquely identifies a cluster and can be used to [verify your cluster](../workflows/verify-cluster.md).
|
||||
|
||||
## Upgrades
|
||||
|
||||
|
||||
@ -1,10 +1,6 @@
|
||||
# Examples
|
||||
|
||||
After [installing the CLI](install.md) and [creating a cluster](first-steps.md) we've collected a few Kubernetes example applications for deploying in your cluster. They highlight different features and give a first hands-on experience working with Kubernetes in a Constellation cluster. If you have experience with Kubernetes deployments there shouldn't be any sensible differences. Have fun exploring your Confidential Kubernetes!
|
||||
|
||||
Before trying out the example applications, make sure you [installed the Constellation CLI](install.md) and [created a cluster](first-steps.md). From there, the examples shown here are designed to work on a freshly created cluster and don't require any further prerequisites.
|
||||
|
||||
Check out the following examples:
|
||||
* [Emojivoto](examples/emojivoto.md): A simple but fun demo application to test the general functionality of your confidential cluster.
|
||||
* [Online Boutique](examples/online-boutique.md): An e-commerce demo application by Google consisting of 11 separate microservices.
|
||||
* [Horizontal Pod Autoscaling](examples/horizontal-scaling.md): An example demonstrating Constellation's autoscaling capabilities.
|
||||
After you [installed the CLI](install.md) and [created your first cluster](first-steps.md), you're ready to deploy applications. Why not start with one of the following examples?
|
||||
* [Emojivoto](examples/emojivoto.md): a simple but fun web application
|
||||
* [Online Boutique](examples/online-boutique.md): an e-commerce demo application by Google consisting of 11 separate microservices
|
||||
* [Horizontal Pod Autoscaling](examples/horizontal-scaling.md): an example demonstrating Constellation's autoscaling capabilities
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
# Emojivoto
|
||||
For a simple but fun demo application to test the general functionality of your confidential cluster, take a look at [Emojivoto](https://github.com/BuoyantIO/emojivoto).
|
||||
[Emojivoto](https://github.com/BuoyantIO/emojivoto) is a simple and fun application that's well suited to test the basic functionality of your cluster.
|
||||
|
||||
<!-- vale off -->
|
||||
|
||||
|
||||
@ -1,10 +1,14 @@
|
||||
# Horizontal Pod Autoscaling
|
||||
This example demonstrates Constellation's autoscaling capabilities by utilizing a slightly adapted version of the Kubernetes [HorizontalPodAutoscaler Walkthrough](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/). During the following steps, we will see Constellation be able to spawn new VMs on demand, add them to the cluster and later on delete them again when the load has settled down.
|
||||
This example demonstrates Constellation's autoscaling capabilities by utilizing a slightly adapted version of the Kubernetes [HorizontalPodAutoscaler Walkthrough](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/). During the following steps, Constellation will spawn new VMs on demand, verify them, add them to the cluster, and delete them again when the load has settled down.
|
||||
|
||||
## Requirements
|
||||
The cluster needs to be initialized with Kubernetes 1.23 or higher. In addition, autoscaling must be enabled to trigger Constellation to assign new nodes dynamically.
|
||||
|
||||
Just for this example specifically, the cluster should have as few worker nodes in the beginning as possible. Starting with a small cluster having only *one* control plane node and *one* worker node using one of the low-end supported VMs is recommended for an easier demonstration and saving costs. The example has been tested on Azure using a `Standard_DC4as_v5` and on GCP using `n2d-standard-4` instance.
|
||||
Just for this example specifically, the cluster should have as few worker nodes in the beginning as possible. We recommend starting with a small cluster with only *one* low-powered node for the control plane node and *one* low-powered worker node.
|
||||
|
||||
:::info
|
||||
We tested the example using instances of types `Standard_DC4as_v5` on Azure and `n2d-standard-4` on GCP.
|
||||
:::
|
||||
|
||||
## Setup
|
||||
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
# Online Boutique
|
||||
[Online Boutique](https://github.com/GoogleCloudPlatform/microservices-demo) is an e-commerce demo application by Google consisting of 11 separate microservices. Constellation is automatically able to set up a load balancer on your CSP, making it easy to expose services from your confidential cluster without any additional setup required.
|
||||
[Online Boutique](https://github.com/GoogleCloudPlatform/microservices-demo) is an e-commerce demo application by Google consisting of 11 separate microservices. In this demo, Constellation automatically sets up a load balancer on your CSP, making it easy to expose services from your confidential cluster.
|
||||
|
||||
<!-- vale off -->
|
||||
|
||||
@ -20,7 +20,7 @@
|
||||
kubectl wait --for=condition=available --timeout=300s -n boutique --all deployments
|
||||
```
|
||||
4. Get the external facing IP address of the frontend (with `<your-ip>` being a placeholder for the assigned IP from your CSP):
|
||||
```terminal-session
|
||||
```shell-session
|
||||
kubectl get service frontend-external -n boutique | awk '{print $4}'
|
||||
EXTERNAL-IP
|
||||
<your-ip>
|
||||
|
||||
@ -25,41 +25,37 @@ The following steps will guide you through the process of creating a cluster and
|
||||
|
||||
This creates the file `constellation-conf.yaml` in your current working directory.
|
||||
|
||||
2. Fill in your cloud provider specific information:
|
||||
2. Fill in your cloud provider specific information.
|
||||
|
||||
<tabs groupId="csp">
|
||||
<tabItem value="azure" label="Azure (CLI)" default>
|
||||
|
||||
For a quick start it's recommended to use our `az` script to automatically create all required resources:
|
||||
For a quick start it's recommended to use the following `az` script to automatically create all required resources:
|
||||
|
||||
```bash
|
||||
RESOURCE_GROUP=constellation # enter name of resource group here
|
||||
LOCATION=westus # enter location of resources here
|
||||
SUBSCRIPTION_ID=$(az account show --query id --out tsv)
|
||||
SERVICE_PRINCIPLE_NAME=constell
|
||||
SERVICE_PRINCIPAL_NAME=constell
|
||||
az group create --name "${RESOURCE_GROUP}" --location "${LOCATION}"
|
||||
az group create --name "${RESOURCE_GROUP}-identity" --location "${LOCATION}"
|
||||
az ad sp create-for-rbac -n "${SERVICE_PRINCIPLE_NAME}" --role Owner --scopes "/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${RESOURCE_GROUP}" | tee azureServiceAccountKey.json
|
||||
az identity create -g "${RESOURCE_GROUP}-identity" -n "${SERVICE_PRINCIPLE_NAME}"
|
||||
identityID=$(az identity show -n "${SERVICE_PRINCIPLE_NAME}" -g "${RESOURCE_GROUP}-identity" --query principalId --out tsv)
|
||||
az ad sp create-for-rbac -n "${SERVICE_PRINCIPAL_NAME}" --role Owner --scopes "/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${RESOURCE_GROUP}" | tee azureServiceAccountKey.json
|
||||
az identity create -g "${RESOURCE_GROUP}-identity" -n "${SERVICE_PRINCIPAL_NAME}"
|
||||
identityID=$(az identity show -n "${SERVICE_PRINCIPAL_NAME}" -g "${RESOURCE_GROUP}-identity" --query principalId --out tsv)
|
||||
az role assignment create --assignee-principal-type ServicePrincipal --assignee-object-id "${identityID}" --role 'Virtual Machine Contributor' --scope "/subscriptions/${SUBSCRIPTION_ID}"
|
||||
az role assignment create --assignee-principal-type ServicePrincipal --assignee-object-id "${identityID}" --role 'Application Insights Component Contributor' --scope "/subscriptions/${SUBSCRIPTION_ID}"
|
||||
echo "subscription: ${SUBSCRIPTION_ID}"
|
||||
echo "tenant: $(az account show --query tenantId -o tsv)"
|
||||
echo "location: ${LOCATION}"
|
||||
echo "resourceGroup: ${RESOURCE_GROUP}"
|
||||
echo "userAssignedIdentity: $(az identity show -n "${SERVICE_PRINCIPLE_NAME}" -g "${RESOURCE_GROUP}-identity" --query id --out tsv)"
|
||||
echo "userAssignedIdentity: $(az identity show -n "${SERVICE_PRINCIPAL_NAME}" -g "${RESOURCE_GROUP}-identity" --query id --out tsv)"
|
||||
echo "appClientID: $(jq -r '.appId' azureServiceAccountKey.json)"
|
||||
echo "clientSecretValue: $(jq -r '.password' azureServiceAccountKey.json)"
|
||||
```
|
||||
|
||||
Fill in the printed out values to your configuration file.
|
||||
Fill the values produced by the script into your configuration file.
|
||||
|
||||
By default, Constellation uses `Standard_DC4as_v5` CVMs (4 vCPUs, 16 GB RAM) to create your cluster. Optionally, you can switch to a different VM type by modifying **instanceType** in the configuration file.
|
||||
|
||||
For CVMs, any VM type with a minimum of 4 vCPUs from the [DCasv5 & DCadsv5](https://docs.microsoft.com/en-us/azure/virtual-machines/dcasv5-dcadsv5-series) or [ECasv5 & ECadsv5](https://docs.microsoft.com/en-us/azure/virtual-machines/ecasv5-ecadsv5-series) families is supported.
|
||||
|
||||
If you decide to use [trusted launch VMs](../workflows/trusted-launch.md) instead, set **confidentialVM** to false. Afterward, you can use any VMs with a minimum of 4 vCPUs from the [Dav4 & Dasv4](https://docs.microsoft.com/en-us/azure/virtual-machines/dav4-dasv4-series) or [Eav4 & Easv4](https://docs.microsoft.com/en-us/azure/virtual-machines/eav4-easv4-series) families.
|
||||
By default, Constellation uses `Standard_DC4as_v5` CVMs (4 vCPUs, 16 GB RAM) to create your cluster. Optionally, you can switch to a different VM type by modifying **instanceType** in the configuration file. For CVMs, any VM type with a minimum of 4 vCPUs from the [DCasv5 & DCadsv5](https://docs.microsoft.com/en-us/azure/virtual-machines/dcasv5-dcadsv5-series) or [ECasv5 & ECadsv5](https://docs.microsoft.com/en-us/azure/virtual-machines/ecasv5-ecadsv5-series) families is supported.
|
||||
|
||||
Run `constellation config instance-types` to get the list of all supported options.
|
||||
|
||||
@ -85,8 +81,6 @@ The following steps will guide you through the process of creating a cluster and
|
||||
|
||||
For CVMs, any type with a minimum of 4 vCPUs from the [DCasv5 & DCadsv5](https://docs.microsoft.com/en-us/azure/virtual-machines/dcasv5-dcadsv5-series) or [ECasv5 & ECadsv5](https://docs.microsoft.com/en-us/azure/virtual-machines/ecasv5-ecadsv5-series) families is supported. It defaults to `Standard_DC4as_v5` (4 vCPUs, 16 GB RAM).
|
||||
|
||||
If you decide to use [trusted launch VMs](../workflows/trusted-launch.md) instead, set **confidentialVM** to false. Afterward, you can use any VMs with a minimum of 4 vCPUs from the [Dav4 & Dasv4](https://docs.microsoft.com/en-us/azure/virtual-machines/dav4-dasv4-series) or [Eav4 & Easv4](https://docs.microsoft.com/en-us/azure/virtual-machines/eav4-easv4-series) families.
|
||||
|
||||
Run `constellation config instance-types` to get the list of all supported options.
|
||||
|
||||
* **resourceGroup**: [Create a new resource group in Azure](https://portal.azure.com/#create/Microsoft.ResourceGroup), to deploy your Constellation cluster into. Afterwards set the configuration field to the name of the created resource group, e.g., `constellation`.
|
||||
@ -116,7 +110,7 @@ The following steps will guide you through the process of creating a cluster and
|
||||
</tabItem>
|
||||
<tabItem value="gcp" label="GCP (CLI)">
|
||||
|
||||
For a quick start it's recommended to use our `gcloud` script to automatically create all required resources:
|
||||
For a quick start it's recommended to use the following `gcloud` script to automatically create all required resources:
|
||||
|
||||
```bash
|
||||
SERVICE_ACCOUNT_ID=constell # enter name of service account here
|
||||
@ -133,7 +127,7 @@ The following steps will guide you through the process of creating a cluster and
|
||||
echo "serviceAccountKeyPath: $(realpath gcpServiceAccountKey.json)"
|
||||
```
|
||||
|
||||
Fill in the printed out values to your configuration file.
|
||||
Fill the values produced by the script into your configuration file.
|
||||
|
||||
By default, Constellation uses `n2d-standard-4` VMs (4 vCPUs, 16 GB RAM) to create your cluster. Optionally, you can switch to a different VM type by modifying **instanceType** in the configuration file. Supported are all machines from the N2D family. Refer to [N2D machine series](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) or run `constellation config instance-types` to get the list of all supported options.
|
||||
|
||||
@ -169,6 +163,12 @@ The following steps will guide you through the process of creating a cluster and
|
||||
</tabItem>
|
||||
</tabs>
|
||||
|
||||
:::info
|
||||
|
||||
In case you don't have access to CVMs on Azure, you may use less secure [trusted launch VMs](../workflows/trusted-launch.md) instead. For this, set **confidentialVM** to `false` in the configuration file.
|
||||
|
||||
:::
|
||||
|
||||
3. Download the measurements for your configured image.
|
||||
|
||||
```bash
|
||||
@ -177,7 +177,7 @@ The following steps will guide you through the process of creating a cluster and
|
||||
|
||||
This command is necessary to download the latest trusted measurements for your configured image.
|
||||
|
||||
For more details, see the [verification section](../workflows/verify.md).
|
||||
For more details, see the [verification section](../workflows/verify-cluster.md).
|
||||
|
||||
4. Create the cluster with one control-plane node and two worker nodes. `constellation create` uses options set in `constellation-conf.yaml` automatically.
|
||||
|
||||
|
||||
@ -2,64 +2,39 @@
|
||||
|
||||
Constellation runs entirely in your cloud environment and can be easily controlled via a dedicated Command Line Interface (CLI).
|
||||
|
||||
The installation process will guide you through the steps of installing the CLI on your machine, verifying it, and connecting it to your Cloud Service Provider (CSP).
|
||||
The following guides you through the steps of installing the CLI on your machine, verifying it, and connecting it to your Cloud Service Provider (CSP).
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Before we start, make sure the following requirements are fulfilled:
|
||||
Make sure the following requirements are met:
|
||||
|
||||
- Your machine is running Ubuntu or macOS
|
||||
- Your machine is running Linux or macOS
|
||||
- You have admin rights on your machine
|
||||
- [kubectl](https://kubernetes.io/docs/tasks/tools/) is installed
|
||||
- Your cloud provider is Microsoft Azure or Google Cloud
|
||||
- Your cloud provider is Microsoft Azure or Google Cloud Platform (GCP)
|
||||
|
||||
## Install the Constellation CLI
|
||||
|
||||
The Constellation CLI can be downloaded from our [release page](https://github.com/edgelesssys/constellation/releases). Therefore, navigate to a release and download the `constellation` binary for your operating system and architecture. Move the downloaded file to a directory in your `PATH` (default: `/usr/local/bin`) and make it executable by entering `chmod u+x constellation` in your terminal.
|
||||
Download the CLI executable from the [release page](https://github.com/edgelesssys/constellation/releases). Move the downloaded file to a directory in your `PATH` (default: `/usr/local/bin`) and make it executable by entering `chmod u+x constellation` in your terminal.
|
||||
|
||||
Running `constellation` should then give you:
|
||||
:::note
|
||||
Edgeless Systems uses [sigstore](https://www.sigstore.dev/) to sign each release of the CLI. You may want to [verify the signature](../workflows/verify-cli.md) before you use the CLI.
|
||||
:::
|
||||
|
||||
```shell-session
|
||||
$ constellation
|
||||
Manage your Constellation cluster.
|
||||
|
||||
Usage:
|
||||
constellation [command]
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
### Optional: Enable shell autocompletion
|
||||
|
||||
The Constellation CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the steps.
|
||||
|
||||
## Verify the CLI
|
||||
|
||||
For extra security, make sure to verify your CLI. Therefore, install [cosign](https://github.com/sigstore/cosign). Then, head to our [release page](https://github.com/edgelesssys/constellation/releases) again and, from the same release as before, download the following files:
|
||||
|
||||
- `cosign.pub` (Edgeless System's cosign public key)
|
||||
- `constellation-*.sig` (the CLI's signature)
|
||||
|
||||
You can then verify your CLI before launching a cluster using the paths to the public key, signature, and CLI executable:
|
||||
|
||||
```bash
|
||||
cosign verify-blob --key cosign.pub --signature constellation.sig constellation
|
||||
```
|
||||
|
||||
For more detailed information read our [installation, update and verification documentation](../architecture/orchestration.md).
|
||||
:::tip
|
||||
The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps.
|
||||
:::
|
||||
|
||||
## Set up cloud credentials
|
||||
|
||||
The CLI makes authenticated calls to the CSP API. Therefore, you need to set up Constellation with the credentials for your CSP.
|
||||
The CLI makes authenticated calls to the CSP API. Therefore, you need to set up Constellation with the credentials for your CSP. Currently, Microsoft Azure and Google Cloud Platform (GCP) are the only supported CSPs.
|
||||
|
||||
### Authentication
|
||||
### Step 1: Authenticate
|
||||
|
||||
In the following, we provide you with different ways to authenticate with your CSP.
|
||||
First, you need to authenticate with your CSP. The following lists the required steps for *testing* and *production* environments.
|
||||
|
||||
:::danger
|
||||
|
||||
Don't use the testing methods for setting up a production-grade Constellation cluster. In those methods, secrets are stored on disk during installation which would be exposed to the CSP.
|
||||
|
||||
The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps.
|
||||
:::
|
||||
|
||||
<tabs groupId="csp">
|
||||
@ -67,11 +42,11 @@ Don't use the testing methods for setting up a production-grade Constellation cl
|
||||
|
||||
**Testing**
|
||||
|
||||
To try out Constellation, using a cloud environment such as [Azure Cloud Shell](https://docs.microsoft.com/en-us/azure/cloud-shell/overview) is the quickest way to get started.
|
||||
Simply open the [Azure Cloud Shell](https://docs.microsoft.com/en-us/azure/cloud-shell/overview).
|
||||
|
||||
**Production**
|
||||
|
||||
For production clusters, use the latest version of the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/) on a trusted machine:
|
||||
Use the latest version of the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/) on a trusted machine:
|
||||
|
||||
```bash
|
||||
az login
|
||||
@ -90,13 +65,13 @@ Enable the following cloud APIs first:
|
||||
|
||||
**Testing**
|
||||
|
||||
- If you are running from within a Google VM, and the VM is allowed to access the necessary APIs, no further configuration is needed.
|
||||
If you are running from within VM on GCP, and the VM is allowed to access the necessary APIs, no further configuration is needed.
|
||||
|
||||
- If you are using the [Google Cloud Shell](https://cloud.google.com/shell), make sure your [session is authorized](https://cloud.google.com/shell/docs/auth). For example, execute `gsutil` and accept the authorization prompt.
|
||||
If you are using the [Google Cloud Shell](https://cloud.google.com/shell), make sure your [session is authorized](https://cloud.google.com/shell/docs/auth). For example, execute `gsutil` and accept the authorization prompt.
|
||||
|
||||
**Production**
|
||||
|
||||
For production clusters, use one of the following options on a trusted machine:
|
||||
For production, use one of the following options on a trusted machine:
|
||||
|
||||
- Use the [`gcloud` CLI](https://cloud.google.com/sdk/gcloud)
|
||||
|
||||
@ -104,7 +79,7 @@ For production clusters, use one of the following options on a trusted machine:
|
||||
gcloud auth application-default login
|
||||
```
|
||||
|
||||
This will ask you to log in to your Google account, and then create your credentials.
|
||||
This will ask you to log-in to your Google account and create your credentials.
|
||||
The Constellation CLI will automatically load these credentials when needed.
|
||||
|
||||
- Set up a service account and pass the credentials manually
|
||||
@ -114,12 +89,14 @@ For production clusters, use one of the following options on a trusted machine:
|
||||
</tabItem>
|
||||
</tabs>
|
||||
|
||||
### Authorization
|
||||
### Step 2: Set permissions
|
||||
|
||||
Finally, set the required permissions for your user account.
|
||||
|
||||
<tabs groupId="csp">
|
||||
<tabItem value="azure" label="Azure" default>
|
||||
|
||||
Your user account needs the following permissions to set up a Constellation cluster:
|
||||
Set the following permissions:
|
||||
|
||||
- `Contributor`
|
||||
- `User Access Administrator`
|
||||
@ -127,7 +104,7 @@ Your user account needs the following permissions to set up a Constellation clus
|
||||
</tabItem>
|
||||
<tabItem value="gcp" label="GCP" default>
|
||||
|
||||
Your user account needs the following permissions to set up a Constellation:
|
||||
Set the following permissions:
|
||||
|
||||
- `compute.*` (or the subset defined by `roles/compute.instanceAdmin.v1`)
|
||||
- `iam.serviceAccountUser`
|
||||
@ -139,4 +116,4 @@ Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/under
|
||||
|
||||
### Next Steps
|
||||
|
||||
Once you have followed all previous steps, you can proceed [to deploy your first confidential Kubernetes cluster and application](first-steps.md).
|
||||
You are now ready to [deploy your first confidential Kubernetes cluster and application](first-steps.md).
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Security benefits and threat model
|
||||
|
||||
Constellation implements the [Confidential Kubernetes](confidential-kubernetes.md) concept and shields entire Kubernetes deployments from the infrastructure. More concretely, Constellation decreases the size of the trusted computing base (TCB) of a Kubernetes deployment. The TCB is the totality of elements in a computing environment that must be trusted not to be compromised. A smaller TCB results in a smaller attack surface. The following diagram shows how Constellation removes the *cloud & datacenter infrastructure* and the *physical hosts*, including the hypervisor, the host OS, and other components, from the TCB (red). Inside the confidential context (green), Kubernetes remains part of the TCB, but its integrity is attested and can be [verified](../workflows/verify.md).
|
||||
Constellation implements the [Confidential Kubernetes](confidential-kubernetes.md) concept and shields entire Kubernetes deployments from the infrastructure. More concretely, Constellation decreases the size of the trusted computing base (TCB) of a Kubernetes deployment. The TCB is the totality of elements in a computing environment that must be trusted not to be compromised. A smaller TCB results in a smaller attack surface. The following diagram shows how Constellation removes the *cloud & datacenter infrastructure* and the *physical hosts*, including the hypervisor, the host OS, and other components, from the TCB (red). Inside the confidential context (green), Kubernetes remains part of the TCB, but its integrity is attested and can be [verified](../workflows/verify-cluster.md).
|
||||
|
||||
|
||||
|
||||
|
||||
@ -14,15 +14,15 @@ Commands:
|
||||
* [config](#constellation-config): Work with the Constellation configuration file
|
||||
* [generate](#constellation-config-generate): Generate a default configuration file
|
||||
* [fetch-measurements](#constellation-config-fetch-measurements): Fetch measurements for configured cloud provider and image
|
||||
* [instance-types](#constellation-config-instance-types): Prints the supported instance types for all cloud providers
|
||||
* [instance-types](#constellation-config-instance-types): Print the supported instance types for all cloud providers
|
||||
* [create](#constellation-create): Create instances on a cloud platform for your Constellation cluster
|
||||
* [init](#constellation-init): Initialize the Constellation cluster
|
||||
* [verify](#constellation-verify): Verify the confidential properties of a Constellation cluster
|
||||
* [upgrade](#constellation-upgrade): Plan and perform an upgrade of a Constellation cluster
|
||||
* [plan](#constellation-upgrade-plan): Plan an upgrade of a Constellation cluster
|
||||
* [execute](#constellation-upgrade-execute): Execute an upgrade of a Constellation cluster
|
||||
* [recover](#constellation-recover): Recover a completely stopped Constellation cluster
|
||||
* [terminate](#constellation-terminate): Terminate a Constellation cluster
|
||||
* [upgrade](#constellation-upgrade): Plan and perform an upgrade of a Constellation cluster
|
||||
* [execute](#constellation-upgrade-execute): Execute an upgrade of a Constellation cluster
|
||||
* [plan](#constellation-upgrade-plan): Plan an upgrade of a Constellation cluster
|
||||
* [version](#constellation-version): Display version of this CLI
|
||||
|
||||
## constellation config
|
||||
@ -31,7 +31,7 @@ Work with the Constellation configuration file
|
||||
|
||||
### Synopsis
|
||||
|
||||
Generate a configuration file for Constellation.
|
||||
Work with the Constellation configuration file.
|
||||
|
||||
### Options
|
||||
|
||||
@ -98,11 +98,11 @@ constellation config fetch-measurements [flags]
|
||||
|
||||
## constellation config instance-types
|
||||
|
||||
Prints the supported instance types for all cloud providers
|
||||
Print the supported instance types for all cloud providers
|
||||
|
||||
### Synopsis
|
||||
|
||||
Prints the supported instance types for all cloud providers.
|
||||
Print the supported instance types for all cloud providers.
|
||||
|
||||
```
|
||||
constellation config instance-types [flags]
|
||||
@ -192,10 +192,78 @@ constellation verify [flags]
|
||||
### Options
|
||||
|
||||
```
|
||||
--cluster-id string verify using Constellation's cluster identifier
|
||||
--cluster-id string expected cluster identifier
|
||||
-h, --help help for verify
|
||||
-e, --node-endpoint string endpoint of the node to verify, passed as HOST[:PORT]
|
||||
--owner-id string verify using the owner identity derived from the master secret
|
||||
```
|
||||
|
||||
### Options inherited from parent commands
|
||||
|
||||
```
|
||||
--config string path to the configuration file (default "constellation-conf.yaml")
|
||||
```
|
||||
|
||||
## constellation upgrade
|
||||
|
||||
Plan and perform an upgrade of a Constellation cluster
|
||||
|
||||
### Synopsis
|
||||
|
||||
Plan and perform an upgrade of a Constellation cluster.
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for upgrade
|
||||
```
|
||||
|
||||
### Options inherited from parent commands
|
||||
|
||||
```
|
||||
--config string path to the configuration file (default "constellation-conf.yaml")
|
||||
```
|
||||
|
||||
## constellation upgrade plan
|
||||
|
||||
Plan an upgrade of a Constellation cluster
|
||||
|
||||
### Synopsis
|
||||
|
||||
Plan an upgrade of a Constellation cluster by fetching compatible image versions and their measurements.
|
||||
|
||||
```
|
||||
constellation upgrade plan [flags]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-f, --file string path to output file, or '-' for stdout (omit for interactive mode)
|
||||
-h, --help help for plan
|
||||
```
|
||||
|
||||
### Options inherited from parent commands
|
||||
|
||||
```
|
||||
--config string path to the configuration file (default "constellation-conf.yaml")
|
||||
```
|
||||
|
||||
## constellation upgrade execute
|
||||
|
||||
Execute an upgrade of a Constellation cluster
|
||||
|
||||
### Synopsis
|
||||
|
||||
Execute an upgrade of a Constellation cluster by applying the chosen configuration.
|
||||
|
||||
```
|
||||
constellation upgrade execute [flags]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for execute
|
||||
```
|
||||
|
||||
### Options inherited from parent commands
|
||||
@ -255,75 +323,6 @@ constellation terminate [flags]
|
||||
--config string path to the configuration file (default "constellation-conf.yaml")
|
||||
```
|
||||
|
||||
## constellation upgrade
|
||||
|
||||
Plan and perform an upgrade of a Constellation cluster
|
||||
|
||||
### Synopsis
|
||||
|
||||
Plan and perform an upgrade of a Constellation cluster.
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for upgrade
|
||||
```
|
||||
|
||||
### Options inherited from parent commands
|
||||
|
||||
```
|
||||
--config string path to the configuration file (default "constellation-conf.yaml")
|
||||
```
|
||||
|
||||
## constellation upgrade execute
|
||||
|
||||
Execute an upgrade of a Constellation cluster
|
||||
|
||||
### Synopsis
|
||||
|
||||
Execute an upgrade of a Constellation cluster by applying the chosen configuration.
|
||||
|
||||
```
|
||||
constellation upgrade execute [flags]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-h, --help help for execute
|
||||
```
|
||||
|
||||
### Options inherited from parent commands
|
||||
|
||||
```
|
||||
--config string path to the configuration file (default "constellation-conf.yaml")
|
||||
```
|
||||
|
||||
## constellation upgrade plan
|
||||
|
||||
Plan an upgrade of a Constellation cluster
|
||||
|
||||
### Synopsis
|
||||
|
||||
Plan an upgrade of a Constellation cluster by fetching compatible image versions and their measurements.
|
||||
|
||||
```
|
||||
constellation upgrade plan [flags]
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
```
|
||||
-f, --file string path to output file, or '-' for stdout, leave empty for interactive mode
|
||||
-h, --help help for plan
|
||||
```
|
||||
|
||||
### Options inherited from parent commands
|
||||
|
||||
```
|
||||
--config string path to the configuration file (default "constellation-conf.yaml")
|
||||
```
|
||||
|
||||
## constellation version
|
||||
|
||||
Display version of this CLI
|
||||
|
||||
@ -50,7 +50,7 @@ Next, download the latest trusted measurements for your configured image.
|
||||
constellation config fetch-measurements
|
||||
```
|
||||
|
||||
For more details, see the [verification section](../workflows/verify.md).
|
||||
For more details, see the [verification section](../workflows/verify-cluster.md).
|
||||
|
||||
### Create
|
||||
|
||||
|
||||
@ -43,7 +43,7 @@ On the left open the *"Support + troubleshooting" -> "Serial console"* page:
|
||||
In the serial console output search for `Waiting for decryption key`.
|
||||
Similar output to the following means your node was restarted and needs to decrypt the [state disk](../architecture/images.md#state-disk):
|
||||
|
||||
```shell
|
||||
```json
|
||||
{"level":"INFO","ts":"2022-09-08T09:56:41Z","caller":"cmd/main.go:55","msg":"Starting disk-mapper","version":"2.0.0","cloudProvider":"azure"}
|
||||
{"level":"INFO","ts":"2022-09-08T09:56:43Z","logger":"setupManager","caller":"setup/setup.go:72","msg":"Preparing existing state disk"}
|
||||
{"level":"INFO","ts":"2022-09-08T09:56:43Z","logger":"recoveryServer","caller":"recoveryserver/server.go:59","msg":"Starting RecoveryServer"}
|
||||
@ -53,7 +53,7 @@ Similar output to the following means your node was restarted and needs to decry
|
||||
The node will then try to connect to the [*JoinService*](../architecture/components.md#joinservice) and obtain the decryption key.
|
||||
If that fails, because the control plane is unhealthy, you will see log messages similar to the following:
|
||||
|
||||
```shell
|
||||
```json
|
||||
{"level":"INFO","ts":"2022-09-08T09:56:43Z","logger":"rejoinClient","caller":"rejoinclient/client.go:77","msg":"Received list with JoinService endpoints","endpoints":["10.9.0.5:30090","10.9.0.6:30090"]}
|
||||
{"level":"INFO","ts":"2022-09-08T09:56:43Z","logger":"rejoinClient","caller":"rejoinclient/client.go:96","msg":"Requesting rejoin ticket","endpoint":"10.9.0.5:30090"}
|
||||
{"level":"WARN","ts":"2022-09-08T09:57:03Z","logger":"rejoinClient","caller":"rejoinclient/client.go:101","msg":"Failed to rejoin on endpoint","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing dial tcp 10.9.0.5:30090: i/o timeout\"","endpoint":"10.9.0.5:30090"}
|
||||
@ -81,7 +81,7 @@ Check the serial console output of that instance by opening the *logs -> "Serial
|
||||
In the serial console output search for `Waiting for decryption key`.
|
||||
Similar output to the following means your node was restarted and needs to decrypt the [state disk](../architecture/images.md#state-disk):
|
||||
|
||||
```shell
|
||||
```json
|
||||
{"level":"INFO","ts":"2022-09-08T10:21:53Z","caller":"cmd/main.go:55","msg":"Starting disk-mapper","version":"2.0.0","cloudProvider":"gcp"}
|
||||
{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"setupManager","caller":"setup/setup.go:72","msg":"Preparing existing state disk"}
|
||||
{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:65","msg":"Starting RejoinClient"}
|
||||
@ -92,7 +92,7 @@ Similar output to the following means your node was restarted and needs to decry
|
||||
The node will then try to connect to the [*JoinService*](../architecture/components.md#joinservice) and obtain the decryption key.
|
||||
If that fails, because the control plane is unhealthy, you will see log messages similar to the following:
|
||||
|
||||
```shell
|
||||
```json
|
||||
{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:77","msg":"Received list with JoinService endpoints","endpoints":["192.168.178.4:30090","192.168.178.2:30090"]}
|
||||
{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:96","msg":"Requesting rejoin ticket","endpoint":"192.168.178.4:30090"}
|
||||
{"level":"WARN","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:101","msg":"Failed to rejoin on endpoint","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing dial tcp 192.168.178.4:30090: connect: connection refused\"","endpoint":"192.168.178.4:30090"}
|
||||
@ -127,14 +127,14 @@ The easiest approach is to set up a jump host connected to the VPC network and p
|
||||
|
||||
Given these prerequisites a node can be recovered like this:
|
||||
|
||||
```bash
|
||||
```
|
||||
$ constellation recover -e 34.107.89.208 --master-secret constellation-mastersecret.json
|
||||
Pushed recovery key.
|
||||
```
|
||||
|
||||
In the serial console output of the node you'll see a similar output to the following:
|
||||
|
||||
```shell
|
||||
```json
|
||||
{"level":"INFO","ts":"2022-09-08T10:26:59Z","logger":"recoveryServer","caller":"recoveryserver/server.go:93","msg":"Received recover call"}
|
||||
{"level":"INFO","ts":"2022-09-08T10:26:59Z","logger":"recoveryServer","caller":"recoveryserver/server.go:125","msg":"Received state disk key and measurement secret, shutting down server"}
|
||||
{"level":"INFO","ts":"2022-09-08T10:26:59Z","logger":"recoveryServer.gRPC","caller":"zap/server_interceptors.go:61","msg":"finished streaming call with code OK","grpc.start_time":"2022-09-08T10:26:59Z","system":"grpc","span.kind":"server","grpc.service":"recoverproto.API","grpc.method":"Recover","peer.address":"192.0.2.3:41752","grpc.code":"OK","grpc.time_ms":15.701}
|
||||
|
||||
@ -54,7 +54,7 @@ The following installation guide gives a brief overview of using CSI-based confi
|
||||
1. Install the CSI driver:
|
||||
|
||||
```bash
|
||||
helm install azuredisk-csi-driver charts/edgeless/latest/azuredisk-csi-driver.tgz \
|
||||
helm install azuredisk-csi-driver https://raw.githubusercontent.com/edgelesssys/constellation-azuredisk-csi-driver/main/charts/edgeless/latest/azuredisk-csi-driver.tgz \
|
||||
--namespace kube-system \
|
||||
--set linux.distro=fedora \
|
||||
--set controller.replicas=1
|
||||
@ -94,9 +94,7 @@ By default, integrity protection is disabled for performance reasons. If you wan
|
||||
1. Install the CSI driver:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver.git
|
||||
cd constellation-gcp-compute-persistent-disk-csi-driver
|
||||
kubectl apply -k ./deploy/kubernetes/overlays/edgeless/latest
|
||||
kubectl apply -k github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver/deploy/kubernetes/overlays/edgeless/latest
|
||||
```
|
||||
|
||||
2. Create a [storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/) for your driver
|
||||
|
||||
90
docs/versioned_docs/version-2.0/workflows/verify-cli.md
Normal file
90
docs/versioned_docs/version-2.0/workflows/verify-cli.md
Normal file
@ -0,0 +1,90 @@
|
||||
# Verify the CLI
|
||||
|
||||
Edgeless Systems uses [sigstore](https://www.sigstore.dev/) to ensure supply-chain security for the Constellation CLI and node images ("artifacts"). sigstore consists of three components: [Cosign](https://docs.sigstore.dev/cosign/overview), [Rekor](https://docs.sigstore.dev/rekor/overview), and Fulcio. Edgeless Systems uses Cosign to sign artifacts. All signatures are automatically uploaded to the public Rekor transparency log, which resides at https://rekor.sigstore.dev/.
|
||||
|
||||
:::note
|
||||
The public key for Edgeless Systems' long-term code-signing key is:
|
||||
```
|
||||
-----BEGIN PUBLIC KEY-----
|
||||
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEf8F1hpmwE+YCFXzjGtaQcrL6XZVT
|
||||
JmEe5iSLvG1SyQSAew7WdMKF6o9t8e2TFuCkzlOhhlws2OHWbiFZnFWCFw==
|
||||
-----END PUBLIC KEY-----
|
||||
```
|
||||
The public key is also available for download at https://edgeless.systems/es.pub and in the Twitter profile [@EdgelessSystems](https://twitter.com/EdgelessSystems).
|
||||
:::
|
||||
|
||||
The Rekor transparency log is a public append-only ledger that verifies and records signatures and associated metadata. The Rekor transparency log enables everyone to observe the sequence of (software) signatures issued by Edgeless Systems and many other parties. The transparency log allows for the public identification of dubious or malicious signatures.
|
||||
|
||||
You should always ensure that (1) your CLI executable was signed with the private key corresponding to the above public key and that (2) there is a corresponding entry in the Rekor transparency log. Both can be done as is described in the following.
|
||||
|
||||
:::info
|
||||
You don't need to verify the Constellation node images. This is done automatically by your CLI and the rest of Constellation.
|
||||
:::
|
||||
|
||||
## Verify the signature
|
||||
|
||||
First, [install the Cosign CLI](https://docs.sigstore.dev/cosign/installation). Next, verify the signature that accompanies your CLI executable, for example:
|
||||
|
||||
```shell-session
|
||||
$ cosign verify-blob --key https://edgeless.systems/es.pub --signature constellation-linux-amd64.sig constellation-linux-amd64
|
||||
|
||||
Verified OK
|
||||
```
|
||||
|
||||
The above performs an offline verification of the provided public key, signature, and executable. To also verify that a corresponding entry exists in the public Rekor transparency log, add the variable `COSIGN_EXPERIMENTAL=1`:
|
||||
|
||||
```shell-session
|
||||
$ COSIGN_EXPERIMENTAL=1 cosign verify-blob --key https://edgeless.systems/es.pub --signature constellation-linux-amd64.sig constellation-linux-amd64
|
||||
|
||||
tlog entry verified with uuid: 0629f03c379219f4ae1b99819fd4c266a39490a338ec24321198ba6ccc16f147 index: 3334047
|
||||
Verified OK
|
||||
```
|
||||
|
||||
🏁 You now know that your CLI executable was officially released and signed by Edgeless Systems.
|
||||
|
||||
## Optional: Manually inspect the transparency log
|
||||
|
||||
To further inspect the public Rekor transparency log, [install the Rekor CLI](https://docs.sigstore.dev/rekor/installation). A search for the CLI executable should give a single UUID. (Note that this UUID contains the UUID from the previous `cosign` command.)
|
||||
|
||||
```shell-session
|
||||
$ rekor-cli search --artifact constellation-linux-amd64
|
||||
|
||||
Found matching entries (listed by UUID):
|
||||
362f8ecba72f43260629f03c379219f4ae1b99819fd4c266a39490a338ec24321198ba6ccc16f147
|
||||
```
|
||||
|
||||
With this UUID you can get the full entry from the transparency log:
|
||||
|
||||
```shell-session
|
||||
$ rekor-cli get --uuid=362f8ecba72f43260629f03c379219f4ae1b99819fd4c266a39490a338ec24321198ba6ccc16f147
|
||||
|
||||
LogID: c0d23d6ad406973f9559f3ba2d1ca01f84147d8ffc5b8445c224f98b9591801d
|
||||
Index: 3334047
|
||||
IntegratedTime: 2022-08-31T08:36:25Z
|
||||
UUID: 0629f03c379219f4ae1b99819fd4c266a39490a338ec24321198ba6ccc16f147
|
||||
Body: {
|
||||
"HashedRekordObj": {
|
||||
"data": {
|
||||
"hash": {
|
||||
"algorithm": "sha256",
|
||||
"value": "7cdc7a7101b215058264279b8d8f624e4e48b6b42cd54857a5e02daf1a1b014c"
|
||||
}
|
||||
},
|
||||
"signature": {
|
||||
"content": "MEYCIQDdL8fuhtFk6ON4b6kW6bvLMXqvw37nm8/UiLcYKjogsAIhAODZCdS1HgHvFJ5KFxT1JZzRN2wPdn3HZsiP0+3q6zsL",
|
||||
"publicKey": {
|
||||
"content": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFZjhGMWhwbXdFK1lDRlh6akd0YVFjckw2WFpWVApKbUVlNWlTTHZHMVN5UVNBZXc3V2RNS0Y2bzl0OGUyVEZ1Q2t6bE9oaGx3czJPSFdiaUZabkZXQ0Z3PT0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg=="
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
The field `publicKey` should contain Edgeless Systems' public key in Base64 encoding.
|
||||
|
||||
You can get an exhaustive list of artifact signatures issued by Edgeless Systems via the following command:
|
||||
|
||||
```bash
|
||||
$ rekor-cli search --public-key https://edgeless.systems/es.pub --pki-format x509
|
||||
```
|
||||
|
||||
Edgeless Systems monitors this list to detect potential unauthorized use of its private key.
|
||||
@ -95,6 +95,11 @@
|
||||
"type": "generated-index"
|
||||
},
|
||||
"items": [
|
||||
{
|
||||
"type": "doc",
|
||||
"label": "Verify the CLI",
|
||||
"id": "workflows/verify-cli"
|
||||
},
|
||||
{
|
||||
"type": "doc",
|
||||
"label": "Create your cluster",
|
||||
@ -103,7 +108,7 @@
|
||||
{
|
||||
"type": "doc",
|
||||
"label": "Verify your cluster",
|
||||
"id": "workflows/verify"
|
||||
"id": "workflows/verify-cluster"
|
||||
},
|
||||
{
|
||||
"type": "doc",
|
||||
|
||||
Loading…
Reference in New Issue
Block a user