diff --git a/docs/docs/architecture/attestation.md b/docs/docs/architecture/attestation.md index 8f12b5851..9bd157460 100644 --- a/docs/docs/architecture/attestation.md +++ b/docs/docs/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements. @@ -153,8 +153,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -184,8 +184,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -217,8 +217,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses a hypervisor-based vTPM for runtime measurements. @@ -249,16 +249,16 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + ### CVM verification To verify the integrity of the received attestation statement, a chain of trust from the CVM technology to the interface providing the statement has to be established. For verification of the CVM technology, Constellation may expose additional options in its config file. - - + + On AWS, AMD SEV-SNP is used to provide runtime encryption to the VMs. An SEV-SNP attestation report is used to establish trust in the VM. @@ -279,8 +279,8 @@ You may customize certain parameters for verification of the attestation stateme This is the intermediate certificate for verifying the SEV-SNP report's signature. If it's not specified, the CLI fetches it from the AMD key distribution server. - - + + On Azure, AMD SEV-SNP is used to provide runtime encryption to the VMs. An SEV-SNP attestation report is used to establish trust in the vTPM running inside the VM. @@ -302,8 +302,8 @@ You may customize certain parameters for verification of the attestation stateme More explicitly, it controls the verification of the `IDKeyDigest` value in the SEV-SNP attestation report. You can provide a list of accepted key digests and specify a policy on how this list is compared against the reported `IDKeyDigest`. - - + + On GCP, AMD SEV-SNP is used to provide runtime encryption to the VMs. An SEV-SNP attestation report is used to establish trust in the VM. @@ -324,15 +324,15 @@ You may customize certain parameters for verification of the attestation stateme This is the intermediate certificate for verifying the SEV-SNP report's signature. If it's not specified, the CLI fetches it from the AMD key distribution server. - - + + On STACKIT, AMD SEV-ES is used to provide runtime encryption to the VMs. The hypervisor-based vTPM is used to establish trust in the VM via [runtime measurements](#runtime-measurements). There is no additional configuration available for STACKIT. - - + + ## Cluster attestation diff --git a/docs/docs/getting-started/first-steps-local.md b/docs/docs/getting-started/first-steps-local.md index 052d29eae..98f0302de 100644 --- a/docs/docs/getting-started/first-steps-local.md +++ b/docs/docs/getting-started/first-steps-local.md @@ -45,8 +45,8 @@ sudo iptables -P FORWARD ACCEPT ## Create a cluster - - + + 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/). @@ -74,8 +74,8 @@ 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. - - + + 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. @@ -145,8 +145,8 @@ attaching persistent storage, or autoscaling aren't available. export KUBECONFIG="$PWD/constellation-admin.conf" ``` - - + + ## Connect to the cluster @@ -199,8 +199,8 @@ worker-0 Ready 32s v1.24.6 ## Terminate your cluster - - + + Once you are done, you can clean up the created resources using the following command: @@ -211,8 +211,8 @@ 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. - - + + Once you are done, you can clean up the created resources using the following command: @@ -240,8 +240,8 @@ 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. - - + + ## Troubleshooting diff --git a/docs/docs/getting-started/first-steps.md b/docs/docs/getting-started/first-steps.md index 8c1da1967..9b37efa64 100644 --- a/docs/docs/getting-started/first-steps.md +++ b/docs/docs/getting-started/first-steps.md @@ -15,41 +15,41 @@ If you encounter any problem with the following steps, make sure to use the [lat 1. Create the [configuration file](../workflows/config.md) and state file for your cloud provider. If you are following the steps of this guide, there is no need to edit the file. - - + + ```bash constellation config generate aws ``` - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate stackit ``` - - + + 2. Create your [IAM configuration](../workflows/config.md#creating-an-iam-configuration). - - + + ```bash constellation iam create aws --zone=us-east-2a --prefix=constellTest --update-config @@ -76,8 +76,8 @@ If you encounter any problem with the following steps, make sure to use the [lat You can find a list of all [regions in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). - - + + ```bash constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest --update-config @@ -98,8 +98,8 @@ If you encounter any problem with the following steps, make sure to use the [lat You can find a list of all [regions in Azure's documentation](https://azure.microsoft.com/en-us/global-infrastructure/services/?products=virtual-machines®ions=all). - - + + ```bash constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west2-a --serviceAccountID=constell-test --update-config @@ -109,16 +109,16 @@ If you encounter any problem with the following steps, make sure to use the [lat Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available), which you can filter by machine type `C2D` or `N2D`. - - + + To use Constellation on STACKIT, the cluster will use the User Access Token (UAT) that's generated [during the install step](./install.md). After creating the accounts, fill in the STACKIT details in `constellation-conf.yaml` under `provider.openstack`: * `stackitProjectID`: STACKIT project id (can be found after login on the [STACKIT portal](https://portal.stackit.cloud)) - - + + :::tip To learn about all options you have for managing IAM resources and Constellation configuration, see the [Configuration workflow](../workflows/config.md). diff --git a/docs/docs/getting-started/install.md b/docs/docs/getting-started/install.md index 4ebd9351a..d52e43476 100644 --- a/docs/docs/getting-started/install.md +++ b/docs/docs/getting-started/install.md @@ -22,8 +22,8 @@ If you prefer to use Terraform, you can alternatively use the [Terraform provide The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -39,8 +39,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -56,9 +56,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -74,9 +74,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -92,9 +92,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -115,8 +115,8 @@ Invoke-WebRequest -OutFile ./constellation.exe -Uri 'https://github.com/edgeless 5. Click `New` 6. Enter the path to the folder containing the binary you want on your PATH: `C:\Program Files\Constellation\bin` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -132,8 +132,8 @@ If you don't have a cloud subscription, you can also set up a [local Constellati ### Required permissions - - + + To set up a Constellation cluster, you need to perform two tasks that require permissions: create the infrastructure and create roles for cluster nodes. Both of these actions can be performed by different users, e.g., an administrator to create roles and a DevOps engineer to create the infrastructure. @@ -183,8 +183,8 @@ The built-in `PowerUserAccess` policy is a superset of these permissions. Follow Amazon's guide on [understanding](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [managing policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html). - - + + The following [resource providers need to be registered](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) in your subscription: @@ -226,8 +226,8 @@ Follow Microsoft's guide on [understanding](https://learn.microsoft.com/en-us/az 1: You can omit `*/register/Action` if the resource providers mentioned above are already registered and the `ARM_SKIP_PROVIDER_REGISTRATION` environment variable is set to `true` when creating the IAM configuration. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. @@ -312,16 +312,16 @@ Together, the built-in roles `roles/editor`, `roles/compute.instanceAdmin` and ` Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + Constellation on STACKIT requires a User Access Token (UAT) for the OpenStack API and a STACKIT service account. The UAT already has all required permissions by default. The STACKIT service account needs the `editor` role to create STACKIT LoadBalancers. Look at the [STACKIT documentation](https://docs.stackit.cloud/stackit/en/getting-started-in-service-accounts-134415831.html) on how to create the service account and assign the role. - - + + ### Authentication @@ -331,8 +331,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -348,8 +348,8 @@ aws configure Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - - + + **Testing** @@ -365,8 +365,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -389,8 +389,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + You need to authenticate with the infrastructure API (OpenStack) and create a service account (STACKIT API). @@ -420,9 +420,9 @@ You need to authenticate with the infrastructure API (OpenStack) and create a se {"STACKIT_SERVICE_ACCOUNT_TOKEN":"REPLACE_WITH_TOKEN"} ``` - + - + ## Next steps diff --git a/docs/docs/getting-started/marketplaces.md b/docs/docs/getting-started/marketplaces.md index b16d796d2..a6763a42a 100644 --- a/docs/docs/getting-started/marketplaces.md +++ b/docs/docs/getting-started/marketplaces.md @@ -4,8 +4,8 @@ Constellation is available through the Marketplaces of AWS, Azure, GCP, and STAC This document explains how to run Constellation with the dynamically billed cloud marketplace images. - - + + To use Constellation's marketplace images, ensure that you are subscribed to the [marketplace offering](https://aws.amazon.com/marketplace/pp/prodview-2mbn65nv57oys) through the web portal. @@ -15,8 +15,8 @@ Then, enable the use of marketplace images in your Constellation `constellation- yq eval -i ".provider.aws.useMarketplaceImage = true" constellation-conf.yaml ``` - - + + Constellation has a private marketplace plan. Please [contact us](https://www.edgeless.systems/enterprise-support/) to gain access. @@ -32,8 +32,8 @@ Then, enable the use of marketplace images in your Constellation `constellation- yq eval -i ".provider.azure.useMarketplaceImage = true" constellation-conf.yaml ``` - - + + To use a marketplace image, ensure that the account is entitled to use marketplace images by Edgeless Systems by accepting the terms through the [web portal](https://console.cloud.google.com/marketplace/vm/config/edgeless-systems-public/constellation). @@ -43,13 +43,13 @@ Then, enable the use of marketplace images in your Constellation `constellation- yq eval -i ".provider.gcp.useMarketplaceImage = true" constellation-conf.yaml ``` - - + + On STACKIT, the selected Constellation image is always a marketplace image. You can find more information on the STACKIT portal. - - + + Ensure that the cluster uses an official release image version (i.e., `.image=vX.Y.Z` in the `constellation-conf.yaml` file). diff --git a/docs/docs/workflows/config.md b/docs/docs/workflows/config.md index 9da4305de..120bf8ed7 100644 --- a/docs/docs/workflows/config.md +++ b/docs/docs/workflows/config.md @@ -14,44 +14,44 @@ Before you can create your cluster, you need to configure the identity and acces You can generate a configuration file for your CSP by using the following CLI command: - - + + ```bash constellation config generate aws ``` - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate stackit ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. ## Choosing a VM type Constellation supports the following VM types: - - + + By default, Constellation uses `m6a.xlarge` 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. @@ -62,20 +62,20 @@ If you are using the attestation variant `awsNitroTPM`, you can choose any of th The Constellation CLI can also print the supported instance types with: `constellation config instance-types`. - - + + 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. You can also run `constellation config instance-types` to get the list of all supported options. - - + + 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 with a minimum of 4 vCPUs from the [C2D](https://cloud.google.com/compute/docs/compute-optimized-machines#c2d_machine_types) or [N2D](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) family. You can run `constellation config instance-types` to get the list of all supported options. - - + + By default, Constellation uses `m1a.4cd` VMs (4 vCPUs, 30 GB RAM) to create your cluster. Optionally, you can switch to a different VM type by modifying `instanceType` in the configuration file. @@ -93,8 +93,8 @@ You can choose any of the SEV-enabled instance types. You can find a list of all The Constellation CLI can also print the supported instance types with: `constellation config instance-types`. - - + + Fill the desired VM type into the `instanceType` fields in the `constellation-conf.yml` file. @@ -153,8 +153,8 @@ See also Constellation's [Kubernetes support policy](../architecture/versions.md You can create an IAM configuration for your cluster automatically using the `constellation iam create` command. If you already have a Constellation configuration file, you can add the `--update-config` flag to the command. This writes the needed IAM fields into your configuration. Furthermore, the flag updates the zone/region of the configuration if it hasn't been set yet. - - + + You must be authenticated with the [AWS CLI](https://aws.amazon.com/en/cli/) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -178,8 +178,8 @@ You can find a list of all [regions in AWS's documentation](https://docs.aws.ama Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -204,8 +204,8 @@ You can find a list of all [regions in Azure's documentation](https://azure.micr Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [GCP CLI](https://cloud.google.com/sdk/gcloud) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -219,21 +219,21 @@ Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + STACKIT requires manual creation and configuration of service accounts. Look at the [first steps](../getting-started/first-steps.md) for more information. - - + +
Alternatively, you can manually create the IAM configuration on your CSP. The following describes the configuration fields and how you obtain the required information or create the required resources. - - + + * **region**: The name of your chosen AWS data center region, e.g., `us-east-2`. @@ -264,8 +264,8 @@ The following describes the configuration fields and how you obtain the required Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.worker_node_policy`. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -301,8 +301,8 @@ The following describes the configuration fields and how you obtain the required The user-assigned identity is used by instances of the cluster to access other cloud resources. For more information about managed identities refer to [Azure's documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities). - - + + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -326,13 +326,13 @@ The following describes the configuration fields and how you obtain the required Afterward, create and download a new JSON key for this service account. Place the downloaded file in your Constellation workspace, and set the config parameter to the filename, e.g., `constellation-129857-15343dba46cb.json`. - - + + STACKIT requires manual creation and configuration of service accounts. Look at the [first steps](../getting-started/first-steps.md) for more information. - - + +
Now that you've configured your CSP, you can [create your cluster](./create.md). diff --git a/docs/docs/workflows/create.md b/docs/docs/workflows/create.md index 388cbedf8..6074ebb16 100644 --- a/docs/docs/workflows/create.md +++ b/docs/docs/workflows/create.md @@ -27,8 +27,8 @@ If you don't have a cloud subscription, you can also set up a [local Constellati Before you create the cluster, make sure to have a [valid configuration file](./config.md). - - + + ```bash constellation apply @@ -36,8 +36,8 @@ constellation apply `apply` stores the state of your cluster's cloud resources in a [`constellation-terraform`](../architecture/orchestration.md#cluster-creation-process) directory in your workspace. - - + + Self-managed infrastructure allows for more flexibility in the setup, by separating the infrastructure setup from the Constellation cluster management. This provides flexibility in DevOps and can meet potential regulatory requirements. @@ -77,8 +77,8 @@ With the required cloud resources set up, continue with initializing your cluste constellation apply --skip-phases=infrastructure ``` - - + + Finally, configure `kubectl` for your cluster: diff --git a/docs/docs/workflows/recovery.md b/docs/docs/workflows/recovery.md index aea370e2f..50cd7ee72 100644 --- a/docs/docs/workflows/recovery.md +++ b/docs/docs/workflows/recovery.md @@ -16,8 +16,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via serial console output. In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + First, open the AWS console to view all Auto Scaling Groups (ASGs) in the region of your cluster. Select the ASG of the control plane `--control-plane` and check that enough members are in a *Running* state. @@ -47,8 +47,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -82,8 +82,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -118,8 +118,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, open the STACKIT portal to view all servers in your project. Select individual control plane nodes `--control-plane--` and check that enough members are in a *Running* state. @@ -149,8 +149,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + ## Recover a cluster diff --git a/docs/docs/workflows/scale.md b/docs/docs/workflows/scale.md index 0b52b9540..28f19e3f1 100644 --- a/docs/docs/workflows/scale.md +++ b/docs/docs/workflows/scale.md @@ -51,36 +51,36 @@ kubectl -n kube-system get nodes Alternatively, you can manually scale your cluster up or down: - - + + 1. Go to Auto Scaling Groups and select the worker ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + Dynamic cluster scaling isn't yet supported for STACKIT. Support will be introduced in one of the upcoming releases. - - + + ## Control-plane node scaling @@ -88,35 +88,35 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - - + + 1. Go to Auto Scaling Groups and select the control-plane ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + Dynamic cluster scaling isn't yet supported for STACKIT. Support will be introduced in one of the upcoming releases. - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/docs/workflows/storage.md b/docs/docs/workflows/storage.md index f1344d6ad..a5c52be90 100644 --- a/docs/docs/workflows/storage.md +++ b/docs/docs/workflows/storage.md @@ -21,37 +21,37 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for AWS Elastic Block Store** Mount [Elastic Block Store](https://aws.amazon.com/ebs/) storage volumes into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-aws-ebs-csi-driver) for more information. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as `ReadWriteOnce`, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for more information. - - + + **Constellation CSI driver for STACKIT / OpenStack Cinder** Mount [Cinder](https://docs.openstack.org/cinder/latest/) block storage volumes into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-cloud-provider-openstack) for more information. - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [AWS EFS](https://docs.aws.amazon.com/en_en/eks/latest/userguide/efs-csi.html), [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction), or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -60,8 +60,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The Constellation CLI automatically installs Constellation's CSI driver for the selected CSP in your cluster. If you don't need a CSI driver or wish to deploy your own, you can disable the automatic installation by setting `deployCSIDriver` to `false` in your Constellation config file. - - + + AWS comes with two storage classes by default. @@ -89,8 +89,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + Azure comes with two storage classes by default. @@ -118,8 +118,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + GCP comes with two storage classes by default. @@ -147,8 +147,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + STACKIT comes with two storage classes by default. @@ -176,8 +176,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + 1. Create a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) diff --git a/docs/docs/workflows/terminate.md b/docs/docs/workflows/terminate.md index 11bbbb2ac..2c45bebe3 100644 --- a/docs/docs/workflows/terminate.md +++ b/docs/docs/workflows/terminate.md @@ -16,8 +16,8 @@ All ephemeral storage and state of your cluster will be lost. Make sure any data ::: - - + + Terminate the cluster by running: ```bash @@ -40,8 +40,8 @@ resources manually. Just run the `terminate` command again afterward to continue ::: - - + + Terminate the cluster by running: ```bash @@ -56,5 +56,5 @@ rm constellation-state.yaml constellation-admin.conf Only the `constellation-mastersecret.json` and the configuration file remain. - - + + diff --git a/docs/docs/workflows/terraform-provider.md b/docs/docs/workflows/terraform-provider.md index 8a3cedc62..ed8f46eda 100644 --- a/docs/docs/workflows/terraform-provider.md +++ b/docs/docs/workflows/terraform-provider.md @@ -21,8 +21,9 @@ This example shows how to set up a Constellation cluster with the reference IAM 2. Use one of the [example configurations for using the Constellation Terraform provider](https://github.com/edgelesssys/constellation/tree/main/terraform-provider-constellation/examples/full) or create a `main.tf` file and fill it with the resources you want to create. The [Constellation Terraform provider documentation](https://registry.terraform.io/providers/edgelesssys/constellation/latest) offers thorough documentation on the resources and their attributes. 3. Initialize and apply the Terraform configuration. - - + + + Initialize the providers and apply the configuration. ```bash @@ -31,8 +32,8 @@ This example shows how to set up a Constellation cluster with the reference IAM ``` Optionally, you can prefix the `terraform apply` command with `TF_LOG=INFO` to collect [Terraform logs](https://developer.hashicorp.com/terraform/internals/debugging) while applying the configuration. This may provide helpful output in debugging scenarios. - - + + When creating a cluster on Azure, you need to manually patch the policy of the MAA provider before creating the Constellation cluster, as this feature isn't available in Azure's Terraform provider yet. The Constellation CLI provides a utility for patching, but you can also do it manually. @@ -66,8 +67,8 @@ This example shows how to set up a Constellation cluster with the reference IAM }; ``` - - + + Initialize the providers and apply the configuration. ```bash @@ -76,8 +77,8 @@ This example shows how to set up a Constellation cluster with the reference IAM ``` Optionally, you can prefix the `terraform apply` command with `TF_LOG=INFO` to collect [Terraform logs](https://developer.hashicorp.com/terraform/internals/debugging) while applying the configuration. This may provide helpful output in debugging scenarios. - - + + Initialize the providers and apply the configuration. ```bash @@ -86,9 +87,9 @@ This example shows how to set up a Constellation cluster with the reference IAM ``` Optionally, you can prefix the `terraform apply` command with `TF_LOG=INFO` to collect [Terraform logs](https://developer.hashicorp.com/terraform/internals/debugging) while applying the configuration. This may provide helpful output in debugging scenarios. - + - + 4. Connect to the cluster. ```bash diff --git a/docs/versioned_docs/version-2.0/architecture/attestation.md b/docs/versioned_docs/version-2.0/architecture/attestation.md index 443c19639..92ee2e9a2 100644 --- a/docs/versioned_docs/version-2.0/architecture/attestation.md +++ b/docs/versioned_docs/version-2.0/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -149,8 +149,8 @@ The latter means that the value can be generated offline and compared to the one | 12 | ClusterID | Constellation Bootstrapper | Yes | | 13–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -179,8 +179,8 @@ The latter means that the value can be generated offline and compared to the one | 12 | ClusterID | Constellation Bootstrapper | Yes | | 13–23 | Unused |- | - | - - + + ## Cluster attestation 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 9be306396..08adfbd12 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 @@ -6,29 +6,29 @@ The following steps guide you through the process of creating a cluster and depl 1. Create the configuration file for your selected cloud provider. - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + This creates the file `constellation-conf.yaml` in your current working directory. 2. Fill in your cloud provider specific information. - - + + You need several resources for the cluster. You can use the following `az` script to create them: @@ -59,8 +59,8 @@ The following steps guide you through the process of creating a cluster and depl Run `constellation config instance-types` to get the list of all supported options. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -106,8 +106,8 @@ The following steps guide you through the process of creating a cluster and depl Run `constellation config instance-types` to get the list of all supported options. - - + + You need a service account for the cluster. You can use the following `gcloud` script to create it: @@ -130,8 +130,8 @@ The following steps guide you through the process of creating a cluster and depl 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. - - + + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -159,8 +159,8 @@ The following steps guide you through the process of creating a cluster and depl Supported are all machines from the N2D family with a minimum of 4 vCPUs. It defaults to `n2d-standard-4` (4 vCPUs, 16 GB RAM), but you can use any other VMs from the same 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. - - + + :::info diff --git a/docs/versioned_docs/version-2.0/getting-started/install.md b/docs/versioned_docs/version-2.0/getting-started/install.md index 8e3545c1a..5945f0405 100644 --- a/docs/versioned_docs/version-2.0/getting-started/install.md +++ b/docs/versioned_docs/version-2.0/getting-started/install.md @@ -18,8 +18,8 @@ Make sure the following requirements are met: The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -35,8 +35,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -52,10 +52,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` + - - - + 1. Download the CLI: @@ -71,11 +70,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` + - - - - + 1. Download the CLI: @@ -91,8 +88,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -104,8 +101,8 @@ The CLI makes authenticated calls to the CSP API. Therefore, you need to set up ### Required permissions - - + + You need the following permissions for your user account: @@ -115,8 +112,8 @@ You need the following permissions for your user account: If you don't have these permissions with scope *subscription*, ask your administrator to [create the service account and a resource group for your Constellation cluster](first-steps.md). Your user account needs the `Contributor` permission scoped to this resource group. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. @@ -128,8 +125,8 @@ You need the following permissions on this project: Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + ### Authentication @@ -139,8 +136,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -156,8 +153,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -180,8 +177,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + ## Next steps diff --git a/docs/versioned_docs/version-2.0/workflows/create.md b/docs/versioned_docs/version-2.0/workflows/create.md index 1dd1088d5..a426202e5 100644 --- a/docs/versioned_docs/version-2.0/workflows/create.md +++ b/docs/versioned_docs/version-2.0/workflows/create.md @@ -15,22 +15,22 @@ This step creates the necessary resources for your cluster in your cloud environ Generate a configuration file for your cloud service provider (CSP): - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. [Fill in your CSP-specific information](../getting-started/first-steps.md#create-a-cluster) before you continue. diff --git a/docs/versioned_docs/version-2.0/workflows/recovery.md b/docs/versioned_docs/version-2.0/workflows/recovery.md index 4c6010d98..ca37ca839 100644 --- a/docs/versioned_docs/version-2.0/workflows/recovery.md +++ b/docs/versioned_docs/version-2.0/workflows/recovery.md @@ -17,8 +17,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via [cloud logging](troubleshooting.md#cloud-logging). In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -52,8 +52,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. For this, you need its IP address, which you can obtain from the *Overview* page under *Private IP address*. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -88,8 +88,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. For this, you need its IP address, which you can obtain from the **VM Instance** > **network interfaces** table under *Primary internal IP address*. - - + + ## Recover a cluster diff --git a/docs/versioned_docs/version-2.0/workflows/scale.md b/docs/versioned_docs/version-2.0/workflows/scale.md index 3318d8aee..84773b80c 100644 --- a/docs/versioned_docs/version-2.0/workflows/scale.md +++ b/docs/versioned_docs/version-2.0/workflows/scale.md @@ -6,23 +6,23 @@ Constellation provides all features of a Kubernetes cluster including scaling an [During cluster initialization](create.md#the-init-step) you can choose to deploy the [cluster autoscaler](https://github.com/kubernetes/autoscaler). It automatically provisions additional worker nodes so that all pods have a place to run. Alternatively, you can choose to manually scale your cluster up or down: - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + ## Control-plane node scaling @@ -30,23 +30,23 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - + - + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/versioned_docs/version-2.0/workflows/storage.md b/docs/versioned_docs/version-2.0/workflows/storage.md index 958c73261..38d77c694 100644 --- a/docs/versioned_docs/version-2.0/workflows/storage.md +++ b/docs/versioned_docs/version-2.0/workflows/storage.md @@ -21,14 +21,14 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as ReadWriteOnce, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. @@ -36,8 +36,8 @@ This includes support for [volume snapshots](https://cloud.google.com/kubernetes You can use them to bring a volume back to a prior state or provision new volumes. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for information about the configuration. - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction) or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -45,8 +45,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The following installation guide gives an overview of how to securely use CSI-based cloud storage for persistent volumes in Constellation. - - + + 1. Install the driver: @@ -56,8 +56,8 @@ The following installation guide gives an overview of how to securely use CSI-ba helm install azuredisk-csi-driver charts/edgeless --namespace kube-system ``` - - + + 1. Install the driver: @@ -66,8 +66,8 @@ The following installation guide gives an overview of how to securely use CSI-ba helm install gcp-compute-persistent-disk-csi-driver charts/ --namespace kube-system ``` - - + + :::info @@ -138,8 +138,8 @@ The default storage class is responsible for all persistent volume claims that d The previous instructions create a storage class with encryption enabled and sets this as the default class. In case you wish to change it, follow the steps below: - - + + 1. List the storage classes in your cluster: @@ -185,8 +185,8 @@ In case you wish to change it, follow the steps below: integrity-encrypted-rwo (default) azuredisk.csi.confidential.cloud Delete Immediate false 1d ``` - - + + 1. List the storage classes in your cluster: @@ -232,5 +232,5 @@ In case you wish to change it, follow the steps below: integrity-encrypted-rwo (default) gcp.csi.confidential.cloud Delete Immediate false 1d ``` - - + + diff --git a/docs/versioned_docs/version-2.0/workflows/troubleshooting.md b/docs/versioned_docs/version-2.0/workflows/troubleshooting.md index ba340601b..afc9274c6 100644 --- a/docs/versioned_docs/version-2.0/workflows/troubleshooting.md +++ b/docs/versioned_docs/version-2.0/workflows/troubleshooting.md @@ -8,8 +8,8 @@ To provide information during early stages of the node's boot process, Constella You can view these information in the follow places: - - + + 1. In your Azure subscription find the Constellation resource group. 2. Inside the resource group find the Application Insights resource called `constellation-insights-*`. @@ -19,8 +19,8 @@ You can view these information in the follow places: To **find the disk UUIDs** use the following query: `traces | where message contains "Disk UUID"` - - + + 1. Select the project that hosts Constellation. 2. Go to the `Compute Engine` service. @@ -35,5 +35,5 @@ Constellation uses the default bucket to store logs. Its [default retention peri ::: - - + + diff --git a/docs/versioned_docs/version-2.1/architecture/attestation.md b/docs/versioned_docs/version-2.1/architecture/attestation.md index 443c19639..92ee2e9a2 100644 --- a/docs/versioned_docs/version-2.1/architecture/attestation.md +++ b/docs/versioned_docs/version-2.1/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -149,8 +149,8 @@ The latter means that the value can be generated offline and compared to the one | 12 | ClusterID | Constellation Bootstrapper | Yes | | 13–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -179,8 +179,8 @@ The latter means that the value can be generated offline and compared to the one | 12 | ClusterID | Constellation Bootstrapper | Yes | | 13–23 | Unused |- | - | - - + + ## Cluster attestation 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 bd9513650..d729fd0cf 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 @@ -11,29 +11,29 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step 1. Create the configuration file for your selected cloud provider. - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + This creates the file `constellation-conf.yaml` in your current working directory. 2. Fill in your cloud provider specific information. - - + + You need several resources for the cluster. You can use the following `az` script to create them: @@ -64,8 +64,8 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step Run `constellation config instance-types` to get the list of all supported options. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -111,8 +111,8 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step Run `constellation config instance-types` to get the list of all supported options. - - + + You need a service account for the cluster. You can use the following `gcloud` script to create it: @@ -135,8 +135,8 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step 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. - - + + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -164,8 +164,8 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step Supported are all machines from the N2D family with a minimum of 4 vCPUs. It defaults to `n2d-standard-4` (4 vCPUs, 16 GB RAM), but you can use any other VMs from the same 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. - - + + :::info 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 56029b806..d4cf81ff7 100644 --- a/docs/versioned_docs/version-2.1/getting-started/install.md +++ b/docs/versioned_docs/version-2.1/getting-started/install.md @@ -18,8 +18,8 @@ Make sure the following requirements are met: The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -35,8 +35,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -52,10 +52,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` + - - - + 1. Download the CLI: @@ -71,11 +70,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` + - - - - + 1. Download the CLI: @@ -91,8 +88,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -108,8 +105,8 @@ If you don't have a cloud subscription, you can try [MiniConstellation](first-st ### Required permissions - - + + You need the following permissions for your user account: @@ -119,8 +116,8 @@ You need the following permissions for your user account: If you don't have these permissions with scope *subscription*, ask your administrator to [create the service account and a resource group for your Constellation cluster](first-steps.md). Your user account needs the `Contributor` permission scoped to this resource group. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. @@ -132,8 +129,8 @@ You need the following permissions on this project: Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + ### Authentication @@ -143,8 +140,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -160,8 +157,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -184,8 +181,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + ## Next steps diff --git a/docs/versioned_docs/version-2.1/workflows/create.md b/docs/versioned_docs/version-2.1/workflows/create.md index b95ffb5fd..a8956d7e4 100644 --- a/docs/versioned_docs/version-2.1/workflows/create.md +++ b/docs/versioned_docs/version-2.1/workflows/create.md @@ -19,22 +19,22 @@ This step creates the necessary resources for your cluster in your cloud environ Generate a configuration file for your cloud service provider (CSP): - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. [Fill in your CSP-specific information](../getting-started/first-steps.md#create-a-cluster) before you continue. diff --git a/docs/versioned_docs/version-2.1/workflows/recovery.md b/docs/versioned_docs/version-2.1/workflows/recovery.md index cde039ea7..c55daf413 100644 --- a/docs/versioned_docs/version-2.1/workflows/recovery.md +++ b/docs/versioned_docs/version-2.1/workflows/recovery.md @@ -16,8 +16,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via [cloud logging](troubleshooting.md#cloud-logging). In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -51,8 +51,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -87,8 +87,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + ## Recover a cluster diff --git a/docs/versioned_docs/version-2.1/workflows/scale.md b/docs/versioned_docs/version-2.1/workflows/scale.md index 1c8757fe8..669856655 100644 --- a/docs/versioned_docs/version-2.1/workflows/scale.md +++ b/docs/versioned_docs/version-2.1/workflows/scale.md @@ -48,23 +48,23 @@ kubectl -n kube-system get nodes Alternatively, you can manually scale your cluster up or down: - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + ## Control-plane node scaling @@ -72,23 +72,23 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - + - + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/versioned_docs/version-2.1/workflows/storage.md b/docs/versioned_docs/version-2.1/workflows/storage.md index 958c73261..38d77c694 100644 --- a/docs/versioned_docs/version-2.1/workflows/storage.md +++ b/docs/versioned_docs/version-2.1/workflows/storage.md @@ -21,14 +21,14 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as ReadWriteOnce, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. @@ -36,8 +36,8 @@ This includes support for [volume snapshots](https://cloud.google.com/kubernetes You can use them to bring a volume back to a prior state or provision new volumes. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for information about the configuration. - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction) or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -45,8 +45,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The following installation guide gives an overview of how to securely use CSI-based cloud storage for persistent volumes in Constellation. - - + + 1. Install the driver: @@ -56,8 +56,8 @@ The following installation guide gives an overview of how to securely use CSI-ba helm install azuredisk-csi-driver charts/edgeless --namespace kube-system ``` - - + + 1. Install the driver: @@ -66,8 +66,8 @@ The following installation guide gives an overview of how to securely use CSI-ba helm install gcp-compute-persistent-disk-csi-driver charts/ --namespace kube-system ``` - - + + :::info @@ -138,8 +138,8 @@ The default storage class is responsible for all persistent volume claims that d The previous instructions create a storage class with encryption enabled and sets this as the default class. In case you wish to change it, follow the steps below: - - + + 1. List the storage classes in your cluster: @@ -185,8 +185,8 @@ In case you wish to change it, follow the steps below: integrity-encrypted-rwo (default) azuredisk.csi.confidential.cloud Delete Immediate false 1d ``` - - + + 1. List the storage classes in your cluster: @@ -232,5 +232,5 @@ In case you wish to change it, follow the steps below: integrity-encrypted-rwo (default) gcp.csi.confidential.cloud Delete Immediate false 1d ``` - - + + diff --git a/docs/versioned_docs/version-2.1/workflows/troubleshooting.md b/docs/versioned_docs/version-2.1/workflows/troubleshooting.md index ba340601b..afc9274c6 100644 --- a/docs/versioned_docs/version-2.1/workflows/troubleshooting.md +++ b/docs/versioned_docs/version-2.1/workflows/troubleshooting.md @@ -8,8 +8,8 @@ To provide information during early stages of the node's boot process, Constella You can view these information in the follow places: - - + + 1. In your Azure subscription find the Constellation resource group. 2. Inside the resource group find the Application Insights resource called `constellation-insights-*`. @@ -19,8 +19,8 @@ You can view these information in the follow places: To **find the disk UUIDs** use the following query: `traces | where message contains "Disk UUID"` - - + + 1. Select the project that hosts Constellation. 2. Go to the `Compute Engine` service. @@ -35,5 +35,5 @@ Constellation uses the default bucket to store logs. Its [default retention peri ::: - - + + diff --git a/docs/versioned_docs/version-2.10/architecture/attestation.md b/docs/versioned_docs/version-2.10/architecture/attestation.md index 07ac3aa72..592063193 100644 --- a/docs/versioned_docs/version-2.10/architecture/attestation.md +++ b/docs/versioned_docs/version-2.10/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -152,8 +152,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -185,8 +185,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements. @@ -217,16 +217,16 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + ### CVM verification To verify the integrity of the received attestation statement, a chain of trust from the CVM technology to the interface providing the statement has to be established. For verification of the CVM technology, Constellation may expose additional options in its config file. - - + + On Azure, AMD SEV-SNP is used to provide runtime encryption to the VMs. An SEV-SNP attestation report is used to establish trust in the vTPM running inside the VM. @@ -248,18 +248,18 @@ You may customize certain parameters for verification of the attestation stateme More explicitly, it controls the verification of the `IDKeyDigest` value in the SEV-SNP attestation report. You can provide a list of accepted key digests and specify a policy on how this list is compared against the reported `IDKeyDigest`. - - + + There is no additional configuration available for GCP. - - + + There is no additional configuration available for AWS. - - + + ## Cluster attestation diff --git a/docs/versioned_docs/version-2.10/getting-started/first-steps-local.md b/docs/versioned_docs/version-2.10/getting-started/first-steps-local.md index de9c66e9b..a6e825906 100644 --- a/docs/versioned_docs/version-2.10/getting-started/first-steps-local.md +++ b/docs/versioned_docs/version-2.10/getting-started/first-steps-local.md @@ -45,8 +45,8 @@ sudo iptables -P FORWARD ACCEPT ## Create a cluster - - + + 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/). @@ -74,8 +74,8 @@ 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. - - + + 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. @@ -151,8 +151,8 @@ attaching persistent storage, or autoscaling aren't available. export KUBECONFIG="$PWD/constellation-admin.conf" ``` - - + + ## Connect to the cluster @@ -205,8 +205,8 @@ worker-0 Ready 32s v1.24.6 ## Terminate your cluster - - + + Once you are done, you can clean up the created resources using the following command: @@ -217,8 +217,8 @@ 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. - - + + Once you are done, you can clean up the created resources using the following command: @@ -246,8 +246,8 @@ 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. - - + + ## Troubleshooting diff --git a/docs/versioned_docs/version-2.10/getting-started/first-steps.md b/docs/versioned_docs/version-2.10/getting-started/first-steps.md index 0b224e04d..9f6034e6b 100644 --- a/docs/versioned_docs/version-2.10/getting-started/first-steps.md +++ b/docs/versioned_docs/version-2.10/getting-started/first-steps.md @@ -15,39 +15,39 @@ If you encounter any problem with the following steps, make sure to use the [lat 1. Create the [configuration file](../workflows/config.md) for your cloud provider. - + - + ```bash constellation config generate azure ``` - + - + ```bash constellation config generate gcp ``` - + - + ```bash constellation config generate aws ``` - + - + 2. Create your [IAM configuration](../workflows/config.md#creating-an-iam-configuration). - + - + ```bash constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest --update-config @@ -62,9 +62,9 @@ If you encounter any problem with the following steps, make sure to use the [lat * `westeurope` * `southeastasia` - + - + ```bash constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west2-a --serviceAccountID=constell-test --update-config @@ -74,9 +74,9 @@ If you encounter any problem with the following steps, make sure to use the [lat Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available), which you can filter by machine type `C2D` or `N2D`. - + - + ```bash constellation iam create aws --zone=us-east-2a --prefix=constellTest --update-config @@ -103,8 +103,8 @@ If you encounter any problem with the following steps, make sure to use the [lat You can find a list of all [regions in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). - - + + :::tip To learn about all options you have for managing IAM resources and Constellation configuration, see the [Configuration workflow](../workflows/config.md). diff --git a/docs/versioned_docs/version-2.10/getting-started/install.md b/docs/versioned_docs/version-2.10/getting-started/install.md index 1a90b6513..c21ad259c 100644 --- a/docs/versioned_docs/version-2.10/getting-started/install.md +++ b/docs/versioned_docs/version-2.10/getting-started/install.md @@ -18,8 +18,8 @@ Make sure the following requirements are met: The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -35,8 +35,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -52,9 +52,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -70,9 +70,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -88,8 +88,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -105,39 +105,42 @@ If you don't have a cloud subscription, you can also set up a [local Constellati ### Required permissions - - + + The following [resource providers need to be registered](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) in your subscription: -* `Microsoft.Attestation` -* `Microsoft.Compute` -* `Microsoft.Insights` -* `Microsoft.ManagedIdentity` -* `Microsoft.Network` + +- `Microsoft.Attestation` +- `Microsoft.Compute` +- `Microsoft.Insights` +- `Microsoft.ManagedIdentity` +- `Microsoft.Network` By default, Constellation tries to register these automatically if they haven't been registered before. To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: -* `*/register/action` \[1] -* `Microsoft.Authorization/roleAssignments/*` -* `Microsoft.Authorization/roleDefinitions/*` -* `Microsoft.ManagedIdentity/userAssignedIdentities/*` -* `Microsoft.Resources/subscriptions/resourcegroups/*` + +- `*/register/action` \[1] +- `Microsoft.Authorization/roleAssignments/*` +- `Microsoft.Authorization/roleDefinitions/*` +- `Microsoft.ManagedIdentity/userAssignedIdentities/*` +- `Microsoft.Resources/subscriptions/resourcegroups/*` The built-in `Owner` role is a superset of these permissions. To [create a Constellation cluster](../workflows/create.md#the-create-step), you need the following permissions: -* `Microsoft.Attestation/attestationProviders/*` -* `Microsoft.Compute/virtualMachineScaleSets/*` -* `Microsoft.Insights/components/*` -* `Microsoft.ManagedIdentity/userAssignedIdentities/*` -* `Microsoft.Network/loadBalancers/*` -* `Microsoft.Network/loadBalancers/backendAddressPools/*` -* `Microsoft.Network/networkSecurityGroups/*` -* `Microsoft.Network/publicIPAddresses/*` -* `Microsoft.Network/virtualNetworks/*` -* `Microsoft.Network/virtualNetworks/subnets/*` -* `Microsoft.Network/natGateways/*` + +- `Microsoft.Attestation/attestationProviders/*` +- `Microsoft.Compute/virtualMachineScaleSets/*` +- `Microsoft.Insights/components/*` +- `Microsoft.ManagedIdentity/userAssignedIdentities/*` +- `Microsoft.Network/loadBalancers/*` +- `Microsoft.Network/loadBalancers/backendAddressPools/*` +- `Microsoft.Network/networkSecurityGroups/*` +- `Microsoft.Network/publicIPAddresses/*` +- `Microsoft.Network/virtualNetworks/*` +- `Microsoft.Network/virtualNetworks/subnets/*` +- `Microsoft.Network/natGateways/*` The built-in `Contributor` role is a superset of these permissions. @@ -145,89 +148,91 @@ Follow Microsoft's guide on [understanding](https://learn.microsoft.com/en-us/az 1: You can omit `*/register/Action` if the resource providers mentioned above are already registered and the `ARM_SKIP_PROVIDER_REGISTRATION` environment variable is set to `true` when creating the IAM configuration. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: -* `iam.serviceAccountKeys.create` -* `iam.serviceAccountKeys.delete` -* `iam.serviceAccountKeys.get` -* `iam.serviceAccounts.create` -* `iam.serviceAccounts.delete` -* `iam.serviceAccounts.get` -* `resourcemanager.projects.getIamPolicy` -* `resourcemanager.projects.setIamPolicy` + +- `iam.serviceAccountKeys.create` +- `iam.serviceAccountKeys.delete` +- `iam.serviceAccountKeys.get` +- `iam.serviceAccounts.create` +- `iam.serviceAccounts.delete` +- `iam.serviceAccounts.get` +- `resourcemanager.projects.getIamPolicy` +- `resourcemanager.projects.setIamPolicy` Together, the built-in roles `roles/editor` and `roles/resourcemanager.projectIamAdmin` form a superset of these permissions. To [create a Constellation cluster](../workflows/create.md#the-create-step), you need the following permissions: -* `compute.addresses.createInternal` -* `compute.addresses.deleteInternal` -* `compute.addresses.get` -* `compute.addresses.useInternal` -* `compute.backendServices.create` -* `compute.backendServices.delete` -* `compute.backendServices.get` -* `compute.backendServices.use` -* `compute.disks.create` -* `compute.firewalls.create` -* `compute.firewalls.delete` -* `compute.firewalls.get` -* `compute.globalAddresses.create` -* `compute.globalAddresses.delete` -* `compute.globalAddresses.get` -* `compute.globalAddresses.use` -* `compute.globalForwardingRules.create` -* `compute.globalForwardingRules.delete` -* `compute.globalForwardingRules.get` -* `compute.globalForwardingRules.setLabels` -* `compute.globalOperations.get` -* `compute.healthChecks.create` -* `compute.healthChecks.delete` -* `compute.healthChecks.get` -* `compute.healthChecks.useReadOnly` -* `compute.instanceGroupManagers.create` -* `compute.instanceGroupManagers.delete` -* `compute.instanceGroupManagers.get` -* `compute.instanceGroups.create` -* `compute.instanceGroups.delete` -* `compute.instanceGroups.get` -* `compute.instanceGroups.use` -* `compute.instances.create` -* `compute.instances.setLabels` -* `compute.instances.setMetadata` -* `compute.instances.setTags` -* `compute.instanceTemplates.create` -* `compute.instanceTemplates.delete` -* `compute.instanceTemplates.get` -* `compute.instanceTemplates.useReadOnly` -* `compute.networks.create` -* `compute.networks.delete` -* `compute.networks.get` -* `compute.networks.updatePolicy` -* `compute.routers.create` -* `compute.routers.delete` -* `compute.routers.get` -* `compute.routers.update` -* `compute.subnetworks.create` -* `compute.subnetworks.delete` -* `compute.subnetworks.get` -* `compute.subnetworks.use` -* `compute.targetTcpProxies.create` -* `compute.targetTcpProxies.delete` -* `compute.targetTcpProxies.get` -* `compute.targetTcpProxies.use` -* `iam.serviceAccounts.actAs` + +- `compute.addresses.createInternal` +- `compute.addresses.deleteInternal` +- `compute.addresses.get` +- `compute.addresses.useInternal` +- `compute.backendServices.create` +- `compute.backendServices.delete` +- `compute.backendServices.get` +- `compute.backendServices.use` +- `compute.disks.create` +- `compute.firewalls.create` +- `compute.firewalls.delete` +- `compute.firewalls.get` +- `compute.globalAddresses.create` +- `compute.globalAddresses.delete` +- `compute.globalAddresses.get` +- `compute.globalAddresses.use` +- `compute.globalForwardingRules.create` +- `compute.globalForwardingRules.delete` +- `compute.globalForwardingRules.get` +- `compute.globalForwardingRules.setLabels` +- `compute.globalOperations.get` +- `compute.healthChecks.create` +- `compute.healthChecks.delete` +- `compute.healthChecks.get` +- `compute.healthChecks.useReadOnly` +- `compute.instanceGroupManagers.create` +- `compute.instanceGroupManagers.delete` +- `compute.instanceGroupManagers.get` +- `compute.instanceGroups.create` +- `compute.instanceGroups.delete` +- `compute.instanceGroups.get` +- `compute.instanceGroups.use` +- `compute.instances.create` +- `compute.instances.setLabels` +- `compute.instances.setMetadata` +- `compute.instances.setTags` +- `compute.instanceTemplates.create` +- `compute.instanceTemplates.delete` +- `compute.instanceTemplates.get` +- `compute.instanceTemplates.useReadOnly` +- `compute.networks.create` +- `compute.networks.delete` +- `compute.networks.get` +- `compute.networks.updatePolicy` +- `compute.routers.create` +- `compute.routers.delete` +- `compute.routers.get` +- `compute.routers.update` +- `compute.subnetworks.create` +- `compute.subnetworks.delete` +- `compute.subnetworks.get` +- `compute.subnetworks.use` +- `compute.targetTcpProxies.create` +- `compute.targetTcpProxies.delete` +- `compute.targetTcpProxies.get` +- `compute.targetTcpProxies.use` +- `iam.serviceAccounts.actAs` Together, the built-in roles `roles/editor`, `roles/compute.instanceAdmin` and `roles/resourcemanager.projectIamAdmin` form a superset of these permissions. Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + To set up a Constellation cluster, you need to perform two tasks that require permissions: create the infrastructure and create roles for cluster nodes. Both of these actions can be performed by different users, e.g., an administrator to create roles and a DevOps engineer to create the infrastructure. @@ -277,8 +282,8 @@ The built-in `PowerUserAccess` policy is a superset of these permissions. Follow Amazon's guide on [understanding](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [managing policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html). - - + + ### Authentication @@ -288,8 +293,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -305,8 +310,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -329,8 +334,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + **Testing** @@ -346,9 +351,9 @@ aws configure Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - + - + ## Next steps diff --git a/docs/versioned_docs/version-2.10/workflows/config.md b/docs/versioned_docs/version-2.10/workflows/config.md index e076e2e34..4dab6bd50 100644 --- a/docs/versioned_docs/version-2.10/workflows/config.md +++ b/docs/versioned_docs/version-2.10/workflows/config.md @@ -14,49 +14,49 @@ Before you can create your cluster, you need to configure the identity and acces You can generate a configuration file for your CSP by using the following CLI command: - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate aws ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. ## Choosing a VM type Constellation supports the following VM types: - - + + 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. You can also run `constellation config instance-types` to get the list of all supported options. - - + + 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 with a minimum of 4 vCPUs from the [C2D](https://cloud.google.com/compute/docs/compute-optimized-machines#c2d_machine_types) or [N2D](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) family. You can run `constellation config instance-types` to get the list of all supported options. - - + + By default, Constellation uses `m6a.xlarge` 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. @@ -75,8 +75,8 @@ AWS is currently investigating the issue. SNP-based attestation will be enabled as soon as a fix is verified. ::: - - + + Fill the desired VM type into the **instanceType** fields in the `constellation-conf.yml` file. @@ -133,8 +133,8 @@ See also Constellation's [Kubernetes support policy](../architecture/versions.md You can create an IAM configuration for your cluster automatically using the `constellation iam create` command. If you already have a Constellation configuration file, you can add the `--update-config` flag to the command. This writes the needed IAM fields into your configuration. Furthermore, the flag updates the zone/region of the configuration if it hasn't been set yet. - - + + You must be authenticated with the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -154,8 +154,8 @@ Note that CVMs are currently only supported in a few regions, check [Azure's pro Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [GCP CLI](https://cloud.google.com/sdk/gcloud) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -169,8 +169,8 @@ Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [AWS CLI](https://aws.amazon.com/en/cli/) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -194,16 +194,16 @@ You can find a list of all [regions in AWS's documentation](https://docs.aws.ama Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + +
Alternatively, you can manually create the IAM configuration on your CSP. The following describes the configuration fields and how you obtain the required information or create the required resources. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -232,9 +232,9 @@ The following describes the configuration fields and how you obtain the required The user-assigned identity is used by instances of the cluster to access other cloud resources. For more information about managed identities refer to [Azure's documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities). - + - + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -258,9 +258,9 @@ The following describes the configuration fields and how you obtain the required Afterward, create and download a new JSON key for this service account. Place the downloaded file in your Constellation workspace, and set the config parameter to the filename, e.g., `constellation-129857-15343dba46cb.json`. - + - + * **region**: The name of your chosen AWS data center region, e.g., `us-east-2`. @@ -291,9 +291,9 @@ The following describes the configuration fields and how you obtain the required Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.worker_node_policy`. - + - +
Now that you've configured your CSP, you can [create your cluster](./create.md). diff --git a/docs/versioned_docs/version-2.10/workflows/create.md b/docs/versioned_docs/version-2.10/workflows/create.md index 9ef9b4020..dd56bc8b7 100644 --- a/docs/versioned_docs/version-2.10/workflows/create.md +++ b/docs/versioned_docs/version-2.10/workflows/create.md @@ -26,8 +26,8 @@ Before you create the cluster, make sure to have a [valid configuration file](./ ### Create - - + + ```bash constellation create @@ -35,8 +35,8 @@ constellation create *create* stores your cluster's state in a [`constellation-terraform`](../architecture/orchestration.md#cluster-creation-process) directory in your workspace. - - + + Terraform allows for an easier GitOps integration as well as meeting regulatory requirements. Since the Constellation CLI also uses Terraform under the hood, you can reuse the same Terraform files. @@ -75,8 +75,8 @@ CONSTELL_CSP=$(cat constellation-conf.yaml | yq ".provider | keys | .[0]") jq --null-input --arg cloudprovider "$CONSTELL_CSP" --arg ip "$CONSTELL_IP" --arg initsecret "$CONSTELL_INIT_SECRET" '{"cloudprovider":$cloudprovider,"ip":$ip,"initsecret":$initsecret}' > constellation-id.json ``` - - + + ## The *init* step diff --git a/docs/versioned_docs/version-2.10/workflows/recovery.md b/docs/versioned_docs/version-2.10/workflows/recovery.md index c26fb32eb..35596b8c9 100644 --- a/docs/versioned_docs/version-2.10/workflows/recovery.md +++ b/docs/versioned_docs/version-2.10/workflows/recovery.md @@ -16,8 +16,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via [cloud logging](troubleshooting.md#cloud-logging). In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -51,8 +51,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -87,8 +87,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, open the AWS console to view all Auto Scaling Groups (ASGs) in the region of your cluster. Select the ASG of the control plane `--control-plane` and check that enough members are in a *Running* state. @@ -118,8 +118,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + ## Recover a cluster diff --git a/docs/versioned_docs/version-2.10/workflows/scale.md b/docs/versioned_docs/version-2.10/workflows/scale.md index 06898ad0c..63b727c7d 100644 --- a/docs/versioned_docs/version-2.10/workflows/scale.md +++ b/docs/versioned_docs/version-2.10/workflows/scale.md @@ -51,30 +51,30 @@ kubectl -n kube-system get nodes Alternatively, you can manually scale your cluster up or down: - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + 1. Go to Auto Scaling Groups and select the worker ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + ## Control-plane node scaling @@ -82,30 +82,30 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - + - + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + 1. Go to Auto Scaling Groups and select the control-plane ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/versioned_docs/version-2.10/workflows/storage.md b/docs/versioned_docs/version-2.10/workflows/storage.md index 9e3d96346..06fbc4de6 100644 --- a/docs/versioned_docs/version-2.10/workflows/storage.md +++ b/docs/versioned_docs/version-2.10/workflows/storage.md @@ -21,30 +21,30 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as `ReadWriteOnce`, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for more information. - - + + **Constellation CSI driver for AWS Elastic Block Store** Mount [Elastic Block Store](https://aws.amazon.com/ebs/) storage volumes into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-aws-ebs-csi-driver) for more information. - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [AWS EFS](https://docs.aws.amazon.com/en_en/eks/latest/userguide/efs-csi.html), [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction), or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -53,8 +53,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The Constellation CLI automatically installs Constellation's CSI driver for the selected CSP in your cluster. If you don't need a CSI driver or wish to deploy your own, you can disable the automatic installation by setting `deployCSIDriver` to `false` in your Constellation config file. - - + + Azure comes with two storage classes by default. @@ -82,8 +82,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + GCP comes with two storage classes by default. @@ -111,8 +111,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + AWS comes with two storage classes by default. @@ -140,8 +140,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + 1. Create a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) diff --git a/docs/versioned_docs/version-2.10/workflows/terminate.md b/docs/versioned_docs/version-2.10/workflows/terminate.md index 6c1eebb14..f33489ca5 100644 --- a/docs/versioned_docs/version-2.10/workflows/terminate.md +++ b/docs/versioned_docs/version-2.10/workflows/terminate.md @@ -16,8 +16,8 @@ All ephemeral storage and state of your cluster will be lost. Make sure any data ::: - - + + Terminate the cluster by running: ```bash @@ -40,8 +40,8 @@ resources manually. Just run the `terminate` command again afterward to continue ::: - - + + Terminate the cluster by running: ```bash @@ -56,5 +56,5 @@ rm constellation-id.json constellation-admin.conf Only the `constellation-mastersecret.json` and the configuration file remain. - - + + diff --git a/docs/versioned_docs/version-2.10/workflows/troubleshooting.md b/docs/versioned_docs/version-2.10/workflows/troubleshooting.md index 781cae8c5..38c0d87e9 100644 --- a/docs/versioned_docs/version-2.10/workflows/troubleshooting.md +++ b/docs/versioned_docs/version-2.10/workflows/troubleshooting.md @@ -55,14 +55,12 @@ When in doubt, check if the encountered [issue is known](https://github.com/edge ::: - :::tip During an upgrade with modified attestation config, a backup of the current configuration is stored in the `join-config-backup` config map in the `kube-system` namespace. To restore the old attestation config after a failed upgrade, you can copy the attestation config from this resource, put it in your configuration file and retry the upgrade. ::: - You can use the `upgrade apply` command to change measurements of a running cluster: 1. Modify the `measurements` key in your local `constellation-conf.yaml` to the expected values. @@ -84,8 +82,8 @@ To provide information during early stages of a node's boot process, Constellati You can view this information in the following places: - - + + 1. In your Azure subscription find the Constellation resource group. 2. Inside the resource group find the Application Insights resource called `constellation-insights-*`. @@ -95,8 +93,8 @@ You can view this information in the following places: To **find the disk UUIDs** use the following query: `traces | where message contains "Disk UUID"` - - + + 1. Select the project that hosts Constellation. 2. Go to the `Compute Engine` service. @@ -111,16 +109,16 @@ Constellation uses the default bucket to store logs. Its [default retention peri ::: - - + + 1. Open [AWS CloudWatch](https://console.aws.amazon.com/cloudwatch/home) 2. Select [Log Groups](https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups) 3. Select the log group that matches the name of your cluster. 4. Select the log stream for control or worker type nodes. - - + + ### Node shell access diff --git a/docs/versioned_docs/version-2.11/architecture/attestation.md b/docs/versioned_docs/version-2.11/architecture/attestation.md index 07ac3aa72..592063193 100644 --- a/docs/versioned_docs/version-2.11/architecture/attestation.md +++ b/docs/versioned_docs/version-2.11/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -152,8 +152,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -185,8 +185,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements. @@ -217,16 +217,16 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + ### CVM verification To verify the integrity of the received attestation statement, a chain of trust from the CVM technology to the interface providing the statement has to be established. For verification of the CVM technology, Constellation may expose additional options in its config file. - - + + On Azure, AMD SEV-SNP is used to provide runtime encryption to the VMs. An SEV-SNP attestation report is used to establish trust in the vTPM running inside the VM. @@ -248,18 +248,18 @@ You may customize certain parameters for verification of the attestation stateme More explicitly, it controls the verification of the `IDKeyDigest` value in the SEV-SNP attestation report. You can provide a list of accepted key digests and specify a policy on how this list is compared against the reported `IDKeyDigest`. - - + + There is no additional configuration available for GCP. - - + + There is no additional configuration available for AWS. - - + + ## Cluster attestation diff --git a/docs/versioned_docs/version-2.11/getting-started/first-steps-local.md b/docs/versioned_docs/version-2.11/getting-started/first-steps-local.md index de9c66e9b..a6e825906 100644 --- a/docs/versioned_docs/version-2.11/getting-started/first-steps-local.md +++ b/docs/versioned_docs/version-2.11/getting-started/first-steps-local.md @@ -45,8 +45,8 @@ sudo iptables -P FORWARD ACCEPT ## Create a cluster - - + + 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/). @@ -74,8 +74,8 @@ 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. - - + + 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. @@ -151,8 +151,8 @@ attaching persistent storage, or autoscaling aren't available. export KUBECONFIG="$PWD/constellation-admin.conf" ``` - - + + ## Connect to the cluster @@ -205,8 +205,8 @@ worker-0 Ready 32s v1.24.6 ## Terminate your cluster - - + + Once you are done, you can clean up the created resources using the following command: @@ -217,8 +217,8 @@ 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. - - + + Once you are done, you can clean up the created resources using the following command: @@ -246,8 +246,8 @@ 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. - - + + ## Troubleshooting diff --git a/docs/versioned_docs/version-2.11/getting-started/first-steps.md b/docs/versioned_docs/version-2.11/getting-started/first-steps.md index 07b7f8410..9811597e6 100644 --- a/docs/versioned_docs/version-2.11/getting-started/first-steps.md +++ b/docs/versioned_docs/version-2.11/getting-started/first-steps.md @@ -15,39 +15,39 @@ If you encounter any problem with the following steps, make sure to use the [lat 1. Create the [configuration file](../workflows/config.md) for your cloud provider. - + - + ```bash constellation config generate azure ``` - + - + ```bash constellation config generate gcp ``` - + - + ```bash constellation config generate aws ``` - + - + 2. Create your [IAM configuration](../workflows/config.md#creating-an-iam-configuration). - + - + ```bash constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest --update-config @@ -62,9 +62,9 @@ If you encounter any problem with the following steps, make sure to use the [lat * `westeurope` * `southeastasia` - + - + ```bash constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west2-a --serviceAccountID=constell-test --update-config @@ -74,9 +74,9 @@ If you encounter any problem with the following steps, make sure to use the [lat Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available), which you can filter by machine type `C2D` or `N2D`. - + - + ```bash constellation iam create aws --zone=us-east-2a --prefix=constellTest --update-config @@ -103,8 +103,8 @@ If you encounter any problem with the following steps, make sure to use the [lat You can find a list of all [regions in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). - - + + :::tip To learn about all options you have for managing IAM resources and Constellation configuration, see the [Configuration workflow](../workflows/config.md). diff --git a/docs/versioned_docs/version-2.11/getting-started/install.md b/docs/versioned_docs/version-2.11/getting-started/install.md index 6a3acaea9..f134ca3c2 100644 --- a/docs/versioned_docs/version-2.11/getting-started/install.md +++ b/docs/versioned_docs/version-2.11/getting-started/install.md @@ -18,8 +18,8 @@ Make sure the following requirements are met: The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -35,8 +35,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -52,9 +52,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -70,9 +70,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -88,8 +88,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -105,39 +105,42 @@ If you don't have a cloud subscription, you can also set up a [local Constellati ### Required permissions - - + + The following [resource providers need to be registered](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) in your subscription: -* `Microsoft.Attestation` \[2] -* `Microsoft.Compute` -* `Microsoft.Insights` -* `Microsoft.ManagedIdentity` -* `Microsoft.Network` + +- `Microsoft.Attestation` \[2] +- `Microsoft.Compute` +- `Microsoft.Insights` +- `Microsoft.ManagedIdentity` +- `Microsoft.Network` By default, Constellation tries to register these automatically if they haven't been registered before. To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: -* `*/register/action` \[1] -* `Microsoft.Authorization/roleAssignments/*` -* `Microsoft.Authorization/roleDefinitions/*` -* `Microsoft.ManagedIdentity/userAssignedIdentities/*` -* `Microsoft.Resources/subscriptions/resourcegroups/*` + +- `*/register/action` \[1] +- `Microsoft.Authorization/roleAssignments/*` +- `Microsoft.Authorization/roleDefinitions/*` +- `Microsoft.ManagedIdentity/userAssignedIdentities/*` +- `Microsoft.Resources/subscriptions/resourcegroups/*` The built-in `Owner` role is a superset of these permissions. To [create a Constellation cluster](../workflows/create.md#the-create-step), you need the following permissions: -* `Microsoft.Attestation/attestationProviders/*` -* `Microsoft.Compute/virtualMachineScaleSets/*` -* `Microsoft.Insights/components/*` -* `Microsoft.ManagedIdentity/userAssignedIdentities/*` -* `Microsoft.Network/loadBalancers/*` -* `Microsoft.Network/loadBalancers/backendAddressPools/*` -* `Microsoft.Network/networkSecurityGroups/*` -* `Microsoft.Network/publicIPAddresses/*` -* `Microsoft.Network/virtualNetworks/*` -* `Microsoft.Network/virtualNetworks/subnets/*` -* `Microsoft.Network/natGateways/*` + +- `Microsoft.Attestation/attestationProviders/*` +- `Microsoft.Compute/virtualMachineScaleSets/*` +- `Microsoft.Insights/components/*` +- `Microsoft.ManagedIdentity/userAssignedIdentities/*` +- `Microsoft.Network/loadBalancers/*` +- `Microsoft.Network/loadBalancers/backendAddressPools/*` +- `Microsoft.Network/networkSecurityGroups/*` +- `Microsoft.Network/publicIPAddresses/*` +- `Microsoft.Network/virtualNetworks/*` +- `Microsoft.Network/virtualNetworks/subnets/*` +- `Microsoft.Network/natGateways/*` The built-in `Contributor` role is a superset of these permissions. @@ -145,89 +148,91 @@ Follow Microsoft's guide on [understanding](https://learn.microsoft.com/en-us/az 1: You can omit `*/register/Action` if the resource providers mentioned above are already registered and the `ARM_SKIP_PROVIDER_REGISTRATION` environment variable is set to `true` when creating the IAM configuration. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: -* `iam.serviceAccountKeys.create` -* `iam.serviceAccountKeys.delete` -* `iam.serviceAccountKeys.get` -* `iam.serviceAccounts.create` -* `iam.serviceAccounts.delete` -* `iam.serviceAccounts.get` -* `resourcemanager.projects.getIamPolicy` -* `resourcemanager.projects.setIamPolicy` + +- `iam.serviceAccountKeys.create` +- `iam.serviceAccountKeys.delete` +- `iam.serviceAccountKeys.get` +- `iam.serviceAccounts.create` +- `iam.serviceAccounts.delete` +- `iam.serviceAccounts.get` +- `resourcemanager.projects.getIamPolicy` +- `resourcemanager.projects.setIamPolicy` Together, the built-in roles `roles/editor` and `roles/resourcemanager.projectIamAdmin` form a superset of these permissions. To [create a Constellation cluster](../workflows/create.md#the-create-step), you need the following permissions: -* `compute.addresses.createInternal` -* `compute.addresses.deleteInternal` -* `compute.addresses.get` -* `compute.addresses.useInternal` -* `compute.backendServices.create` -* `compute.backendServices.delete` -* `compute.backendServices.get` -* `compute.backendServices.use` -* `compute.disks.create` -* `compute.firewalls.create` -* `compute.firewalls.delete` -* `compute.firewalls.get` -* `compute.globalAddresses.create` -* `compute.globalAddresses.delete` -* `compute.globalAddresses.get` -* `compute.globalAddresses.use` -* `compute.globalForwardingRules.create` -* `compute.globalForwardingRules.delete` -* `compute.globalForwardingRules.get` -* `compute.globalForwardingRules.setLabels` -* `compute.globalOperations.get` -* `compute.healthChecks.create` -* `compute.healthChecks.delete` -* `compute.healthChecks.get` -* `compute.healthChecks.useReadOnly` -* `compute.instanceGroupManagers.create` -* `compute.instanceGroupManagers.delete` -* `compute.instanceGroupManagers.get` -* `compute.instanceGroups.create` -* `compute.instanceGroups.delete` -* `compute.instanceGroups.get` -* `compute.instanceGroups.use` -* `compute.instances.create` -* `compute.instances.setLabels` -* `compute.instances.setMetadata` -* `compute.instances.setTags` -* `compute.instanceTemplates.create` -* `compute.instanceTemplates.delete` -* `compute.instanceTemplates.get` -* `compute.instanceTemplates.useReadOnly` -* `compute.networks.create` -* `compute.networks.delete` -* `compute.networks.get` -* `compute.networks.updatePolicy` -* `compute.routers.create` -* `compute.routers.delete` -* `compute.routers.get` -* `compute.routers.update` -* `compute.subnetworks.create` -* `compute.subnetworks.delete` -* `compute.subnetworks.get` -* `compute.subnetworks.use` -* `compute.targetTcpProxies.create` -* `compute.targetTcpProxies.delete` -* `compute.targetTcpProxies.get` -* `compute.targetTcpProxies.use` -* `iam.serviceAccounts.actAs` + +- `compute.addresses.createInternal` +- `compute.addresses.deleteInternal` +- `compute.addresses.get` +- `compute.addresses.useInternal` +- `compute.backendServices.create` +- `compute.backendServices.delete` +- `compute.backendServices.get` +- `compute.backendServices.use` +- `compute.disks.create` +- `compute.firewalls.create` +- `compute.firewalls.delete` +- `compute.firewalls.get` +- `compute.globalAddresses.create` +- `compute.globalAddresses.delete` +- `compute.globalAddresses.get` +- `compute.globalAddresses.use` +- `compute.globalForwardingRules.create` +- `compute.globalForwardingRules.delete` +- `compute.globalForwardingRules.get` +- `compute.globalForwardingRules.setLabels` +- `compute.globalOperations.get` +- `compute.healthChecks.create` +- `compute.healthChecks.delete` +- `compute.healthChecks.get` +- `compute.healthChecks.useReadOnly` +- `compute.instanceGroupManagers.create` +- `compute.instanceGroupManagers.delete` +- `compute.instanceGroupManagers.get` +- `compute.instanceGroups.create` +- `compute.instanceGroups.delete` +- `compute.instanceGroups.get` +- `compute.instanceGroups.use` +- `compute.instances.create` +- `compute.instances.setLabels` +- `compute.instances.setMetadata` +- `compute.instances.setTags` +- `compute.instanceTemplates.create` +- `compute.instanceTemplates.delete` +- `compute.instanceTemplates.get` +- `compute.instanceTemplates.useReadOnly` +- `compute.networks.create` +- `compute.networks.delete` +- `compute.networks.get` +- `compute.networks.updatePolicy` +- `compute.routers.create` +- `compute.routers.delete` +- `compute.routers.get` +- `compute.routers.update` +- `compute.subnetworks.create` +- `compute.subnetworks.delete` +- `compute.subnetworks.get` +- `compute.subnetworks.use` +- `compute.targetTcpProxies.create` +- `compute.targetTcpProxies.delete` +- `compute.targetTcpProxies.get` +- `compute.targetTcpProxies.use` +- `iam.serviceAccounts.actAs` Together, the built-in roles `roles/editor`, `roles/compute.instanceAdmin` and `roles/resourcemanager.projectIamAdmin` form a superset of these permissions. Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + To set up a Constellation cluster, you need to perform two tasks that require permissions: create the infrastructure and create roles for cluster nodes. Both of these actions can be performed by different users, e.g., an administrator to create roles and a DevOps engineer to create the infrastructure. @@ -277,8 +282,8 @@ The built-in `PowerUserAccess` policy is a superset of these permissions. Follow Amazon's guide on [understanding](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [managing policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html). - - + + ### Authentication @@ -288,8 +293,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -305,8 +310,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -329,8 +334,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + **Testing** @@ -346,9 +351,9 @@ aws configure Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - + - + ## Next steps diff --git a/docs/versioned_docs/version-2.11/workflows/config.md b/docs/versioned_docs/version-2.11/workflows/config.md index e076e2e34..4dab6bd50 100644 --- a/docs/versioned_docs/version-2.11/workflows/config.md +++ b/docs/versioned_docs/version-2.11/workflows/config.md @@ -14,49 +14,49 @@ Before you can create your cluster, you need to configure the identity and acces You can generate a configuration file for your CSP by using the following CLI command: - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate aws ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. ## Choosing a VM type Constellation supports the following VM types: - - + + 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. You can also run `constellation config instance-types` to get the list of all supported options. - - + + 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 with a minimum of 4 vCPUs from the [C2D](https://cloud.google.com/compute/docs/compute-optimized-machines#c2d_machine_types) or [N2D](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) family. You can run `constellation config instance-types` to get the list of all supported options. - - + + By default, Constellation uses `m6a.xlarge` 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. @@ -75,8 +75,8 @@ AWS is currently investigating the issue. SNP-based attestation will be enabled as soon as a fix is verified. ::: - - + + Fill the desired VM type into the **instanceType** fields in the `constellation-conf.yml` file. @@ -133,8 +133,8 @@ See also Constellation's [Kubernetes support policy](../architecture/versions.md You can create an IAM configuration for your cluster automatically using the `constellation iam create` command. If you already have a Constellation configuration file, you can add the `--update-config` flag to the command. This writes the needed IAM fields into your configuration. Furthermore, the flag updates the zone/region of the configuration if it hasn't been set yet. - - + + You must be authenticated with the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -154,8 +154,8 @@ Note that CVMs are currently only supported in a few regions, check [Azure's pro Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [GCP CLI](https://cloud.google.com/sdk/gcloud) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -169,8 +169,8 @@ Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [AWS CLI](https://aws.amazon.com/en/cli/) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -194,16 +194,16 @@ You can find a list of all [regions in AWS's documentation](https://docs.aws.ama Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + +
Alternatively, you can manually create the IAM configuration on your CSP. The following describes the configuration fields and how you obtain the required information or create the required resources. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -232,9 +232,9 @@ The following describes the configuration fields and how you obtain the required The user-assigned identity is used by instances of the cluster to access other cloud resources. For more information about managed identities refer to [Azure's documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities). - + - + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -258,9 +258,9 @@ The following describes the configuration fields and how you obtain the required Afterward, create and download a new JSON key for this service account. Place the downloaded file in your Constellation workspace, and set the config parameter to the filename, e.g., `constellation-129857-15343dba46cb.json`. - + - + * **region**: The name of your chosen AWS data center region, e.g., `us-east-2`. @@ -291,9 +291,9 @@ The following describes the configuration fields and how you obtain the required Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.worker_node_policy`. - + - +
Now that you've configured your CSP, you can [create your cluster](./create.md). diff --git a/docs/versioned_docs/version-2.11/workflows/create.md b/docs/versioned_docs/version-2.11/workflows/create.md index aa421d88a..8dd4946de 100644 --- a/docs/versioned_docs/version-2.11/workflows/create.md +++ b/docs/versioned_docs/version-2.11/workflows/create.md @@ -26,8 +26,8 @@ Before you create the cluster, make sure to have a [valid configuration file](./ ### Create - - + + ```bash constellation create @@ -35,8 +35,8 @@ constellation create *create* stores your cluster's state in a [`constellation-terraform`](../architecture/orchestration.md#cluster-creation-process) directory in your workspace. - - + + Terraform allows for an easier GitOps integration as well as meeting regulatory requirements. Since the Constellation CLI also uses Terraform under the hood, you can reuse the same Terraform files. @@ -75,8 +75,8 @@ CONSTELL_CSP=$(cat constellation-conf.yaml | yq ".provider | keys | .[0]") jq --null-input --arg cloudprovider "$CONSTELL_CSP" --arg ip "$CONSTELL_IP" --arg initsecret "$CONSTELL_INIT_SECRET" '{"cloudprovider":$cloudprovider,"ip":$ip,"initsecret":$initsecret}' > constellation-id.json ``` - - + + ## The *init* step diff --git a/docs/versioned_docs/version-2.11/workflows/recovery.md b/docs/versioned_docs/version-2.11/workflows/recovery.md index c26fb32eb..35596b8c9 100644 --- a/docs/versioned_docs/version-2.11/workflows/recovery.md +++ b/docs/versioned_docs/version-2.11/workflows/recovery.md @@ -16,8 +16,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via [cloud logging](troubleshooting.md#cloud-logging). In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -51,8 +51,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -87,8 +87,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, open the AWS console to view all Auto Scaling Groups (ASGs) in the region of your cluster. Select the ASG of the control plane `--control-plane` and check that enough members are in a *Running* state. @@ -118,8 +118,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + ## Recover a cluster diff --git a/docs/versioned_docs/version-2.11/workflows/scale.md b/docs/versioned_docs/version-2.11/workflows/scale.md index 06898ad0c..63b727c7d 100644 --- a/docs/versioned_docs/version-2.11/workflows/scale.md +++ b/docs/versioned_docs/version-2.11/workflows/scale.md @@ -51,30 +51,30 @@ kubectl -n kube-system get nodes Alternatively, you can manually scale your cluster up or down: - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + 1. Go to Auto Scaling Groups and select the worker ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + ## Control-plane node scaling @@ -82,30 +82,30 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - + - + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + 1. Go to Auto Scaling Groups and select the control-plane ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/versioned_docs/version-2.11/workflows/storage.md b/docs/versioned_docs/version-2.11/workflows/storage.md index 9e3d96346..06fbc4de6 100644 --- a/docs/versioned_docs/version-2.11/workflows/storage.md +++ b/docs/versioned_docs/version-2.11/workflows/storage.md @@ -21,30 +21,30 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as `ReadWriteOnce`, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for more information. - - + + **Constellation CSI driver for AWS Elastic Block Store** Mount [Elastic Block Store](https://aws.amazon.com/ebs/) storage volumes into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-aws-ebs-csi-driver) for more information. - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [AWS EFS](https://docs.aws.amazon.com/en_en/eks/latest/userguide/efs-csi.html), [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction), or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -53,8 +53,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The Constellation CLI automatically installs Constellation's CSI driver for the selected CSP in your cluster. If you don't need a CSI driver or wish to deploy your own, you can disable the automatic installation by setting `deployCSIDriver` to `false` in your Constellation config file. - - + + Azure comes with two storage classes by default. @@ -82,8 +82,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + GCP comes with two storage classes by default. @@ -111,8 +111,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + AWS comes with two storage classes by default. @@ -140,8 +140,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + 1. Create a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) diff --git a/docs/versioned_docs/version-2.11/workflows/terminate.md b/docs/versioned_docs/version-2.11/workflows/terminate.md index 6c1eebb14..f33489ca5 100644 --- a/docs/versioned_docs/version-2.11/workflows/terminate.md +++ b/docs/versioned_docs/version-2.11/workflows/terminate.md @@ -16,8 +16,8 @@ All ephemeral storage and state of your cluster will be lost. Make sure any data ::: - - + + Terminate the cluster by running: ```bash @@ -40,8 +40,8 @@ resources manually. Just run the `terminate` command again afterward to continue ::: - - + + Terminate the cluster by running: ```bash @@ -56,5 +56,5 @@ rm constellation-id.json constellation-admin.conf Only the `constellation-mastersecret.json` and the configuration file remain. - - + + diff --git a/docs/versioned_docs/version-2.11/workflows/troubleshooting.md b/docs/versioned_docs/version-2.11/workflows/troubleshooting.md index a3e25a0fe..c40e6496e 100644 --- a/docs/versioned_docs/version-2.11/workflows/troubleshooting.md +++ b/docs/versioned_docs/version-2.11/workflows/troubleshooting.md @@ -101,8 +101,8 @@ To provide information during early stages of a node's boot process, Constellati You can view this information in the following places: - - + + 1. In your Azure subscription find the Constellation resource group. 2. Inside the resource group find the Application Insights resource called `constellation-insights-*`. @@ -112,8 +112,8 @@ You can view this information in the following places: To **find the disk UUIDs** use the following query: `traces | where message contains "Disk UUID"` - - + + 1. Select the project that hosts Constellation. 2. Go to the `Compute Engine` service. @@ -128,16 +128,16 @@ Constellation uses the default bucket to store logs. Its [default retention peri ::: - - + + 1. Open [AWS CloudWatch](https://console.aws.amazon.com/cloudwatch/home) 2. Select [Log Groups](https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups) 3. Select the log group that matches the name of your cluster. 4. Select the log stream for control or worker type nodes. - - + + ### Node shell access diff --git a/docs/versioned_docs/version-2.12/architecture/attestation.md b/docs/versioned_docs/version-2.12/architecture/attestation.md index e37533995..f9c9ac38e 100644 --- a/docs/versioned_docs/version-2.12/architecture/attestation.md +++ b/docs/versioned_docs/version-2.12/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -152,8 +152,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -185,8 +185,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements. @@ -217,16 +217,16 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + ### CVM verification To verify the integrity of the received attestation statement, a chain of trust from the CVM technology to the interface providing the statement has to be established. For verification of the CVM technology, Constellation may expose additional options in its config file. - - + + On Azure, AMD SEV-SNP is used to provide runtime encryption to the VMs. An SEV-SNP attestation report is used to establish trust in the vTPM running inside the VM. @@ -248,18 +248,18 @@ You may customize certain parameters for verification of the attestation stateme More explicitly, it controls the verification of the `IDKeyDigest` value in the SEV-SNP attestation report. You can provide a list of accepted key digests and specify a policy on how this list is compared against the reported `IDKeyDigest`. - - + + There is no additional configuration available for GCP. - - + + There is no additional configuration available for AWS. - - + + ## Cluster attestation diff --git a/docs/versioned_docs/version-2.12/getting-started/first-steps-local.md b/docs/versioned_docs/version-2.12/getting-started/first-steps-local.md index de9c66e9b..a6e825906 100644 --- a/docs/versioned_docs/version-2.12/getting-started/first-steps-local.md +++ b/docs/versioned_docs/version-2.12/getting-started/first-steps-local.md @@ -45,8 +45,8 @@ sudo iptables -P FORWARD ACCEPT ## Create a cluster - - + + 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/). @@ -74,8 +74,8 @@ 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. - - + + 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. @@ -151,8 +151,8 @@ attaching persistent storage, or autoscaling aren't available. export KUBECONFIG="$PWD/constellation-admin.conf" ``` - - + + ## Connect to the cluster @@ -205,8 +205,8 @@ worker-0 Ready 32s v1.24.6 ## Terminate your cluster - - + + Once you are done, you can clean up the created resources using the following command: @@ -217,8 +217,8 @@ 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. - - + + Once you are done, you can clean up the created resources using the following command: @@ -246,8 +246,8 @@ 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. - - + + ## Troubleshooting diff --git a/docs/versioned_docs/version-2.12/getting-started/first-steps.md b/docs/versioned_docs/version-2.12/getting-started/first-steps.md index 07b7f8410..9811597e6 100644 --- a/docs/versioned_docs/version-2.12/getting-started/first-steps.md +++ b/docs/versioned_docs/version-2.12/getting-started/first-steps.md @@ -15,39 +15,39 @@ If you encounter any problem with the following steps, make sure to use the [lat 1. Create the [configuration file](../workflows/config.md) for your cloud provider. - + - + ```bash constellation config generate azure ``` - + - + ```bash constellation config generate gcp ``` - + - + ```bash constellation config generate aws ``` - + - + 2. Create your [IAM configuration](../workflows/config.md#creating-an-iam-configuration). - + - + ```bash constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest --update-config @@ -62,9 +62,9 @@ If you encounter any problem with the following steps, make sure to use the [lat * `westeurope` * `southeastasia` - + - + ```bash constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west2-a --serviceAccountID=constell-test --update-config @@ -74,9 +74,9 @@ If you encounter any problem with the following steps, make sure to use the [lat Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available), which you can filter by machine type `C2D` or `N2D`. - + - + ```bash constellation iam create aws --zone=us-east-2a --prefix=constellTest --update-config @@ -103,8 +103,8 @@ If you encounter any problem with the following steps, make sure to use the [lat You can find a list of all [regions in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). - - + + :::tip To learn about all options you have for managing IAM resources and Constellation configuration, see the [Configuration workflow](../workflows/config.md). diff --git a/docs/versioned_docs/version-2.12/getting-started/install.md b/docs/versioned_docs/version-2.12/getting-started/install.md index 035f679b2..2fabcf0b1 100644 --- a/docs/versioned_docs/version-2.12/getting-started/install.md +++ b/docs/versioned_docs/version-2.12/getting-started/install.md @@ -18,8 +18,8 @@ Make sure the following requirements are met: The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -35,8 +35,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -52,9 +52,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -70,9 +70,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -88,8 +88,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -105,39 +105,42 @@ If you don't have a cloud subscription, you can also set up a [local Constellati ### Required permissions - - + + The following [resource providers need to be registered](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) in your subscription: -* `Microsoft.Attestation` -* `Microsoft.Compute` -* `Microsoft.Insights` -* `Microsoft.ManagedIdentity` -* `Microsoft.Network` + +- `Microsoft.Attestation` +- `Microsoft.Compute` +- `Microsoft.Insights` +- `Microsoft.ManagedIdentity` +- `Microsoft.Network` By default, Constellation tries to register these automatically if they haven't been registered before. To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: -* `*/register/action` \[1] -* `Microsoft.Authorization/roleAssignments/*` -* `Microsoft.Authorization/roleDefinitions/*` -* `Microsoft.ManagedIdentity/userAssignedIdentities/*` -* `Microsoft.Resources/subscriptions/resourcegroups/*` + +- `*/register/action` \[1] +- `Microsoft.Authorization/roleAssignments/*` +- `Microsoft.Authorization/roleDefinitions/*` +- `Microsoft.ManagedIdentity/userAssignedIdentities/*` +- `Microsoft.Resources/subscriptions/resourcegroups/*` The built-in `Owner` role is a superset of these permissions. To [create a Constellation cluster](../workflows/create.md#the-create-step), you need the following permissions: -* `Microsoft.Attestation/attestationProviders/*` -* `Microsoft.Compute/virtualMachineScaleSets/*` -* `Microsoft.Insights/components/*` -* `Microsoft.ManagedIdentity/userAssignedIdentities/*` -* `Microsoft.Network/loadBalancers/*` -* `Microsoft.Network/loadBalancers/backendAddressPools/*` -* `Microsoft.Network/networkSecurityGroups/*` -* `Microsoft.Network/publicIPAddresses/*` -* `Microsoft.Network/virtualNetworks/*` -* `Microsoft.Network/virtualNetworks/subnets/*` -* `Microsoft.Network/natGateways/*` + +- `Microsoft.Attestation/attestationProviders/*` +- `Microsoft.Compute/virtualMachineScaleSets/*` +- `Microsoft.Insights/components/*` +- `Microsoft.ManagedIdentity/userAssignedIdentities/*` +- `Microsoft.Network/loadBalancers/*` +- `Microsoft.Network/loadBalancers/backendAddressPools/*` +- `Microsoft.Network/networkSecurityGroups/*` +- `Microsoft.Network/publicIPAddresses/*` +- `Microsoft.Network/virtualNetworks/*` +- `Microsoft.Network/virtualNetworks/subnets/*` +- `Microsoft.Network/natGateways/*` The built-in `Contributor` role is a superset of these permissions. @@ -145,92 +148,94 @@ Follow Microsoft's guide on [understanding](https://learn.microsoft.com/en-us/az 1: You can omit `*/register/Action` if the resource providers mentioned above are already registered and the `ARM_SKIP_PROVIDER_REGISTRATION` environment variable is set to `true` when creating the IAM configuration. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: -* `iam.serviceAccountKeys.create` -* `iam.serviceAccountKeys.delete` -* `iam.serviceAccountKeys.get` -* `iam.serviceAccounts.create` -* `iam.serviceAccounts.delete` -* `iam.serviceAccounts.get` -* `resourcemanager.projects.getIamPolicy` -* `resourcemanager.projects.setIamPolicy` + +- `iam.serviceAccountKeys.create` +- `iam.serviceAccountKeys.delete` +- `iam.serviceAccountKeys.get` +- `iam.serviceAccounts.create` +- `iam.serviceAccounts.delete` +- `iam.serviceAccounts.get` +- `resourcemanager.projects.getIamPolicy` +- `resourcemanager.projects.setIamPolicy` Together, the built-in roles `roles/editor` and `roles/resourcemanager.projectIamAdmin` form a superset of these permissions. To [create a Constellation cluster](../workflows/create.md#the-create-step), you need the following permissions: -* `compute.addresses.createInternal` -* `compute.addresses.deleteInternal` -* `compute.addresses.get` -* `compute.addresses.useInternal` -* `compute.backendServices.create` -* `compute.backendServices.delete` -* `compute.backendServices.get` -* `compute.backendServices.use` -* `compute.disks.create` -* `compute.firewalls.create` -* `compute.firewalls.delete` -* `compute.firewalls.get` -* `compute.firewalls.update` -* `compute.globalAddresses.create` -* `compute.globalAddresses.delete` -* `compute.globalAddresses.get` -* `compute.globalAddresses.use` -* `compute.globalForwardingRules.create` -* `compute.globalForwardingRules.delete` -* `compute.globalForwardingRules.get` -* `compute.globalForwardingRules.setLabels` -* `compute.globalOperations.get` -* `compute.healthChecks.create` -* `compute.healthChecks.delete` -* `compute.healthChecks.get` -* `compute.healthChecks.useReadOnly` -* `compute.instanceGroupManagers.create` -* `compute.instanceGroupManagers.delete` -* `compute.instanceGroupManagers.get` -* `compute.instanceGroupManagers.update` -* `compute.instanceGroups.create` -* `compute.instanceGroups.delete` -* `compute.instanceGroups.get` -* `compute.instanceGroups.update` -* `compute.instanceGroups.use` -* `compute.instances.create` -* `compute.instances.setLabels` -* `compute.instances.setMetadata` -* `compute.instances.setTags` -* `compute.instanceTemplates.create` -* `compute.instanceTemplates.delete` -* `compute.instanceTemplates.get` -* `compute.instanceTemplates.useReadOnly` -* `compute.networks.create` -* `compute.networks.delete` -* `compute.networks.get` -* `compute.networks.updatePolicy` -* `compute.routers.create` -* `compute.routers.delete` -* `compute.routers.get` -* `compute.routers.update` -* `compute.subnetworks.create` -* `compute.subnetworks.delete` -* `compute.subnetworks.get` -* `compute.subnetworks.use` -* `compute.targetTcpProxies.create` -* `compute.targetTcpProxies.delete` -* `compute.targetTcpProxies.get` -* `compute.targetTcpProxies.use` -* `iam.serviceAccounts.actAs` + +- `compute.addresses.createInternal` +- `compute.addresses.deleteInternal` +- `compute.addresses.get` +- `compute.addresses.useInternal` +- `compute.backendServices.create` +- `compute.backendServices.delete` +- `compute.backendServices.get` +- `compute.backendServices.use` +- `compute.disks.create` +- `compute.firewalls.create` +- `compute.firewalls.delete` +- `compute.firewalls.get` +- `compute.firewalls.update` +- `compute.globalAddresses.create` +- `compute.globalAddresses.delete` +- `compute.globalAddresses.get` +- `compute.globalAddresses.use` +- `compute.globalForwardingRules.create` +- `compute.globalForwardingRules.delete` +- `compute.globalForwardingRules.get` +- `compute.globalForwardingRules.setLabels` +- `compute.globalOperations.get` +- `compute.healthChecks.create` +- `compute.healthChecks.delete` +- `compute.healthChecks.get` +- `compute.healthChecks.useReadOnly` +- `compute.instanceGroupManagers.create` +- `compute.instanceGroupManagers.delete` +- `compute.instanceGroupManagers.get` +- `compute.instanceGroupManagers.update` +- `compute.instanceGroups.create` +- `compute.instanceGroups.delete` +- `compute.instanceGroups.get` +- `compute.instanceGroups.update` +- `compute.instanceGroups.use` +- `compute.instances.create` +- `compute.instances.setLabels` +- `compute.instances.setMetadata` +- `compute.instances.setTags` +- `compute.instanceTemplates.create` +- `compute.instanceTemplates.delete` +- `compute.instanceTemplates.get` +- `compute.instanceTemplates.useReadOnly` +- `compute.networks.create` +- `compute.networks.delete` +- `compute.networks.get` +- `compute.networks.updatePolicy` +- `compute.routers.create` +- `compute.routers.delete` +- `compute.routers.get` +- `compute.routers.update` +- `compute.subnetworks.create` +- `compute.subnetworks.delete` +- `compute.subnetworks.get` +- `compute.subnetworks.use` +- `compute.targetTcpProxies.create` +- `compute.targetTcpProxies.delete` +- `compute.targetTcpProxies.get` +- `compute.targetTcpProxies.use` +- `iam.serviceAccounts.actAs` Together, the built-in roles `roles/editor`, `roles/compute.instanceAdmin` and `roles/resourcemanager.projectIamAdmin` form a superset of these permissions. Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + To set up a Constellation cluster, you need to perform two tasks that require permissions: create the infrastructure and create roles for cluster nodes. Both of these actions can be performed by different users, e.g., an administrator to create roles and a DevOps engineer to create the infrastructure. @@ -280,8 +285,8 @@ The built-in `PowerUserAccess` policy is a superset of these permissions. Follow Amazon's guide on [understanding](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [managing policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html). - - + + ### Authentication @@ -291,8 +296,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -308,8 +313,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -332,8 +337,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + **Testing** @@ -349,9 +354,9 @@ aws configure Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - + - + ## Next steps diff --git a/docs/versioned_docs/version-2.12/workflows/config.md b/docs/versioned_docs/version-2.12/workflows/config.md index e076e2e34..4dab6bd50 100644 --- a/docs/versioned_docs/version-2.12/workflows/config.md +++ b/docs/versioned_docs/version-2.12/workflows/config.md @@ -14,49 +14,49 @@ Before you can create your cluster, you need to configure the identity and acces You can generate a configuration file for your CSP by using the following CLI command: - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate aws ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. ## Choosing a VM type Constellation supports the following VM types: - - + + 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. You can also run `constellation config instance-types` to get the list of all supported options. - - + + 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 with a minimum of 4 vCPUs from the [C2D](https://cloud.google.com/compute/docs/compute-optimized-machines#c2d_machine_types) or [N2D](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) family. You can run `constellation config instance-types` to get the list of all supported options. - - + + By default, Constellation uses `m6a.xlarge` 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. @@ -75,8 +75,8 @@ AWS is currently investigating the issue. SNP-based attestation will be enabled as soon as a fix is verified. ::: - - + + Fill the desired VM type into the **instanceType** fields in the `constellation-conf.yml` file. @@ -133,8 +133,8 @@ See also Constellation's [Kubernetes support policy](../architecture/versions.md You can create an IAM configuration for your cluster automatically using the `constellation iam create` command. If you already have a Constellation configuration file, you can add the `--update-config` flag to the command. This writes the needed IAM fields into your configuration. Furthermore, the flag updates the zone/region of the configuration if it hasn't been set yet. - - + + You must be authenticated with the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -154,8 +154,8 @@ Note that CVMs are currently only supported in a few regions, check [Azure's pro Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [GCP CLI](https://cloud.google.com/sdk/gcloud) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -169,8 +169,8 @@ Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [AWS CLI](https://aws.amazon.com/en/cli/) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -194,16 +194,16 @@ You can find a list of all [regions in AWS's documentation](https://docs.aws.ama Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + +
Alternatively, you can manually create the IAM configuration on your CSP. The following describes the configuration fields and how you obtain the required information or create the required resources. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -232,9 +232,9 @@ The following describes the configuration fields and how you obtain the required The user-assigned identity is used by instances of the cluster to access other cloud resources. For more information about managed identities refer to [Azure's documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities). - + - + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -258,9 +258,9 @@ The following describes the configuration fields and how you obtain the required Afterward, create and download a new JSON key for this service account. Place the downloaded file in your Constellation workspace, and set the config parameter to the filename, e.g., `constellation-129857-15343dba46cb.json`. - + - + * **region**: The name of your chosen AWS data center region, e.g., `us-east-2`. @@ -291,9 +291,9 @@ The following describes the configuration fields and how you obtain the required Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.worker_node_policy`. - + - +
Now that you've configured your CSP, you can [create your cluster](./create.md). diff --git a/docs/versioned_docs/version-2.12/workflows/create.md b/docs/versioned_docs/version-2.12/workflows/create.md index 58c0efe39..eccb2699a 100644 --- a/docs/versioned_docs/version-2.12/workflows/create.md +++ b/docs/versioned_docs/version-2.12/workflows/create.md @@ -26,8 +26,8 @@ Before you create the cluster, make sure to have a [valid configuration file](./ ### Create - - + + ```bash constellation create @@ -35,8 +35,8 @@ constellation create *create* stores your cluster's state in a [`constellation-terraform`](../architecture/orchestration.md#cluster-creation-process) directory in your workspace. - - + + Terraform allows for an easier GitOps integration as well as meeting regulatory requirements. Since the Constellation CLI also uses Terraform under the hood, you can reuse the same Terraform files. @@ -77,8 +77,8 @@ yq eval '.infrastructure.initSecret ="$CONSTELL_INIT_SECRET"' --inplace constell yq eval '.infrastructure.clusterEndpoint ="$CONSTELL_IP"' --inplace constellation-state.yaml ``` - - + + ## The *init* step diff --git a/docs/versioned_docs/version-2.12/workflows/recovery.md b/docs/versioned_docs/version-2.12/workflows/recovery.md index 955981749..f2d5f22c1 100644 --- a/docs/versioned_docs/version-2.12/workflows/recovery.md +++ b/docs/versioned_docs/version-2.12/workflows/recovery.md @@ -16,8 +16,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via [cloud logging](troubleshooting.md#cloud-logging). In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -51,8 +51,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -87,8 +87,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, open the AWS console to view all Auto Scaling Groups (ASGs) in the region of your cluster. Select the ASG of the control plane `--control-plane` and check that enough members are in a *Running* state. @@ -118,8 +118,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + ## Recover a cluster diff --git a/docs/versioned_docs/version-2.12/workflows/scale.md b/docs/versioned_docs/version-2.12/workflows/scale.md index 06898ad0c..63b727c7d 100644 --- a/docs/versioned_docs/version-2.12/workflows/scale.md +++ b/docs/versioned_docs/version-2.12/workflows/scale.md @@ -51,30 +51,30 @@ kubectl -n kube-system get nodes Alternatively, you can manually scale your cluster up or down: - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + 1. Go to Auto Scaling Groups and select the worker ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + ## Control-plane node scaling @@ -82,30 +82,30 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - + - + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + 1. Go to Auto Scaling Groups and select the control-plane ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/versioned_docs/version-2.12/workflows/storage.md b/docs/versioned_docs/version-2.12/workflows/storage.md index 9e3d96346..06fbc4de6 100644 --- a/docs/versioned_docs/version-2.12/workflows/storage.md +++ b/docs/versioned_docs/version-2.12/workflows/storage.md @@ -21,30 +21,30 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as `ReadWriteOnce`, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for more information. - - + + **Constellation CSI driver for AWS Elastic Block Store** Mount [Elastic Block Store](https://aws.amazon.com/ebs/) storage volumes into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-aws-ebs-csi-driver) for more information. - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [AWS EFS](https://docs.aws.amazon.com/en_en/eks/latest/userguide/efs-csi.html), [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction), or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -53,8 +53,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The Constellation CLI automatically installs Constellation's CSI driver for the selected CSP in your cluster. If you don't need a CSI driver or wish to deploy your own, you can disable the automatic installation by setting `deployCSIDriver` to `false` in your Constellation config file. - - + + Azure comes with two storage classes by default. @@ -82,8 +82,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + GCP comes with two storage classes by default. @@ -111,8 +111,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + AWS comes with two storage classes by default. @@ -140,8 +140,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + 1. Create a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) diff --git a/docs/versioned_docs/version-2.12/workflows/terminate.md b/docs/versioned_docs/version-2.12/workflows/terminate.md index a990bc108..af7dbc1db 100644 --- a/docs/versioned_docs/version-2.12/workflows/terminate.md +++ b/docs/versioned_docs/version-2.12/workflows/terminate.md @@ -16,8 +16,8 @@ All ephemeral storage and state of your cluster will be lost. Make sure any data ::: - - + + Terminate the cluster by running: ```bash @@ -40,8 +40,8 @@ resources manually. Just run the `terminate` command again afterward to continue ::: - - + + Terminate the cluster by running: ```bash @@ -56,5 +56,5 @@ rm constellation-state.yaml constellation-admin.conf Only the `constellation-mastersecret.json` and the configuration file remain. - - + + diff --git a/docs/versioned_docs/version-2.12/workflows/troubleshooting.md b/docs/versioned_docs/version-2.12/workflows/troubleshooting.md index a3e25a0fe..c40e6496e 100644 --- a/docs/versioned_docs/version-2.12/workflows/troubleshooting.md +++ b/docs/versioned_docs/version-2.12/workflows/troubleshooting.md @@ -101,8 +101,8 @@ To provide information during early stages of a node's boot process, Constellati You can view this information in the following places: - - + + 1. In your Azure subscription find the Constellation resource group. 2. Inside the resource group find the Application Insights resource called `constellation-insights-*`. @@ -112,8 +112,8 @@ You can view this information in the following places: To **find the disk UUIDs** use the following query: `traces | where message contains "Disk UUID"` - - + + 1. Select the project that hosts Constellation. 2. Go to the `Compute Engine` service. @@ -128,16 +128,16 @@ Constellation uses the default bucket to store logs. Its [default retention peri ::: - - + + 1. Open [AWS CloudWatch](https://console.aws.amazon.com/cloudwatch/home) 2. Select [Log Groups](https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups) 3. Select the log group that matches the name of your cluster. 4. Select the log stream for control or worker type nodes. - - + + ### Node shell access diff --git a/docs/versioned_docs/version-2.13/architecture/attestation.md b/docs/versioned_docs/version-2.13/architecture/attestation.md index 576bc8865..8408cc5f0 100644 --- a/docs/versioned_docs/version-2.13/architecture/attestation.md +++ b/docs/versioned_docs/version-2.13/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -152,8 +152,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -185,8 +185,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements. @@ -217,16 +217,16 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + ### CVM verification To verify the integrity of the received attestation statement, a chain of trust from the CVM technology to the interface providing the statement has to be established. For verification of the CVM technology, Constellation may expose additional options in its config file. - - + + On Azure, AMD SEV-SNP is used to provide runtime encryption to the VMs. An SEV-SNP attestation report is used to establish trust in the vTPM running inside the VM. @@ -248,18 +248,18 @@ You may customize certain parameters for verification of the attestation stateme More explicitly, it controls the verification of the `IDKeyDigest` value in the SEV-SNP attestation report. You can provide a list of accepted key digests and specify a policy on how this list is compared against the reported `IDKeyDigest`. - - + + There is no additional configuration available for GCP. - - + + There is no additional configuration available for AWS. - - + + ## Cluster attestation diff --git a/docs/versioned_docs/version-2.13/getting-started/first-steps-local.md b/docs/versioned_docs/version-2.13/getting-started/first-steps-local.md index 90a7317af..890a12654 100644 --- a/docs/versioned_docs/version-2.13/getting-started/first-steps-local.md +++ b/docs/versioned_docs/version-2.13/getting-started/first-steps-local.md @@ -45,8 +45,8 @@ sudo iptables -P FORWARD ACCEPT ## Create a cluster - - + + 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/). @@ -74,8 +74,8 @@ 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. - - + + 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. @@ -152,8 +152,8 @@ attaching persistent storage, or autoscaling aren't available. export KUBECONFIG="$PWD/constellation-admin.conf" ``` - - + + ## Connect to the cluster @@ -206,8 +206,8 @@ worker-0 Ready 32s v1.24.6 ## Terminate your cluster - - + + Once you are done, you can clean up the created resources using the following command: @@ -218,8 +218,8 @@ 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. - - + + Once you are done, you can clean up the created resources using the following command: @@ -247,8 +247,8 @@ 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. - - + + ## Troubleshooting diff --git a/docs/versioned_docs/version-2.13/getting-started/first-steps.md b/docs/versioned_docs/version-2.13/getting-started/first-steps.md index 040be5478..287e0737a 100644 --- a/docs/versioned_docs/version-2.13/getting-started/first-steps.md +++ b/docs/versioned_docs/version-2.13/getting-started/first-steps.md @@ -15,39 +15,39 @@ If you encounter any problem with the following steps, make sure to use the [lat 1. Create the [configuration file](../workflows/config.md) and state file for your cloud provider. - + - + ```bash constellation config generate azure ``` - + - + ```bash constellation config generate gcp ``` - + - + ```bash constellation config generate aws ``` - + - + 2. Create your [IAM configuration](../workflows/config.md#creating-an-iam-configuration). - + - + ```bash constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest --update-config @@ -62,9 +62,9 @@ If you encounter any problem with the following steps, make sure to use the [lat * `westeurope` * `southeastasia` - + - + ```bash constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west2-a --serviceAccountID=constell-test --update-config @@ -74,9 +74,9 @@ If you encounter any problem with the following steps, make sure to use the [lat Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available), which you can filter by machine type `C2D` or `N2D`. - + - + ```bash constellation iam create aws --zone=us-east-2a --prefix=constellTest --update-config @@ -103,8 +103,8 @@ If you encounter any problem with the following steps, make sure to use the [lat You can find a list of all [regions in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). - - + + :::tip To learn about all options you have for managing IAM resources and Constellation configuration, see the [Configuration workflow](../workflows/config.md). diff --git a/docs/versioned_docs/version-2.13/getting-started/install.md b/docs/versioned_docs/version-2.13/getting-started/install.md index 035f679b2..2fabcf0b1 100644 --- a/docs/versioned_docs/version-2.13/getting-started/install.md +++ b/docs/versioned_docs/version-2.13/getting-started/install.md @@ -18,8 +18,8 @@ Make sure the following requirements are met: The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -35,8 +35,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -52,9 +52,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -70,9 +70,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -88,8 +88,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -105,39 +105,42 @@ If you don't have a cloud subscription, you can also set up a [local Constellati ### Required permissions - - + + The following [resource providers need to be registered](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) in your subscription: -* `Microsoft.Attestation` -* `Microsoft.Compute` -* `Microsoft.Insights` -* `Microsoft.ManagedIdentity` -* `Microsoft.Network` + +- `Microsoft.Attestation` +- `Microsoft.Compute` +- `Microsoft.Insights` +- `Microsoft.ManagedIdentity` +- `Microsoft.Network` By default, Constellation tries to register these automatically if they haven't been registered before. To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: -* `*/register/action` \[1] -* `Microsoft.Authorization/roleAssignments/*` -* `Microsoft.Authorization/roleDefinitions/*` -* `Microsoft.ManagedIdentity/userAssignedIdentities/*` -* `Microsoft.Resources/subscriptions/resourcegroups/*` + +- `*/register/action` \[1] +- `Microsoft.Authorization/roleAssignments/*` +- `Microsoft.Authorization/roleDefinitions/*` +- `Microsoft.ManagedIdentity/userAssignedIdentities/*` +- `Microsoft.Resources/subscriptions/resourcegroups/*` The built-in `Owner` role is a superset of these permissions. To [create a Constellation cluster](../workflows/create.md#the-create-step), you need the following permissions: -* `Microsoft.Attestation/attestationProviders/*` -* `Microsoft.Compute/virtualMachineScaleSets/*` -* `Microsoft.Insights/components/*` -* `Microsoft.ManagedIdentity/userAssignedIdentities/*` -* `Microsoft.Network/loadBalancers/*` -* `Microsoft.Network/loadBalancers/backendAddressPools/*` -* `Microsoft.Network/networkSecurityGroups/*` -* `Microsoft.Network/publicIPAddresses/*` -* `Microsoft.Network/virtualNetworks/*` -* `Microsoft.Network/virtualNetworks/subnets/*` -* `Microsoft.Network/natGateways/*` + +- `Microsoft.Attestation/attestationProviders/*` +- `Microsoft.Compute/virtualMachineScaleSets/*` +- `Microsoft.Insights/components/*` +- `Microsoft.ManagedIdentity/userAssignedIdentities/*` +- `Microsoft.Network/loadBalancers/*` +- `Microsoft.Network/loadBalancers/backendAddressPools/*` +- `Microsoft.Network/networkSecurityGroups/*` +- `Microsoft.Network/publicIPAddresses/*` +- `Microsoft.Network/virtualNetworks/*` +- `Microsoft.Network/virtualNetworks/subnets/*` +- `Microsoft.Network/natGateways/*` The built-in `Contributor` role is a superset of these permissions. @@ -145,92 +148,94 @@ Follow Microsoft's guide on [understanding](https://learn.microsoft.com/en-us/az 1: You can omit `*/register/Action` if the resource providers mentioned above are already registered and the `ARM_SKIP_PROVIDER_REGISTRATION` environment variable is set to `true` when creating the IAM configuration. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: -* `iam.serviceAccountKeys.create` -* `iam.serviceAccountKeys.delete` -* `iam.serviceAccountKeys.get` -* `iam.serviceAccounts.create` -* `iam.serviceAccounts.delete` -* `iam.serviceAccounts.get` -* `resourcemanager.projects.getIamPolicy` -* `resourcemanager.projects.setIamPolicy` + +- `iam.serviceAccountKeys.create` +- `iam.serviceAccountKeys.delete` +- `iam.serviceAccountKeys.get` +- `iam.serviceAccounts.create` +- `iam.serviceAccounts.delete` +- `iam.serviceAccounts.get` +- `resourcemanager.projects.getIamPolicy` +- `resourcemanager.projects.setIamPolicy` Together, the built-in roles `roles/editor` and `roles/resourcemanager.projectIamAdmin` form a superset of these permissions. To [create a Constellation cluster](../workflows/create.md#the-create-step), you need the following permissions: -* `compute.addresses.createInternal` -* `compute.addresses.deleteInternal` -* `compute.addresses.get` -* `compute.addresses.useInternal` -* `compute.backendServices.create` -* `compute.backendServices.delete` -* `compute.backendServices.get` -* `compute.backendServices.use` -* `compute.disks.create` -* `compute.firewalls.create` -* `compute.firewalls.delete` -* `compute.firewalls.get` -* `compute.firewalls.update` -* `compute.globalAddresses.create` -* `compute.globalAddresses.delete` -* `compute.globalAddresses.get` -* `compute.globalAddresses.use` -* `compute.globalForwardingRules.create` -* `compute.globalForwardingRules.delete` -* `compute.globalForwardingRules.get` -* `compute.globalForwardingRules.setLabels` -* `compute.globalOperations.get` -* `compute.healthChecks.create` -* `compute.healthChecks.delete` -* `compute.healthChecks.get` -* `compute.healthChecks.useReadOnly` -* `compute.instanceGroupManagers.create` -* `compute.instanceGroupManagers.delete` -* `compute.instanceGroupManagers.get` -* `compute.instanceGroupManagers.update` -* `compute.instanceGroups.create` -* `compute.instanceGroups.delete` -* `compute.instanceGroups.get` -* `compute.instanceGroups.update` -* `compute.instanceGroups.use` -* `compute.instances.create` -* `compute.instances.setLabels` -* `compute.instances.setMetadata` -* `compute.instances.setTags` -* `compute.instanceTemplates.create` -* `compute.instanceTemplates.delete` -* `compute.instanceTemplates.get` -* `compute.instanceTemplates.useReadOnly` -* `compute.networks.create` -* `compute.networks.delete` -* `compute.networks.get` -* `compute.networks.updatePolicy` -* `compute.routers.create` -* `compute.routers.delete` -* `compute.routers.get` -* `compute.routers.update` -* `compute.subnetworks.create` -* `compute.subnetworks.delete` -* `compute.subnetworks.get` -* `compute.subnetworks.use` -* `compute.targetTcpProxies.create` -* `compute.targetTcpProxies.delete` -* `compute.targetTcpProxies.get` -* `compute.targetTcpProxies.use` -* `iam.serviceAccounts.actAs` + +- `compute.addresses.createInternal` +- `compute.addresses.deleteInternal` +- `compute.addresses.get` +- `compute.addresses.useInternal` +- `compute.backendServices.create` +- `compute.backendServices.delete` +- `compute.backendServices.get` +- `compute.backendServices.use` +- `compute.disks.create` +- `compute.firewalls.create` +- `compute.firewalls.delete` +- `compute.firewalls.get` +- `compute.firewalls.update` +- `compute.globalAddresses.create` +- `compute.globalAddresses.delete` +- `compute.globalAddresses.get` +- `compute.globalAddresses.use` +- `compute.globalForwardingRules.create` +- `compute.globalForwardingRules.delete` +- `compute.globalForwardingRules.get` +- `compute.globalForwardingRules.setLabels` +- `compute.globalOperations.get` +- `compute.healthChecks.create` +- `compute.healthChecks.delete` +- `compute.healthChecks.get` +- `compute.healthChecks.useReadOnly` +- `compute.instanceGroupManagers.create` +- `compute.instanceGroupManagers.delete` +- `compute.instanceGroupManagers.get` +- `compute.instanceGroupManagers.update` +- `compute.instanceGroups.create` +- `compute.instanceGroups.delete` +- `compute.instanceGroups.get` +- `compute.instanceGroups.update` +- `compute.instanceGroups.use` +- `compute.instances.create` +- `compute.instances.setLabels` +- `compute.instances.setMetadata` +- `compute.instances.setTags` +- `compute.instanceTemplates.create` +- `compute.instanceTemplates.delete` +- `compute.instanceTemplates.get` +- `compute.instanceTemplates.useReadOnly` +- `compute.networks.create` +- `compute.networks.delete` +- `compute.networks.get` +- `compute.networks.updatePolicy` +- `compute.routers.create` +- `compute.routers.delete` +- `compute.routers.get` +- `compute.routers.update` +- `compute.subnetworks.create` +- `compute.subnetworks.delete` +- `compute.subnetworks.get` +- `compute.subnetworks.use` +- `compute.targetTcpProxies.create` +- `compute.targetTcpProxies.delete` +- `compute.targetTcpProxies.get` +- `compute.targetTcpProxies.use` +- `iam.serviceAccounts.actAs` Together, the built-in roles `roles/editor`, `roles/compute.instanceAdmin` and `roles/resourcemanager.projectIamAdmin` form a superset of these permissions. Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + To set up a Constellation cluster, you need to perform two tasks that require permissions: create the infrastructure and create roles for cluster nodes. Both of these actions can be performed by different users, e.g., an administrator to create roles and a DevOps engineer to create the infrastructure. @@ -280,8 +285,8 @@ The built-in `PowerUserAccess` policy is a superset of these permissions. Follow Amazon's guide on [understanding](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [managing policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html). - - + + ### Authentication @@ -291,8 +296,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -308,8 +313,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -332,8 +337,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + **Testing** @@ -349,9 +354,9 @@ aws configure Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - + - + ## Next steps diff --git a/docs/versioned_docs/version-2.13/workflows/config.md b/docs/versioned_docs/version-2.13/workflows/config.md index e076e2e34..4dab6bd50 100644 --- a/docs/versioned_docs/version-2.13/workflows/config.md +++ b/docs/versioned_docs/version-2.13/workflows/config.md @@ -14,49 +14,49 @@ Before you can create your cluster, you need to configure the identity and acces You can generate a configuration file for your CSP by using the following CLI command: - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate aws ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. ## Choosing a VM type Constellation supports the following VM types: - - + + 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. You can also run `constellation config instance-types` to get the list of all supported options. - - + + 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 with a minimum of 4 vCPUs from the [C2D](https://cloud.google.com/compute/docs/compute-optimized-machines#c2d_machine_types) or [N2D](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) family. You can run `constellation config instance-types` to get the list of all supported options. - - + + By default, Constellation uses `m6a.xlarge` 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. @@ -75,8 +75,8 @@ AWS is currently investigating the issue. SNP-based attestation will be enabled as soon as a fix is verified. ::: - - + + Fill the desired VM type into the **instanceType** fields in the `constellation-conf.yml` file. @@ -133,8 +133,8 @@ See also Constellation's [Kubernetes support policy](../architecture/versions.md You can create an IAM configuration for your cluster automatically using the `constellation iam create` command. If you already have a Constellation configuration file, you can add the `--update-config` flag to the command. This writes the needed IAM fields into your configuration. Furthermore, the flag updates the zone/region of the configuration if it hasn't been set yet. - - + + You must be authenticated with the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -154,8 +154,8 @@ Note that CVMs are currently only supported in a few regions, check [Azure's pro Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [GCP CLI](https://cloud.google.com/sdk/gcloud) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -169,8 +169,8 @@ Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [AWS CLI](https://aws.amazon.com/en/cli/) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -194,16 +194,16 @@ You can find a list of all [regions in AWS's documentation](https://docs.aws.ama Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + +
Alternatively, you can manually create the IAM configuration on your CSP. The following describes the configuration fields and how you obtain the required information or create the required resources. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -232,9 +232,9 @@ The following describes the configuration fields and how you obtain the required The user-assigned identity is used by instances of the cluster to access other cloud resources. For more information about managed identities refer to [Azure's documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities). - + - + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -258,9 +258,9 @@ The following describes the configuration fields and how you obtain the required Afterward, create and download a new JSON key for this service account. Place the downloaded file in your Constellation workspace, and set the config parameter to the filename, e.g., `constellation-129857-15343dba46cb.json`. - + - + * **region**: The name of your chosen AWS data center region, e.g., `us-east-2`. @@ -291,9 +291,9 @@ The following describes the configuration fields and how you obtain the required Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.worker_node_policy`. - + - +
Now that you've configured your CSP, you can [create your cluster](./create.md). diff --git a/docs/versioned_docs/version-2.13/workflows/create.md b/docs/versioned_docs/version-2.13/workflows/create.md index 387f68c8e..f347e9f27 100644 --- a/docs/versioned_docs/version-2.13/workflows/create.md +++ b/docs/versioned_docs/version-2.13/workflows/create.md @@ -26,8 +26,8 @@ Before you create the cluster, make sure to have a [valid configuration file](./ ### Create - - + + ```bash constellation create @@ -35,8 +35,8 @@ constellation create *create* stores your cluster's state in a [`constellation-terraform`](../architecture/orchestration.md#cluster-creation-process) directory in your workspace. - - + + Self-managed infrastructure allows for more flexibility in the setup, by separating the infrastructure setup from the Constellation cluster management. This provides flexibility in DevOps and can meet potential regulatory requirements. @@ -72,8 +72,8 @@ Fill these outputs into the corresponding fields of the `Infrastructure` block i Continue with [initializing your cluster](#the-apply-step). - - + + ## The *apply* step diff --git a/docs/versioned_docs/version-2.13/workflows/recovery.md b/docs/versioned_docs/version-2.13/workflows/recovery.md index 955981749..f2d5f22c1 100644 --- a/docs/versioned_docs/version-2.13/workflows/recovery.md +++ b/docs/versioned_docs/version-2.13/workflows/recovery.md @@ -16,8 +16,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via [cloud logging](troubleshooting.md#cloud-logging). In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -51,8 +51,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -87,8 +87,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, open the AWS console to view all Auto Scaling Groups (ASGs) in the region of your cluster. Select the ASG of the control plane `--control-plane` and check that enough members are in a *Running* state. @@ -118,8 +118,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + ## Recover a cluster diff --git a/docs/versioned_docs/version-2.13/workflows/scale.md b/docs/versioned_docs/version-2.13/workflows/scale.md index 06898ad0c..63b727c7d 100644 --- a/docs/versioned_docs/version-2.13/workflows/scale.md +++ b/docs/versioned_docs/version-2.13/workflows/scale.md @@ -51,30 +51,30 @@ kubectl -n kube-system get nodes Alternatively, you can manually scale your cluster up or down: - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + 1. Go to Auto Scaling Groups and select the worker ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + ## Control-plane node scaling @@ -82,30 +82,30 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - + - + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + 1. Go to Auto Scaling Groups and select the control-plane ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/versioned_docs/version-2.13/workflows/storage.md b/docs/versioned_docs/version-2.13/workflows/storage.md index 9e3d96346..06fbc4de6 100644 --- a/docs/versioned_docs/version-2.13/workflows/storage.md +++ b/docs/versioned_docs/version-2.13/workflows/storage.md @@ -21,30 +21,30 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as `ReadWriteOnce`, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for more information. - - + + **Constellation CSI driver for AWS Elastic Block Store** Mount [Elastic Block Store](https://aws.amazon.com/ebs/) storage volumes into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-aws-ebs-csi-driver) for more information. - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [AWS EFS](https://docs.aws.amazon.com/en_en/eks/latest/userguide/efs-csi.html), [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction), or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -53,8 +53,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The Constellation CLI automatically installs Constellation's CSI driver for the selected CSP in your cluster. If you don't need a CSI driver or wish to deploy your own, you can disable the automatic installation by setting `deployCSIDriver` to `false` in your Constellation config file. - - + + Azure comes with two storage classes by default. @@ -82,8 +82,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + GCP comes with two storage classes by default. @@ -111,8 +111,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + AWS comes with two storage classes by default. @@ -140,8 +140,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + 1. Create a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) diff --git a/docs/versioned_docs/version-2.13/workflows/terminate.md b/docs/versioned_docs/version-2.13/workflows/terminate.md index 168039fd2..e9599cb2b 100644 --- a/docs/versioned_docs/version-2.13/workflows/terminate.md +++ b/docs/versioned_docs/version-2.13/workflows/terminate.md @@ -16,8 +16,8 @@ All ephemeral storage and state of your cluster will be lost. Make sure any data ::: - - + + Terminate the cluster by running: ```bash @@ -40,8 +40,8 @@ resources manually. Just run the `terminate` command again afterward to continue ::: - - + + Terminate the cluster by running: ```bash @@ -56,5 +56,5 @@ rm constellation-state.yaml constellation-admin.conf Only the `constellation-mastersecret.json` and the configuration file remain. - - + + diff --git a/docs/versioned_docs/version-2.13/workflows/terraform-module.md b/docs/versioned_docs/version-2.13/workflows/terraform-module.md index e0534b9f5..07525cd27 100644 --- a/docs/versioned_docs/version-2.13/workflows/terraform-module.md +++ b/docs/versioned_docs/version-2.13/workflows/terraform-module.md @@ -1,12 +1,15 @@ # Use the Terraform module + You can manage a Constellation cluster through Terraform. The module package is available as part of the [GitHub release](https://github.com/edgelesssys/constellation/releases/). It consists of a convenience module for each cloud service provider (`{csp}-constellation`) that combines the IAM (`infrastructure/{csp}/iam`), infrastructure (`infrastructure/{csp}`), and constellation (`constellation-cluster`) modules. ## Prerequisites + - a Linux / Mac operating system - a Terraform installation of version `v1.4.4` or above ## Quick setup + The convenience module allows setting up a Constellation cluster with a single module. It's easiest to consume the module through a remote source, as shown below. This allows to upgrade the cluster to a newer Constellation version by simply updating the module source. @@ -18,6 +21,7 @@ The files are deleted on `terraform destroy`. ::: 1. Create a directory (workspace) for your Constellation cluster. + ```bash mkdir constellation-workspace cd constellation-workspace @@ -25,9 +29,9 @@ The files are deleted on `terraform destroy`. 1. Create a `main.tf` file to call the CSP specific Constellation module. - + - + ``` module "azure-constellation" { @@ -55,9 +59,9 @@ The files are deleted on `terraform destroy`. } ``` - + - + ``` module "aws-constellation" { @@ -86,9 +90,9 @@ The files are deleted on `terraform destroy`. } ``` - + - + ``` module "gcp-constellation" { @@ -118,25 +122,29 @@ The files are deleted on `terraform destroy`. } ``` - - + + 3. Initialize and apply the module. + ```bash terraform init terraform apply ``` ## Custom setup + If you need to separate IAM and cluster management or need custom infrastructure, you can also call the submodules individually. Look at the respective convenience module (`{csp}-constellation`) for how you can structure the module calls. The submodules are: + - `constellation-cluster`: manages the Constellation cluster - `fetch-image`: translates the Constellation image version to the image ID of the cloud service provider - `infrastructure/{csp}`: contains the cluster infrastructure resources - `infrastructure/iam/{csp}`: contains the IAM resources used within the cluster ## Cluster upgrades + :::tip For general information on cluster upgrades, see [Upgrade your cluster](./upgrade.md). ::: @@ -145,6 +153,7 @@ Using a [remote address as module source](https://developer.hashicorp.com/terraf 1. Update the `` variable inside the `source` field of the module. 2. Upgrade the Terraform module and provider dependencies and apply the Constellation upgrade. + ```bash terraform init -upgrade terraform apply diff --git a/docs/versioned_docs/version-2.13/workflows/troubleshooting.md b/docs/versioned_docs/version-2.13/workflows/troubleshooting.md index 05f515ed7..e8220c9a2 100644 --- a/docs/versioned_docs/version-2.13/workflows/troubleshooting.md +++ b/docs/versioned_docs/version-2.13/workflows/troubleshooting.md @@ -101,8 +101,8 @@ To provide information during early stages of a node's boot process, Constellati You can view this information in the following places: - - + + 1. In your Azure subscription find the Constellation resource group. 2. Inside the resource group find the Application Insights resource called `constellation-insights-*`. @@ -112,8 +112,8 @@ You can view this information in the following places: To **find the disk UUIDs** use the following query: `traces | where message contains "Disk UUID"` - - + + 1. Select the project that hosts Constellation. 2. Go to the `Compute Engine` service. @@ -128,16 +128,16 @@ Constellation uses the default bucket to store logs. Its [default retention peri ::: - - + + 1. Open [AWS CloudWatch](https://console.aws.amazon.com/cloudwatch/home) 2. Select [Log Groups](https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups) 3. Select the log group that matches the name of your cluster. 4. Select the log stream for control or worker type nodes. - - + + ### Node shell access diff --git a/docs/versioned_docs/version-2.14/architecture/attestation.md b/docs/versioned_docs/version-2.14/architecture/attestation.md index 04b85d8ad..415b41f47 100644 --- a/docs/versioned_docs/version-2.14/architecture/attestation.md +++ b/docs/versioned_docs/version-2.14/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -152,8 +152,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -185,8 +185,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements. @@ -217,16 +217,16 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + ### CVM verification To verify the integrity of the received attestation statement, a chain of trust from the CVM technology to the interface providing the statement has to be established. For verification of the CVM technology, Constellation may expose additional options in its config file. - - + + On Azure, AMD SEV-SNP is used to provide runtime encryption to the VMs. An SEV-SNP attestation report is used to establish trust in the vTPM running inside the VM. @@ -248,13 +248,13 @@ You may customize certain parameters for verification of the attestation stateme More explicitly, it controls the verification of the `IDKeyDigest` value in the SEV-SNP attestation report. You can provide a list of accepted key digests and specify a policy on how this list is compared against the reported `IDKeyDigest`. - - + + There is no additional configuration available for GCP. - - + + On AWS, AMD SEV-SNP is used to provide runtime encryption to the VMs. An SEV-SNP attestation report is used to establish trust in the VM and it's vTPM. @@ -275,8 +275,8 @@ You may customize certain parameters for verification of the attestation stateme This is the intermediate certificate for verifying the SEV-SNP report's signature. If it's not specified, the CLI fetches it from the AMD key distribution server. - - + + ## Cluster attestation diff --git a/docs/versioned_docs/version-2.14/getting-started/first-steps-local.md b/docs/versioned_docs/version-2.14/getting-started/first-steps-local.md index 052d29eae..98f0302de 100644 --- a/docs/versioned_docs/version-2.14/getting-started/first-steps-local.md +++ b/docs/versioned_docs/version-2.14/getting-started/first-steps-local.md @@ -45,8 +45,8 @@ sudo iptables -P FORWARD ACCEPT ## Create a cluster - - + + 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/). @@ -74,8 +74,8 @@ 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. - - + + 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. @@ -145,8 +145,8 @@ attaching persistent storage, or autoscaling aren't available. export KUBECONFIG="$PWD/constellation-admin.conf" ``` - - + + ## Connect to the cluster @@ -199,8 +199,8 @@ worker-0 Ready 32s v1.24.6 ## Terminate your cluster - - + + Once you are done, you can clean up the created resources using the following command: @@ -211,8 +211,8 @@ 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. - - + + Once you are done, you can clean up the created resources using the following command: @@ -240,8 +240,8 @@ 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. - - + + ## Troubleshooting diff --git a/docs/versioned_docs/version-2.14/getting-started/first-steps.md b/docs/versioned_docs/version-2.14/getting-started/first-steps.md index c58d4a0ae..a1f6cba25 100644 --- a/docs/versioned_docs/version-2.14/getting-started/first-steps.md +++ b/docs/versioned_docs/version-2.14/getting-started/first-steps.md @@ -15,39 +15,39 @@ If you encounter any problem with the following steps, make sure to use the [lat 1. Create the [configuration file](../workflows/config.md) and state file for your cloud provider. - + - + ```bash constellation config generate azure ``` - + - + ```bash constellation config generate gcp ``` - + - + ```bash constellation config generate aws ``` - + - + 2. Create your [IAM configuration](../workflows/config.md#creating-an-iam-configuration). - + - + ```bash constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest --update-config @@ -62,9 +62,9 @@ If you encounter any problem with the following steps, make sure to use the [lat * `westeurope` * `southeastasia` - + - + ```bash constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west2-a --serviceAccountID=constell-test --update-config @@ -74,9 +74,9 @@ If you encounter any problem with the following steps, make sure to use the [lat Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available), which you can filter by machine type `C2D` or `N2D`. - + - + ```bash constellation iam create aws --zone=us-east-2a --prefix=constellTest --update-config @@ -103,8 +103,8 @@ If you encounter any problem with the following steps, make sure to use the [lat You can find a list of all [regions in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). - - + + :::tip To learn about all options you have for managing IAM resources and Constellation configuration, see the [Configuration workflow](../workflows/config.md). diff --git a/docs/versioned_docs/version-2.14/getting-started/install.md b/docs/versioned_docs/version-2.14/getting-started/install.md index e74a45741..08e2315ef 100644 --- a/docs/versioned_docs/version-2.14/getting-started/install.md +++ b/docs/versioned_docs/version-2.14/getting-started/install.md @@ -22,8 +22,8 @@ If you prefer to use Terraform, you can alternatively use the [Terraform provide The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -39,8 +39,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -56,9 +56,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -74,9 +74,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -92,8 +92,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -109,8 +109,8 @@ If you don't have a cloud subscription, you can also set up a [local Constellati ### Required permissions - - + + The following [resource providers need to be registered](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) in your subscription: @@ -152,8 +152,8 @@ Follow Microsoft's guide on [understanding](https://learn.microsoft.com/en-us/az 1: You can omit `*/register/Action` if the resource providers mentioned above are already registered and the `ARM_SKIP_PROVIDER_REGISTRATION` environment variable is set to `true` when creating the IAM configuration. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. @@ -238,8 +238,8 @@ Together, the built-in roles `roles/editor`, `roles/compute.instanceAdmin` and ` Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + To set up a Constellation cluster, you need to perform two tasks that require permissions: create the infrastructure and create roles for cluster nodes. Both of these actions can be performed by different users, e.g., an administrator to create roles and a DevOps engineer to create the infrastructure. @@ -289,8 +289,8 @@ The built-in `PowerUserAccess` policy is a superset of these permissions. Follow Amazon's guide on [understanding](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [managing policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html). - - + + ### Authentication @@ -300,8 +300,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -317,8 +317,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -341,8 +341,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + **Testing** @@ -358,9 +358,9 @@ aws configure Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - + - + ## Next steps diff --git a/docs/versioned_docs/version-2.14/workflows/config.md b/docs/versioned_docs/version-2.14/workflows/config.md index 17be3792a..81d2b49fd 100644 --- a/docs/versioned_docs/version-2.14/workflows/config.md +++ b/docs/versioned_docs/version-2.14/workflows/config.md @@ -14,49 +14,49 @@ Before you can create your cluster, you need to configure the identity and acces You can generate a configuration file for your CSP by using the following CLI command: - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate aws ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. ## Choosing a VM type Constellation supports the following VM types: - - + + 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. You can also run `constellation config instance-types` to get the list of all supported options. - - + + 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 with a minimum of 4 vCPUs from the [C2D](https://cloud.google.com/compute/docs/compute-optimized-machines#c2d_machine_types) or [N2D](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) family. You can run `constellation config instance-types` to get the list of all supported options. - - + + By default, Constellation uses `m6a.xlarge` 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. @@ -67,8 +67,8 @@ If you are using the attestation variant `awsNitroTPM`, you can choose any of th The Constellation CLI can also print the supported instance types with: `constellation config instance-types`. - - + + Fill the desired VM type into the **instanceType** fields in the `constellation-conf.yml` file. @@ -125,8 +125,8 @@ See also Constellation's [Kubernetes support policy](../architecture/versions.md You can create an IAM configuration for your cluster automatically using the `constellation iam create` command. If you already have a Constellation configuration file, you can add the `--update-config` flag to the command. This writes the needed IAM fields into your configuration. Furthermore, the flag updates the zone/region of the configuration if it hasn't been set yet. - - + + You must be authenticated with the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -146,8 +146,8 @@ Note that CVMs are currently only supported in a few regions, check [Azure's pro Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [GCP CLI](https://cloud.google.com/sdk/gcloud) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -161,8 +161,8 @@ Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [AWS CLI](https://aws.amazon.com/en/cli/) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -186,16 +186,16 @@ You can find a list of all [regions in AWS's documentation](https://docs.aws.ama Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + +
Alternatively, you can manually create the IAM configuration on your CSP. The following describes the configuration fields and how you obtain the required information or create the required resources. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -224,9 +224,9 @@ The following describes the configuration fields and how you obtain the required The user-assigned identity is used by instances of the cluster to access other cloud resources. For more information about managed identities refer to [Azure's documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities). - + - + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -250,9 +250,9 @@ The following describes the configuration fields and how you obtain the required Afterward, create and download a new JSON key for this service account. Place the downloaded file in your Constellation workspace, and set the config parameter to the filename, e.g., `constellation-129857-15343dba46cb.json`. - + - + * **region**: The name of your chosen AWS data center region, e.g., `us-east-2`. @@ -283,9 +283,9 @@ The following describes the configuration fields and how you obtain the required Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.worker_node_policy`. - + - +
Now that you've configured your CSP, you can [create your cluster](./create.md). diff --git a/docs/versioned_docs/version-2.14/workflows/create.md b/docs/versioned_docs/version-2.14/workflows/create.md index 388cbedf8..6074ebb16 100644 --- a/docs/versioned_docs/version-2.14/workflows/create.md +++ b/docs/versioned_docs/version-2.14/workflows/create.md @@ -27,8 +27,8 @@ If you don't have a cloud subscription, you can also set up a [local Constellati Before you create the cluster, make sure to have a [valid configuration file](./config.md). - - + + ```bash constellation apply @@ -36,8 +36,8 @@ constellation apply `apply` stores the state of your cluster's cloud resources in a [`constellation-terraform`](../architecture/orchestration.md#cluster-creation-process) directory in your workspace. - - + + Self-managed infrastructure allows for more flexibility in the setup, by separating the infrastructure setup from the Constellation cluster management. This provides flexibility in DevOps and can meet potential regulatory requirements. @@ -77,8 +77,8 @@ With the required cloud resources set up, continue with initializing your cluste constellation apply --skip-phases=infrastructure ``` - - + + Finally, configure `kubectl` for your cluster: diff --git a/docs/versioned_docs/version-2.14/workflows/recovery.md b/docs/versioned_docs/version-2.14/workflows/recovery.md index 955981749..f2d5f22c1 100644 --- a/docs/versioned_docs/version-2.14/workflows/recovery.md +++ b/docs/versioned_docs/version-2.14/workflows/recovery.md @@ -16,8 +16,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via [cloud logging](troubleshooting.md#cloud-logging). In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -51,8 +51,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -87,8 +87,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, open the AWS console to view all Auto Scaling Groups (ASGs) in the region of your cluster. Select the ASG of the control plane `--control-plane` and check that enough members are in a *Running* state. @@ -118,8 +118,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + ## Recover a cluster diff --git a/docs/versioned_docs/version-2.14/workflows/scale.md b/docs/versioned_docs/version-2.14/workflows/scale.md index 06898ad0c..63b727c7d 100644 --- a/docs/versioned_docs/version-2.14/workflows/scale.md +++ b/docs/versioned_docs/version-2.14/workflows/scale.md @@ -51,30 +51,30 @@ kubectl -n kube-system get nodes Alternatively, you can manually scale your cluster up or down: - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + 1. Go to Auto Scaling Groups and select the worker ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + ## Control-plane node scaling @@ -82,30 +82,30 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - + - + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + 1. Go to Auto Scaling Groups and select the control-plane ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/versioned_docs/version-2.14/workflows/storage.md b/docs/versioned_docs/version-2.14/workflows/storage.md index 9e3d96346..06fbc4de6 100644 --- a/docs/versioned_docs/version-2.14/workflows/storage.md +++ b/docs/versioned_docs/version-2.14/workflows/storage.md @@ -21,30 +21,30 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as `ReadWriteOnce`, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for more information. - - + + **Constellation CSI driver for AWS Elastic Block Store** Mount [Elastic Block Store](https://aws.amazon.com/ebs/) storage volumes into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-aws-ebs-csi-driver) for more information. - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [AWS EFS](https://docs.aws.amazon.com/en_en/eks/latest/userguide/efs-csi.html), [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction), or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -53,8 +53,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The Constellation CLI automatically installs Constellation's CSI driver for the selected CSP in your cluster. If you don't need a CSI driver or wish to deploy your own, you can disable the automatic installation by setting `deployCSIDriver` to `false` in your Constellation config file. - - + + Azure comes with two storage classes by default. @@ -82,8 +82,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + GCP comes with two storage classes by default. @@ -111,8 +111,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + AWS comes with two storage classes by default. @@ -140,8 +140,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + 1. Create a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) diff --git a/docs/versioned_docs/version-2.14/workflows/terminate.md b/docs/versioned_docs/version-2.14/workflows/terminate.md index 11bbbb2ac..2c45bebe3 100644 --- a/docs/versioned_docs/version-2.14/workflows/terminate.md +++ b/docs/versioned_docs/version-2.14/workflows/terminate.md @@ -16,8 +16,8 @@ All ephemeral storage and state of your cluster will be lost. Make sure any data ::: - - + + Terminate the cluster by running: ```bash @@ -40,8 +40,8 @@ resources manually. Just run the `terminate` command again afterward to continue ::: - - + + Terminate the cluster by running: ```bash @@ -56,5 +56,5 @@ rm constellation-state.yaml constellation-admin.conf Only the `constellation-mastersecret.json` and the configuration file remain. - - + + diff --git a/docs/versioned_docs/version-2.14/workflows/terraform-provider.md b/docs/versioned_docs/version-2.14/workflows/terraform-provider.md index 7de44a530..e831ccc9e 100644 --- a/docs/versioned_docs/version-2.14/workflows/terraform-provider.md +++ b/docs/versioned_docs/version-2.14/workflows/terraform-provider.md @@ -21,9 +21,9 @@ This example shows how to set up a Constellation cluster with the reference IAM 2. Use one of the [example configurations for using the Constellation Terraform provider](https://github.com/edgelesssys/constellation/tree/main/terraform-provider-constellation/examples/full) or create a `main.tf` file and fill it with the resources you want to create. The [Constellation Terraform provider documentation](https://registry.terraform.io/providers/edgelesssys/constellation/latest) offers thorough documentation on the resources and their attributes. 3. Initialize and apply the Terraform configuration. - + - + When creating a cluster on Azure, you need to manually patch the policy of the MAA provider before creating the Constellation cluster, as this feature isn't available in Azure's Terraform provider yet. The Constellation CLI provides a utility for patching, but you can also do it manually. @@ -57,8 +57,8 @@ This example shows how to set up a Constellation cluster with the reference IAM }; ``` - - + + Initialize the providers and apply the configuration. ```bash @@ -67,8 +67,8 @@ This example shows how to set up a Constellation cluster with the reference IAM ``` Optionally, you can prefix the `terraform apply` command with `TF_LOG=INFO` to collect [Terraform logs](https://developer.hashicorp.com/terraform/internals/debugging) while applying the configuration. This may provide helpful output in debugging scenarios. - - + + Initialize the providers and apply the configuration. ```bash @@ -77,8 +77,8 @@ This example shows how to set up a Constellation cluster with the reference IAM ``` Optionally, you can prefix the `terraform apply` command with `TF_LOG=INFO` to collect [Terraform logs](https://developer.hashicorp.com/terraform/internals/debugging) while applying the configuration. This may provide helpful output in debugging scenarios. - - + + 4. Connect to the cluster. ```bash diff --git a/docs/versioned_docs/version-2.14/workflows/troubleshooting.md b/docs/versioned_docs/version-2.14/workflows/troubleshooting.md index 633053e0b..64d7d3355 100644 --- a/docs/versioned_docs/version-2.14/workflows/troubleshooting.md +++ b/docs/versioned_docs/version-2.14/workflows/troubleshooting.md @@ -101,8 +101,8 @@ To provide information during early stages of a node's boot process, Constellati You can view this information in the following places: - - + + 1. In your Azure subscription find the Constellation resource group. 2. Inside the resource group find the Application Insights resource called `constellation-insights-*`. @@ -112,8 +112,8 @@ You can view this information in the following places: To **find the disk UUIDs** use the following query: `traces | where message contains "Disk UUID"` - - + + 1. Select the project that hosts Constellation. 2. Go to the `Compute Engine` service. @@ -128,16 +128,16 @@ Constellation uses the default bucket to store logs. Its [default retention peri ::: - - + + 1. Open [AWS CloudWatch](https://console.aws.amazon.com/cloudwatch/home) 2. Select [Log Groups](https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups) 3. Select the log group that matches the name of your cluster. 4. Select the log stream for control or worker type nodes. - - + + ### Node shell access diff --git a/docs/versioned_docs/version-2.15/architecture/attestation.md b/docs/versioned_docs/version-2.15/architecture/attestation.md index 3e184fa03..286b2466d 100644 --- a/docs/versioned_docs/version-2.15/architecture/attestation.md +++ b/docs/versioned_docs/version-2.15/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -152,8 +152,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -185,8 +185,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements. @@ -217,16 +217,16 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + ### CVM verification To verify the integrity of the received attestation statement, a chain of trust from the CVM technology to the interface providing the statement has to be established. For verification of the CVM technology, Constellation may expose additional options in its config file. - - + + On Azure, AMD SEV-SNP is used to provide runtime encryption to the VMs. An SEV-SNP attestation report is used to establish trust in the vTPM running inside the VM. @@ -248,13 +248,13 @@ You may customize certain parameters for verification of the attestation stateme More explicitly, it controls the verification of the `IDKeyDigest` value in the SEV-SNP attestation report. You can provide a list of accepted key digests and specify a policy on how this list is compared against the reported `IDKeyDigest`. - - + + There is no additional configuration available for GCP. - - + + On AWS, AMD SEV-SNP is used to provide runtime encryption to the VMs. An SEV-SNP attestation report is used to establish trust in the VM and it's vTPM. @@ -275,8 +275,8 @@ You may customize certain parameters for verification of the attestation stateme This is the intermediate certificate for verifying the SEV-SNP report's signature. If it's not specified, the CLI fetches it from the AMD key distribution server. - - + + ## Cluster attestation diff --git a/docs/versioned_docs/version-2.15/getting-started/first-steps-local.md b/docs/versioned_docs/version-2.15/getting-started/first-steps-local.md index 052d29eae..98f0302de 100644 --- a/docs/versioned_docs/version-2.15/getting-started/first-steps-local.md +++ b/docs/versioned_docs/version-2.15/getting-started/first-steps-local.md @@ -45,8 +45,8 @@ sudo iptables -P FORWARD ACCEPT ## Create a cluster - - + + 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/). @@ -74,8 +74,8 @@ 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. - - + + 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. @@ -145,8 +145,8 @@ attaching persistent storage, or autoscaling aren't available. export KUBECONFIG="$PWD/constellation-admin.conf" ``` - - + + ## Connect to the cluster @@ -199,8 +199,8 @@ worker-0 Ready 32s v1.24.6 ## Terminate your cluster - - + + Once you are done, you can clean up the created resources using the following command: @@ -211,8 +211,8 @@ 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. - - + + Once you are done, you can clean up the created resources using the following command: @@ -240,8 +240,8 @@ 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. - - + + ## Troubleshooting diff --git a/docs/versioned_docs/version-2.15/getting-started/first-steps.md b/docs/versioned_docs/version-2.15/getting-started/first-steps.md index dc867bf77..a6efd758f 100644 --- a/docs/versioned_docs/version-2.15/getting-started/first-steps.md +++ b/docs/versioned_docs/version-2.15/getting-started/first-steps.md @@ -15,39 +15,39 @@ If you encounter any problem with the following steps, make sure to use the [lat 1. Create the [configuration file](../workflows/config.md) and state file for your cloud provider. - + - + ```bash constellation config generate azure ``` - + - + ```bash constellation config generate gcp ``` - + - + ```bash constellation config generate aws ``` - + - + 2. Create your [IAM configuration](../workflows/config.md#creating-an-iam-configuration). - + - + ```bash constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest --update-config @@ -68,9 +68,9 @@ If you encounter any problem with the following steps, make sure to use the [lat You can find a list of all [regions in Azure's documentation](https://azure.microsoft.com/en-us/global-infrastructure/services/?products=virtual-machines®ions=all). - + - + ```bash constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west2-a --serviceAccountID=constell-test --update-config @@ -80,9 +80,9 @@ If you encounter any problem with the following steps, make sure to use the [lat Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available), which you can filter by machine type `C2D` or `N2D`. - + - + ```bash constellation iam create aws --zone=us-east-2a --prefix=constellTest --update-config @@ -109,8 +109,8 @@ If you encounter any problem with the following steps, make sure to use the [lat You can find a list of all [regions in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). - - + + :::tip To learn about all options you have for managing IAM resources and Constellation configuration, see the [Configuration workflow](../workflows/config.md). diff --git a/docs/versioned_docs/version-2.15/getting-started/install.md b/docs/versioned_docs/version-2.15/getting-started/install.md index e74a45741..08e2315ef 100644 --- a/docs/versioned_docs/version-2.15/getting-started/install.md +++ b/docs/versioned_docs/version-2.15/getting-started/install.md @@ -22,8 +22,8 @@ If you prefer to use Terraform, you can alternatively use the [Terraform provide The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -39,8 +39,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -56,9 +56,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -74,9 +74,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -92,8 +92,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -109,8 +109,8 @@ If you don't have a cloud subscription, you can also set up a [local Constellati ### Required permissions - - + + The following [resource providers need to be registered](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) in your subscription: @@ -152,8 +152,8 @@ Follow Microsoft's guide on [understanding](https://learn.microsoft.com/en-us/az 1: You can omit `*/register/Action` if the resource providers mentioned above are already registered and the `ARM_SKIP_PROVIDER_REGISTRATION` environment variable is set to `true` when creating the IAM configuration. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. @@ -238,8 +238,8 @@ Together, the built-in roles `roles/editor`, `roles/compute.instanceAdmin` and ` Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + To set up a Constellation cluster, you need to perform two tasks that require permissions: create the infrastructure and create roles for cluster nodes. Both of these actions can be performed by different users, e.g., an administrator to create roles and a DevOps engineer to create the infrastructure. @@ -289,8 +289,8 @@ The built-in `PowerUserAccess` policy is a superset of these permissions. Follow Amazon's guide on [understanding](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [managing policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html). - - + + ### Authentication @@ -300,8 +300,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -317,8 +317,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -341,8 +341,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + **Testing** @@ -358,9 +358,9 @@ aws configure Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - + - + ## Next steps diff --git a/docs/versioned_docs/version-2.15/workflows/config.md b/docs/versioned_docs/version-2.15/workflows/config.md index dc5dd0e41..92ff9d040 100644 --- a/docs/versioned_docs/version-2.15/workflows/config.md +++ b/docs/versioned_docs/version-2.15/workflows/config.md @@ -14,49 +14,49 @@ Before you can create your cluster, you need to configure the identity and acces You can generate a configuration file for your CSP by using the following CLI command: - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate aws ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. ## Choosing a VM type Constellation supports the following VM types: - - + + 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. You can also run `constellation config instance-types` to get the list of all supported options. - - + + 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 with a minimum of 4 vCPUs from the [C2D](https://cloud.google.com/compute/docs/compute-optimized-machines#c2d_machine_types) or [N2D](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) family. You can run `constellation config instance-types` to get the list of all supported options. - - + + By default, Constellation uses `m6a.xlarge` 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. @@ -67,8 +67,8 @@ If you are using the attestation variant `awsNitroTPM`, you can choose any of th The Constellation CLI can also print the supported instance types with: `constellation config instance-types`. - - + + Fill the desired VM type into the `instanceType` fields in the `constellation-conf.yml` file. @@ -125,8 +125,8 @@ See also Constellation's [Kubernetes support policy](../architecture/versions.md You can create an IAM configuration for your cluster automatically using the `constellation iam create` command. If you already have a Constellation configuration file, you can add the `--update-config` flag to the command. This writes the needed IAM fields into your configuration. Furthermore, the flag updates the zone/region of the configuration if it hasn't been set yet. - - + + You must be authenticated with the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -151,8 +151,8 @@ You can find a list of all [regions in Azure's documentation](https://azure.micr Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [GCP CLI](https://cloud.google.com/sdk/gcloud) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -166,8 +166,8 @@ Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [AWS CLI](https://aws.amazon.com/en/cli/) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -191,16 +191,16 @@ You can find a list of all [regions in AWS's documentation](https://docs.aws.ama Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + +
Alternatively, you can manually create the IAM configuration on your CSP. The following describes the configuration fields and how you obtain the required information or create the required resources. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -236,9 +236,9 @@ The following describes the configuration fields and how you obtain the required The user-assigned identity is used by instances of the cluster to access other cloud resources. For more information about managed identities refer to [Azure's documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities). - + - + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -262,9 +262,9 @@ The following describes the configuration fields and how you obtain the required Afterward, create and download a new JSON key for this service account. Place the downloaded file in your Constellation workspace, and set the config parameter to the filename, e.g., `constellation-129857-15343dba46cb.json`. - + - + * **region**: The name of your chosen AWS data center region, e.g., `us-east-2`. @@ -295,9 +295,9 @@ The following describes the configuration fields and how you obtain the required Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.worker_node_policy`. - + - +
Now that you've configured your CSP, you can [create your cluster](./create.md). diff --git a/docs/versioned_docs/version-2.15/workflows/create.md b/docs/versioned_docs/version-2.15/workflows/create.md index 388cbedf8..6074ebb16 100644 --- a/docs/versioned_docs/version-2.15/workflows/create.md +++ b/docs/versioned_docs/version-2.15/workflows/create.md @@ -27,8 +27,8 @@ If you don't have a cloud subscription, you can also set up a [local Constellati Before you create the cluster, make sure to have a [valid configuration file](./config.md). - - + + ```bash constellation apply @@ -36,8 +36,8 @@ constellation apply `apply` stores the state of your cluster's cloud resources in a [`constellation-terraform`](../architecture/orchestration.md#cluster-creation-process) directory in your workspace. - - + + Self-managed infrastructure allows for more flexibility in the setup, by separating the infrastructure setup from the Constellation cluster management. This provides flexibility in DevOps and can meet potential regulatory requirements. @@ -77,8 +77,8 @@ With the required cloud resources set up, continue with initializing your cluste constellation apply --skip-phases=infrastructure ``` - - + + Finally, configure `kubectl` for your cluster: diff --git a/docs/versioned_docs/version-2.15/workflows/recovery.md b/docs/versioned_docs/version-2.15/workflows/recovery.md index 9396bf8f2..592ab74af 100644 --- a/docs/versioned_docs/version-2.15/workflows/recovery.md +++ b/docs/versioned_docs/version-2.15/workflows/recovery.md @@ -16,8 +16,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via serial console output. In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -51,8 +51,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -87,8 +87,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, open the AWS console to view all Auto Scaling Groups (ASGs) in the region of your cluster. Select the ASG of the control plane `--control-plane` and check that enough members are in a *Running* state. @@ -118,8 +118,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + ## Recover a cluster diff --git a/docs/versioned_docs/version-2.15/workflows/scale.md b/docs/versioned_docs/version-2.15/workflows/scale.md index 06898ad0c..63b727c7d 100644 --- a/docs/versioned_docs/version-2.15/workflows/scale.md +++ b/docs/versioned_docs/version-2.15/workflows/scale.md @@ -51,30 +51,30 @@ kubectl -n kube-system get nodes Alternatively, you can manually scale your cluster up or down: - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + 1. Go to Auto Scaling Groups and select the worker ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + ## Control-plane node scaling @@ -82,30 +82,30 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - + - + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + 1. Go to Auto Scaling Groups and select the control-plane ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/versioned_docs/version-2.15/workflows/storage.md b/docs/versioned_docs/version-2.15/workflows/storage.md index 9e3d96346..06fbc4de6 100644 --- a/docs/versioned_docs/version-2.15/workflows/storage.md +++ b/docs/versioned_docs/version-2.15/workflows/storage.md @@ -21,30 +21,30 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as `ReadWriteOnce`, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for more information. - - + + **Constellation CSI driver for AWS Elastic Block Store** Mount [Elastic Block Store](https://aws.amazon.com/ebs/) storage volumes into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-aws-ebs-csi-driver) for more information. - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [AWS EFS](https://docs.aws.amazon.com/en_en/eks/latest/userguide/efs-csi.html), [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction), or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -53,8 +53,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The Constellation CLI automatically installs Constellation's CSI driver for the selected CSP in your cluster. If you don't need a CSI driver or wish to deploy your own, you can disable the automatic installation by setting `deployCSIDriver` to `false` in your Constellation config file. - - + + Azure comes with two storage classes by default. @@ -82,8 +82,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + GCP comes with two storage classes by default. @@ -111,8 +111,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + AWS comes with two storage classes by default. @@ -140,8 +140,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + 1. Create a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) diff --git a/docs/versioned_docs/version-2.15/workflows/terminate.md b/docs/versioned_docs/version-2.15/workflows/terminate.md index 11bbbb2ac..2c45bebe3 100644 --- a/docs/versioned_docs/version-2.15/workflows/terminate.md +++ b/docs/versioned_docs/version-2.15/workflows/terminate.md @@ -16,8 +16,8 @@ All ephemeral storage and state of your cluster will be lost. Make sure any data ::: - - + + Terminate the cluster by running: ```bash @@ -40,8 +40,8 @@ resources manually. Just run the `terminate` command again afterward to continue ::: - - + + Terminate the cluster by running: ```bash @@ -56,5 +56,5 @@ rm constellation-state.yaml constellation-admin.conf Only the `constellation-mastersecret.json` and the configuration file remain. - - + + diff --git a/docs/versioned_docs/version-2.15/workflows/terraform-provider.md b/docs/versioned_docs/version-2.15/workflows/terraform-provider.md index 7de44a530..e831ccc9e 100644 --- a/docs/versioned_docs/version-2.15/workflows/terraform-provider.md +++ b/docs/versioned_docs/version-2.15/workflows/terraform-provider.md @@ -21,9 +21,9 @@ This example shows how to set up a Constellation cluster with the reference IAM 2. Use one of the [example configurations for using the Constellation Terraform provider](https://github.com/edgelesssys/constellation/tree/main/terraform-provider-constellation/examples/full) or create a `main.tf` file and fill it with the resources you want to create. The [Constellation Terraform provider documentation](https://registry.terraform.io/providers/edgelesssys/constellation/latest) offers thorough documentation on the resources and their attributes. 3. Initialize and apply the Terraform configuration. - + - + When creating a cluster on Azure, you need to manually patch the policy of the MAA provider before creating the Constellation cluster, as this feature isn't available in Azure's Terraform provider yet. The Constellation CLI provides a utility for patching, but you can also do it manually. @@ -57,8 +57,8 @@ This example shows how to set up a Constellation cluster with the reference IAM }; ``` - - + + Initialize the providers and apply the configuration. ```bash @@ -67,8 +67,8 @@ This example shows how to set up a Constellation cluster with the reference IAM ``` Optionally, you can prefix the `terraform apply` command with `TF_LOG=INFO` to collect [Terraform logs](https://developer.hashicorp.com/terraform/internals/debugging) while applying the configuration. This may provide helpful output in debugging scenarios. - - + + Initialize the providers and apply the configuration. ```bash @@ -77,8 +77,8 @@ This example shows how to set up a Constellation cluster with the reference IAM ``` Optionally, you can prefix the `terraform apply` command with `TF_LOG=INFO` to collect [Terraform logs](https://developer.hashicorp.com/terraform/internals/debugging) while applying the configuration. This may provide helpful output in debugging scenarios. - - + + 4. Connect to the cluster. ```bash diff --git a/docs/versioned_docs/version-2.16/architecture/attestation.md b/docs/versioned_docs/version-2.16/architecture/attestation.md index 7dbfc9392..a07b35e5a 100644 --- a/docs/versioned_docs/version-2.16/architecture/attestation.md +++ b/docs/versioned_docs/version-2.16/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements. @@ -153,8 +153,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -184,8 +184,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -217,8 +217,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses a hypervisor-based vTPM for runtime measurements. @@ -249,16 +249,16 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + ### CVM verification To verify the integrity of the received attestation statement, a chain of trust from the CVM technology to the interface providing the statement has to be established. For verification of the CVM technology, Constellation may expose additional options in its config file. - - + + On AWS, AMD SEV-SNP is used to provide runtime encryption to the VMs. An SEV-SNP attestation report is used to establish trust in the VM. @@ -279,8 +279,8 @@ You may customize certain parameters for verification of the attestation stateme This is the intermediate certificate for verifying the SEV-SNP report's signature. If it's not specified, the CLI fetches it from the AMD key distribution server. - - + + On Azure, AMD SEV-SNP is used to provide runtime encryption to the VMs. An SEV-SNP attestation report is used to establish trust in the vTPM running inside the VM. @@ -302,22 +302,22 @@ You may customize certain parameters for verification of the attestation stateme More explicitly, it controls the verification of the `IDKeyDigest` value in the SEV-SNP attestation report. You can provide a list of accepted key digests and specify a policy on how this list is compared against the reported `IDKeyDigest`. - - + + On GCP, AMD SEV-ES is used to provide runtime encryption to the VMs. The hypervisor-based vTPM is used to establish trust in the VM via [runtime measurements](#runtime-measurements). There is no additional configuration available for GCP. - - + + On STACKIT, AMD SEV-ES is used to provide runtime encryption to the VMs. The hypervisor-based vTPM is used to establish trust in the VM via [runtime measurements](#runtime-measurements). There is no additional configuration available for STACKIT. - - + + ## Cluster attestation diff --git a/docs/versioned_docs/version-2.16/getting-started/first-steps-local.md b/docs/versioned_docs/version-2.16/getting-started/first-steps-local.md index 052d29eae..98f0302de 100644 --- a/docs/versioned_docs/version-2.16/getting-started/first-steps-local.md +++ b/docs/versioned_docs/version-2.16/getting-started/first-steps-local.md @@ -45,8 +45,8 @@ sudo iptables -P FORWARD ACCEPT ## Create a cluster - - + + 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/). @@ -74,8 +74,8 @@ 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. - - + + 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. @@ -145,8 +145,8 @@ attaching persistent storage, or autoscaling aren't available. export KUBECONFIG="$PWD/constellation-admin.conf" ``` - - + + ## Connect to the cluster @@ -199,8 +199,8 @@ worker-0 Ready 32s v1.24.6 ## Terminate your cluster - - + + Once you are done, you can clean up the created resources using the following command: @@ -211,8 +211,8 @@ 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. - - + + Once you are done, you can clean up the created resources using the following command: @@ -240,8 +240,8 @@ 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. - - + + ## Troubleshooting diff --git a/docs/versioned_docs/version-2.16/getting-started/first-steps.md b/docs/versioned_docs/version-2.16/getting-started/first-steps.md index b29bf5926..d82d93836 100644 --- a/docs/versioned_docs/version-2.16/getting-started/first-steps.md +++ b/docs/versioned_docs/version-2.16/getting-started/first-steps.md @@ -15,41 +15,41 @@ If you encounter any problem with the following steps, make sure to use the [lat 1. Create the [configuration file](../workflows/config.md) and state file for your cloud provider. - - + + ```bash constellation config generate aws ``` - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate stackit ``` - - + + 2. Create your [IAM configuration](../workflows/config.md#creating-an-iam-configuration). - - + + ```bash constellation iam create aws --zone=us-east-2a --prefix=constellTest --update-config @@ -76,8 +76,8 @@ If you encounter any problem with the following steps, make sure to use the [lat You can find a list of all [regions in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). - - + + ```bash constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest --update-config @@ -98,8 +98,8 @@ If you encounter any problem with the following steps, make sure to use the [lat You can find a list of all [regions in Azure's documentation](https://azure.microsoft.com/en-us/global-infrastructure/services/?products=virtual-machines®ions=all). - - + + ```bash constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west2-a --serviceAccountID=constell-test --update-config @@ -109,16 +109,16 @@ If you encounter any problem with the following steps, make sure to use the [lat Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available), which you can filter by machine type `C2D` or `N2D`. - - + + To use Constellation on STACKIT, the cluster will use the User Access Token (UAT) that's generated [during the install step](./install.md). After creating the accounts, fill in the STACKIT details in `constellation-conf.yaml` under `provider.openstack`: * `stackitProjectID`: STACKIT project id (can be found after login on the [STACKIT portal](https://portal.stackit.cloud)) - - + + :::tip To learn about all options you have for managing IAM resources and Constellation configuration, see the [Configuration workflow](../workflows/config.md). diff --git a/docs/versioned_docs/version-2.16/getting-started/install.md b/docs/versioned_docs/version-2.16/getting-started/install.md index 4ebd9351a..d52e43476 100644 --- a/docs/versioned_docs/version-2.16/getting-started/install.md +++ b/docs/versioned_docs/version-2.16/getting-started/install.md @@ -22,8 +22,8 @@ If you prefer to use Terraform, you can alternatively use the [Terraform provide The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -39,8 +39,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -56,9 +56,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -74,9 +74,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -92,9 +92,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -115,8 +115,8 @@ Invoke-WebRequest -OutFile ./constellation.exe -Uri 'https://github.com/edgeless 5. Click `New` 6. Enter the path to the folder containing the binary you want on your PATH: `C:\Program Files\Constellation\bin` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -132,8 +132,8 @@ If you don't have a cloud subscription, you can also set up a [local Constellati ### Required permissions - - + + To set up a Constellation cluster, you need to perform two tasks that require permissions: create the infrastructure and create roles for cluster nodes. Both of these actions can be performed by different users, e.g., an administrator to create roles and a DevOps engineer to create the infrastructure. @@ -183,8 +183,8 @@ The built-in `PowerUserAccess` policy is a superset of these permissions. Follow Amazon's guide on [understanding](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [managing policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html). - - + + The following [resource providers need to be registered](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) in your subscription: @@ -226,8 +226,8 @@ Follow Microsoft's guide on [understanding](https://learn.microsoft.com/en-us/az 1: You can omit `*/register/Action` if the resource providers mentioned above are already registered and the `ARM_SKIP_PROVIDER_REGISTRATION` environment variable is set to `true` when creating the IAM configuration. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. @@ -312,16 +312,16 @@ Together, the built-in roles `roles/editor`, `roles/compute.instanceAdmin` and ` Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + Constellation on STACKIT requires a User Access Token (UAT) for the OpenStack API and a STACKIT service account. The UAT already has all required permissions by default. The STACKIT service account needs the `editor` role to create STACKIT LoadBalancers. Look at the [STACKIT documentation](https://docs.stackit.cloud/stackit/en/getting-started-in-service-accounts-134415831.html) on how to create the service account and assign the role. - - + + ### Authentication @@ -331,8 +331,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -348,8 +348,8 @@ aws configure Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - - + + **Testing** @@ -365,8 +365,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -389,8 +389,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + You need to authenticate with the infrastructure API (OpenStack) and create a service account (STACKIT API). @@ -420,9 +420,9 @@ You need to authenticate with the infrastructure API (OpenStack) and create a se {"STACKIT_SERVICE_ACCOUNT_TOKEN":"REPLACE_WITH_TOKEN"} ``` - + - + ## Next steps diff --git a/docs/versioned_docs/version-2.16/getting-started/marketplaces.md b/docs/versioned_docs/version-2.16/getting-started/marketplaces.md index b16d796d2..a6763a42a 100644 --- a/docs/versioned_docs/version-2.16/getting-started/marketplaces.md +++ b/docs/versioned_docs/version-2.16/getting-started/marketplaces.md @@ -4,8 +4,8 @@ Constellation is available through the Marketplaces of AWS, Azure, GCP, and STAC This document explains how to run Constellation with the dynamically billed cloud marketplace images. - - + + To use Constellation's marketplace images, ensure that you are subscribed to the [marketplace offering](https://aws.amazon.com/marketplace/pp/prodview-2mbn65nv57oys) through the web portal. @@ -15,8 +15,8 @@ Then, enable the use of marketplace images in your Constellation `constellation- yq eval -i ".provider.aws.useMarketplaceImage = true" constellation-conf.yaml ``` - - + + Constellation has a private marketplace plan. Please [contact us](https://www.edgeless.systems/enterprise-support/) to gain access. @@ -32,8 +32,8 @@ Then, enable the use of marketplace images in your Constellation `constellation- yq eval -i ".provider.azure.useMarketplaceImage = true" constellation-conf.yaml ``` - - + + To use a marketplace image, ensure that the account is entitled to use marketplace images by Edgeless Systems by accepting the terms through the [web portal](https://console.cloud.google.com/marketplace/vm/config/edgeless-systems-public/constellation). @@ -43,13 +43,13 @@ Then, enable the use of marketplace images in your Constellation `constellation- yq eval -i ".provider.gcp.useMarketplaceImage = true" constellation-conf.yaml ``` - - + + On STACKIT, the selected Constellation image is always a marketplace image. You can find more information on the STACKIT portal. - - + + Ensure that the cluster uses an official release image version (i.e., `.image=vX.Y.Z` in the `constellation-conf.yaml` file). diff --git a/docs/versioned_docs/version-2.16/workflows/config.md b/docs/versioned_docs/version-2.16/workflows/config.md index 9da4305de..120bf8ed7 100644 --- a/docs/versioned_docs/version-2.16/workflows/config.md +++ b/docs/versioned_docs/version-2.16/workflows/config.md @@ -14,44 +14,44 @@ Before you can create your cluster, you need to configure the identity and acces You can generate a configuration file for your CSP by using the following CLI command: - - + + ```bash constellation config generate aws ``` - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate stackit ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. ## Choosing a VM type Constellation supports the following VM types: - - + + By default, Constellation uses `m6a.xlarge` 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. @@ -62,20 +62,20 @@ If you are using the attestation variant `awsNitroTPM`, you can choose any of th The Constellation CLI can also print the supported instance types with: `constellation config instance-types`. - - + + 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. You can also run `constellation config instance-types` to get the list of all supported options. - - + + 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 with a minimum of 4 vCPUs from the [C2D](https://cloud.google.com/compute/docs/compute-optimized-machines#c2d_machine_types) or [N2D](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) family. You can run `constellation config instance-types` to get the list of all supported options. - - + + By default, Constellation uses `m1a.4cd` VMs (4 vCPUs, 30 GB RAM) to create your cluster. Optionally, you can switch to a different VM type by modifying `instanceType` in the configuration file. @@ -93,8 +93,8 @@ You can choose any of the SEV-enabled instance types. You can find a list of all The Constellation CLI can also print the supported instance types with: `constellation config instance-types`. - - + + Fill the desired VM type into the `instanceType` fields in the `constellation-conf.yml` file. @@ -153,8 +153,8 @@ See also Constellation's [Kubernetes support policy](../architecture/versions.md You can create an IAM configuration for your cluster automatically using the `constellation iam create` command. If you already have a Constellation configuration file, you can add the `--update-config` flag to the command. This writes the needed IAM fields into your configuration. Furthermore, the flag updates the zone/region of the configuration if it hasn't been set yet. - - + + You must be authenticated with the [AWS CLI](https://aws.amazon.com/en/cli/) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -178,8 +178,8 @@ You can find a list of all [regions in AWS's documentation](https://docs.aws.ama Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -204,8 +204,8 @@ You can find a list of all [regions in Azure's documentation](https://azure.micr Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [GCP CLI](https://cloud.google.com/sdk/gcloud) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -219,21 +219,21 @@ Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + STACKIT requires manual creation and configuration of service accounts. Look at the [first steps](../getting-started/first-steps.md) for more information. - - + +
Alternatively, you can manually create the IAM configuration on your CSP. The following describes the configuration fields and how you obtain the required information or create the required resources. - - + + * **region**: The name of your chosen AWS data center region, e.g., `us-east-2`. @@ -264,8 +264,8 @@ The following describes the configuration fields and how you obtain the required Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.worker_node_policy`. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -301,8 +301,8 @@ The following describes the configuration fields and how you obtain the required The user-assigned identity is used by instances of the cluster to access other cloud resources. For more information about managed identities refer to [Azure's documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities). - - + + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -326,13 +326,13 @@ The following describes the configuration fields and how you obtain the required Afterward, create and download a new JSON key for this service account. Place the downloaded file in your Constellation workspace, and set the config parameter to the filename, e.g., `constellation-129857-15343dba46cb.json`. - - + + STACKIT requires manual creation and configuration of service accounts. Look at the [first steps](../getting-started/first-steps.md) for more information. - - + +
Now that you've configured your CSP, you can [create your cluster](./create.md). diff --git a/docs/versioned_docs/version-2.16/workflows/create.md b/docs/versioned_docs/version-2.16/workflows/create.md index 388cbedf8..6074ebb16 100644 --- a/docs/versioned_docs/version-2.16/workflows/create.md +++ b/docs/versioned_docs/version-2.16/workflows/create.md @@ -27,8 +27,8 @@ If you don't have a cloud subscription, you can also set up a [local Constellati Before you create the cluster, make sure to have a [valid configuration file](./config.md). - - + + ```bash constellation apply @@ -36,8 +36,8 @@ constellation apply `apply` stores the state of your cluster's cloud resources in a [`constellation-terraform`](../architecture/orchestration.md#cluster-creation-process) directory in your workspace. - - + + Self-managed infrastructure allows for more flexibility in the setup, by separating the infrastructure setup from the Constellation cluster management. This provides flexibility in DevOps and can meet potential regulatory requirements. @@ -77,8 +77,8 @@ With the required cloud resources set up, continue with initializing your cluste constellation apply --skip-phases=infrastructure ``` - - + + Finally, configure `kubectl` for your cluster: diff --git a/docs/versioned_docs/version-2.16/workflows/recovery.md b/docs/versioned_docs/version-2.16/workflows/recovery.md index aea370e2f..50cd7ee72 100644 --- a/docs/versioned_docs/version-2.16/workflows/recovery.md +++ b/docs/versioned_docs/version-2.16/workflows/recovery.md @@ -16,8 +16,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via serial console output. In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + First, open the AWS console to view all Auto Scaling Groups (ASGs) in the region of your cluster. Select the ASG of the control plane `--control-plane` and check that enough members are in a *Running* state. @@ -47,8 +47,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -82,8 +82,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -118,8 +118,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, open the STACKIT portal to view all servers in your project. Select individual control plane nodes `--control-plane--` and check that enough members are in a *Running* state. @@ -149,8 +149,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + ## Recover a cluster diff --git a/docs/versioned_docs/version-2.16/workflows/scale.md b/docs/versioned_docs/version-2.16/workflows/scale.md index 0b52b9540..28f19e3f1 100644 --- a/docs/versioned_docs/version-2.16/workflows/scale.md +++ b/docs/versioned_docs/version-2.16/workflows/scale.md @@ -51,36 +51,36 @@ kubectl -n kube-system get nodes Alternatively, you can manually scale your cluster up or down: - - + + 1. Go to Auto Scaling Groups and select the worker ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + Dynamic cluster scaling isn't yet supported for STACKIT. Support will be introduced in one of the upcoming releases. - - + + ## Control-plane node scaling @@ -88,35 +88,35 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - - + + 1. Go to Auto Scaling Groups and select the control-plane ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + Dynamic cluster scaling isn't yet supported for STACKIT. Support will be introduced in one of the upcoming releases. - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/versioned_docs/version-2.16/workflows/storage.md b/docs/versioned_docs/version-2.16/workflows/storage.md index f1344d6ad..a5c52be90 100644 --- a/docs/versioned_docs/version-2.16/workflows/storage.md +++ b/docs/versioned_docs/version-2.16/workflows/storage.md @@ -21,37 +21,37 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for AWS Elastic Block Store** Mount [Elastic Block Store](https://aws.amazon.com/ebs/) storage volumes into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-aws-ebs-csi-driver) for more information. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as `ReadWriteOnce`, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for more information. - - + + **Constellation CSI driver for STACKIT / OpenStack Cinder** Mount [Cinder](https://docs.openstack.org/cinder/latest/) block storage volumes into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-cloud-provider-openstack) for more information. - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [AWS EFS](https://docs.aws.amazon.com/en_en/eks/latest/userguide/efs-csi.html), [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction), or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -60,8 +60,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The Constellation CLI automatically installs Constellation's CSI driver for the selected CSP in your cluster. If you don't need a CSI driver or wish to deploy your own, you can disable the automatic installation by setting `deployCSIDriver` to `false` in your Constellation config file. - - + + AWS comes with two storage classes by default. @@ -89,8 +89,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + Azure comes with two storage classes by default. @@ -118,8 +118,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + GCP comes with two storage classes by default. @@ -147,8 +147,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + STACKIT comes with two storage classes by default. @@ -176,8 +176,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + 1. Create a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) diff --git a/docs/versioned_docs/version-2.16/workflows/terminate.md b/docs/versioned_docs/version-2.16/workflows/terminate.md index 11bbbb2ac..2c45bebe3 100644 --- a/docs/versioned_docs/version-2.16/workflows/terminate.md +++ b/docs/versioned_docs/version-2.16/workflows/terminate.md @@ -16,8 +16,8 @@ All ephemeral storage and state of your cluster will be lost. Make sure any data ::: - - + + Terminate the cluster by running: ```bash @@ -40,8 +40,8 @@ resources manually. Just run the `terminate` command again afterward to continue ::: - - + + Terminate the cluster by running: ```bash @@ -56,5 +56,5 @@ rm constellation-state.yaml constellation-admin.conf Only the `constellation-mastersecret.json` and the configuration file remain. - - + + diff --git a/docs/versioned_docs/version-2.16/workflows/terraform-provider.md b/docs/versioned_docs/version-2.16/workflows/terraform-provider.md index 8a3cedc62..ed8f46eda 100644 --- a/docs/versioned_docs/version-2.16/workflows/terraform-provider.md +++ b/docs/versioned_docs/version-2.16/workflows/terraform-provider.md @@ -21,8 +21,9 @@ This example shows how to set up a Constellation cluster with the reference IAM 2. Use one of the [example configurations for using the Constellation Terraform provider](https://github.com/edgelesssys/constellation/tree/main/terraform-provider-constellation/examples/full) or create a `main.tf` file and fill it with the resources you want to create. The [Constellation Terraform provider documentation](https://registry.terraform.io/providers/edgelesssys/constellation/latest) offers thorough documentation on the resources and their attributes. 3. Initialize and apply the Terraform configuration. - - + + + Initialize the providers and apply the configuration. ```bash @@ -31,8 +32,8 @@ This example shows how to set up a Constellation cluster with the reference IAM ``` Optionally, you can prefix the `terraform apply` command with `TF_LOG=INFO` to collect [Terraform logs](https://developer.hashicorp.com/terraform/internals/debugging) while applying the configuration. This may provide helpful output in debugging scenarios. - - + + When creating a cluster on Azure, you need to manually patch the policy of the MAA provider before creating the Constellation cluster, as this feature isn't available in Azure's Terraform provider yet. The Constellation CLI provides a utility for patching, but you can also do it manually. @@ -66,8 +67,8 @@ This example shows how to set up a Constellation cluster with the reference IAM }; ``` - - + + Initialize the providers and apply the configuration. ```bash @@ -76,8 +77,8 @@ This example shows how to set up a Constellation cluster with the reference IAM ``` Optionally, you can prefix the `terraform apply` command with `TF_LOG=INFO` to collect [Terraform logs](https://developer.hashicorp.com/terraform/internals/debugging) while applying the configuration. This may provide helpful output in debugging scenarios. - - + + Initialize the providers and apply the configuration. ```bash @@ -86,9 +87,9 @@ This example shows how to set up a Constellation cluster with the reference IAM ``` Optionally, you can prefix the `terraform apply` command with `TF_LOG=INFO` to collect [Terraform logs](https://developer.hashicorp.com/terraform/internals/debugging) while applying the configuration. This may provide helpful output in debugging scenarios. - + - + 4. Connect to the cluster. ```bash diff --git a/docs/versioned_docs/version-2.17/architecture/attestation.md b/docs/versioned_docs/version-2.17/architecture/attestation.md index 7dbfc9392..a07b35e5a 100644 --- a/docs/versioned_docs/version-2.17/architecture/attestation.md +++ b/docs/versioned_docs/version-2.17/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements. @@ -153,8 +153,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -184,8 +184,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -217,8 +217,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses a hypervisor-based vTPM for runtime measurements. @@ -249,16 +249,16 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + ### CVM verification To verify the integrity of the received attestation statement, a chain of trust from the CVM technology to the interface providing the statement has to be established. For verification of the CVM technology, Constellation may expose additional options in its config file. - - + + On AWS, AMD SEV-SNP is used to provide runtime encryption to the VMs. An SEV-SNP attestation report is used to establish trust in the VM. @@ -279,8 +279,8 @@ You may customize certain parameters for verification of the attestation stateme This is the intermediate certificate for verifying the SEV-SNP report's signature. If it's not specified, the CLI fetches it from the AMD key distribution server. - - + + On Azure, AMD SEV-SNP is used to provide runtime encryption to the VMs. An SEV-SNP attestation report is used to establish trust in the vTPM running inside the VM. @@ -302,22 +302,22 @@ You may customize certain parameters for verification of the attestation stateme More explicitly, it controls the verification of the `IDKeyDigest` value in the SEV-SNP attestation report. You can provide a list of accepted key digests and specify a policy on how this list is compared against the reported `IDKeyDigest`. - - + + On GCP, AMD SEV-ES is used to provide runtime encryption to the VMs. The hypervisor-based vTPM is used to establish trust in the VM via [runtime measurements](#runtime-measurements). There is no additional configuration available for GCP. - - + + On STACKIT, AMD SEV-ES is used to provide runtime encryption to the VMs. The hypervisor-based vTPM is used to establish trust in the VM via [runtime measurements](#runtime-measurements). There is no additional configuration available for STACKIT. - - + + ## Cluster attestation diff --git a/docs/versioned_docs/version-2.17/getting-started/first-steps-local.md b/docs/versioned_docs/version-2.17/getting-started/first-steps-local.md index 052d29eae..98f0302de 100644 --- a/docs/versioned_docs/version-2.17/getting-started/first-steps-local.md +++ b/docs/versioned_docs/version-2.17/getting-started/first-steps-local.md @@ -45,8 +45,8 @@ sudo iptables -P FORWARD ACCEPT ## Create a cluster - - + + 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/). @@ -74,8 +74,8 @@ 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. - - + + 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. @@ -145,8 +145,8 @@ attaching persistent storage, or autoscaling aren't available. export KUBECONFIG="$PWD/constellation-admin.conf" ``` - - + + ## Connect to the cluster @@ -199,8 +199,8 @@ worker-0 Ready 32s v1.24.6 ## Terminate your cluster - - + + Once you are done, you can clean up the created resources using the following command: @@ -211,8 +211,8 @@ 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. - - + + Once you are done, you can clean up the created resources using the following command: @@ -240,8 +240,8 @@ 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. - - + + ## Troubleshooting diff --git a/docs/versioned_docs/version-2.17/getting-started/first-steps.md b/docs/versioned_docs/version-2.17/getting-started/first-steps.md index 8c1da1967..9b37efa64 100644 --- a/docs/versioned_docs/version-2.17/getting-started/first-steps.md +++ b/docs/versioned_docs/version-2.17/getting-started/first-steps.md @@ -15,41 +15,41 @@ If you encounter any problem with the following steps, make sure to use the [lat 1. Create the [configuration file](../workflows/config.md) and state file for your cloud provider. If you are following the steps of this guide, there is no need to edit the file. - - + + ```bash constellation config generate aws ``` - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate stackit ``` - - + + 2. Create your [IAM configuration](../workflows/config.md#creating-an-iam-configuration). - - + + ```bash constellation iam create aws --zone=us-east-2a --prefix=constellTest --update-config @@ -76,8 +76,8 @@ If you encounter any problem with the following steps, make sure to use the [lat You can find a list of all [regions in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). - - + + ```bash constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest --update-config @@ -98,8 +98,8 @@ If you encounter any problem with the following steps, make sure to use the [lat You can find a list of all [regions in Azure's documentation](https://azure.microsoft.com/en-us/global-infrastructure/services/?products=virtual-machines®ions=all). - - + + ```bash constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west2-a --serviceAccountID=constell-test --update-config @@ -109,16 +109,16 @@ If you encounter any problem with the following steps, make sure to use the [lat Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available), which you can filter by machine type `C2D` or `N2D`. - - + + To use Constellation on STACKIT, the cluster will use the User Access Token (UAT) that's generated [during the install step](./install.md). After creating the accounts, fill in the STACKIT details in `constellation-conf.yaml` under `provider.openstack`: * `stackitProjectID`: STACKIT project id (can be found after login on the [STACKIT portal](https://portal.stackit.cloud)) - - + + :::tip To learn about all options you have for managing IAM resources and Constellation configuration, see the [Configuration workflow](../workflows/config.md). diff --git a/docs/versioned_docs/version-2.17/getting-started/install.md b/docs/versioned_docs/version-2.17/getting-started/install.md index 4ebd9351a..d52e43476 100644 --- a/docs/versioned_docs/version-2.17/getting-started/install.md +++ b/docs/versioned_docs/version-2.17/getting-started/install.md @@ -22,8 +22,8 @@ If you prefer to use Terraform, you can alternatively use the [Terraform provide The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -39,8 +39,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -56,9 +56,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -74,9 +74,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -92,9 +92,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -115,8 +115,8 @@ Invoke-WebRequest -OutFile ./constellation.exe -Uri 'https://github.com/edgeless 5. Click `New` 6. Enter the path to the folder containing the binary you want on your PATH: `C:\Program Files\Constellation\bin` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -132,8 +132,8 @@ If you don't have a cloud subscription, you can also set up a [local Constellati ### Required permissions - - + + To set up a Constellation cluster, you need to perform two tasks that require permissions: create the infrastructure and create roles for cluster nodes. Both of these actions can be performed by different users, e.g., an administrator to create roles and a DevOps engineer to create the infrastructure. @@ -183,8 +183,8 @@ The built-in `PowerUserAccess` policy is a superset of these permissions. Follow Amazon's guide on [understanding](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [managing policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html). - - + + The following [resource providers need to be registered](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) in your subscription: @@ -226,8 +226,8 @@ Follow Microsoft's guide on [understanding](https://learn.microsoft.com/en-us/az 1: You can omit `*/register/Action` if the resource providers mentioned above are already registered and the `ARM_SKIP_PROVIDER_REGISTRATION` environment variable is set to `true` when creating the IAM configuration. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. @@ -312,16 +312,16 @@ Together, the built-in roles `roles/editor`, `roles/compute.instanceAdmin` and ` Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + Constellation on STACKIT requires a User Access Token (UAT) for the OpenStack API and a STACKIT service account. The UAT already has all required permissions by default. The STACKIT service account needs the `editor` role to create STACKIT LoadBalancers. Look at the [STACKIT documentation](https://docs.stackit.cloud/stackit/en/getting-started-in-service-accounts-134415831.html) on how to create the service account and assign the role. - - + + ### Authentication @@ -331,8 +331,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -348,8 +348,8 @@ aws configure Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - - + + **Testing** @@ -365,8 +365,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -389,8 +389,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + You need to authenticate with the infrastructure API (OpenStack) and create a service account (STACKIT API). @@ -420,9 +420,9 @@ You need to authenticate with the infrastructure API (OpenStack) and create a se {"STACKIT_SERVICE_ACCOUNT_TOKEN":"REPLACE_WITH_TOKEN"} ``` - + - + ## Next steps diff --git a/docs/versioned_docs/version-2.17/getting-started/marketplaces.md b/docs/versioned_docs/version-2.17/getting-started/marketplaces.md index b16d796d2..a6763a42a 100644 --- a/docs/versioned_docs/version-2.17/getting-started/marketplaces.md +++ b/docs/versioned_docs/version-2.17/getting-started/marketplaces.md @@ -4,8 +4,8 @@ Constellation is available through the Marketplaces of AWS, Azure, GCP, and STAC This document explains how to run Constellation with the dynamically billed cloud marketplace images. - - + + To use Constellation's marketplace images, ensure that you are subscribed to the [marketplace offering](https://aws.amazon.com/marketplace/pp/prodview-2mbn65nv57oys) through the web portal. @@ -15,8 +15,8 @@ Then, enable the use of marketplace images in your Constellation `constellation- yq eval -i ".provider.aws.useMarketplaceImage = true" constellation-conf.yaml ``` - - + + Constellation has a private marketplace plan. Please [contact us](https://www.edgeless.systems/enterprise-support/) to gain access. @@ -32,8 +32,8 @@ Then, enable the use of marketplace images in your Constellation `constellation- yq eval -i ".provider.azure.useMarketplaceImage = true" constellation-conf.yaml ``` - - + + To use a marketplace image, ensure that the account is entitled to use marketplace images by Edgeless Systems by accepting the terms through the [web portal](https://console.cloud.google.com/marketplace/vm/config/edgeless-systems-public/constellation). @@ -43,13 +43,13 @@ Then, enable the use of marketplace images in your Constellation `constellation- yq eval -i ".provider.gcp.useMarketplaceImage = true" constellation-conf.yaml ``` - - + + On STACKIT, the selected Constellation image is always a marketplace image. You can find more information on the STACKIT portal. - - + + Ensure that the cluster uses an official release image version (i.e., `.image=vX.Y.Z` in the `constellation-conf.yaml` file). diff --git a/docs/versioned_docs/version-2.17/workflows/config.md b/docs/versioned_docs/version-2.17/workflows/config.md index 9da4305de..120bf8ed7 100644 --- a/docs/versioned_docs/version-2.17/workflows/config.md +++ b/docs/versioned_docs/version-2.17/workflows/config.md @@ -14,44 +14,44 @@ Before you can create your cluster, you need to configure the identity and acces You can generate a configuration file for your CSP by using the following CLI command: - - + + ```bash constellation config generate aws ``` - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate stackit ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. ## Choosing a VM type Constellation supports the following VM types: - - + + By default, Constellation uses `m6a.xlarge` 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. @@ -62,20 +62,20 @@ If you are using the attestation variant `awsNitroTPM`, you can choose any of th The Constellation CLI can also print the supported instance types with: `constellation config instance-types`. - - + + 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. You can also run `constellation config instance-types` to get the list of all supported options. - - + + 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 with a minimum of 4 vCPUs from the [C2D](https://cloud.google.com/compute/docs/compute-optimized-machines#c2d_machine_types) or [N2D](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) family. You can run `constellation config instance-types` to get the list of all supported options. - - + + By default, Constellation uses `m1a.4cd` VMs (4 vCPUs, 30 GB RAM) to create your cluster. Optionally, you can switch to a different VM type by modifying `instanceType` in the configuration file. @@ -93,8 +93,8 @@ You can choose any of the SEV-enabled instance types. You can find a list of all The Constellation CLI can also print the supported instance types with: `constellation config instance-types`. - - + + Fill the desired VM type into the `instanceType` fields in the `constellation-conf.yml` file. @@ -153,8 +153,8 @@ See also Constellation's [Kubernetes support policy](../architecture/versions.md You can create an IAM configuration for your cluster automatically using the `constellation iam create` command. If you already have a Constellation configuration file, you can add the `--update-config` flag to the command. This writes the needed IAM fields into your configuration. Furthermore, the flag updates the zone/region of the configuration if it hasn't been set yet. - - + + You must be authenticated with the [AWS CLI](https://aws.amazon.com/en/cli/) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -178,8 +178,8 @@ You can find a list of all [regions in AWS's documentation](https://docs.aws.ama Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -204,8 +204,8 @@ You can find a list of all [regions in Azure's documentation](https://azure.micr Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [GCP CLI](https://cloud.google.com/sdk/gcloud) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -219,21 +219,21 @@ Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + STACKIT requires manual creation and configuration of service accounts. Look at the [first steps](../getting-started/first-steps.md) for more information. - - + +
Alternatively, you can manually create the IAM configuration on your CSP. The following describes the configuration fields and how you obtain the required information or create the required resources. - - + + * **region**: The name of your chosen AWS data center region, e.g., `us-east-2`. @@ -264,8 +264,8 @@ The following describes the configuration fields and how you obtain the required Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.worker_node_policy`. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -301,8 +301,8 @@ The following describes the configuration fields and how you obtain the required The user-assigned identity is used by instances of the cluster to access other cloud resources. For more information about managed identities refer to [Azure's documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities). - - + + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -326,13 +326,13 @@ The following describes the configuration fields and how you obtain the required Afterward, create and download a new JSON key for this service account. Place the downloaded file in your Constellation workspace, and set the config parameter to the filename, e.g., `constellation-129857-15343dba46cb.json`. - - + + STACKIT requires manual creation and configuration of service accounts. Look at the [first steps](../getting-started/first-steps.md) for more information. - - + +
Now that you've configured your CSP, you can [create your cluster](./create.md). diff --git a/docs/versioned_docs/version-2.17/workflows/create.md b/docs/versioned_docs/version-2.17/workflows/create.md index 388cbedf8..6074ebb16 100644 --- a/docs/versioned_docs/version-2.17/workflows/create.md +++ b/docs/versioned_docs/version-2.17/workflows/create.md @@ -27,8 +27,8 @@ If you don't have a cloud subscription, you can also set up a [local Constellati Before you create the cluster, make sure to have a [valid configuration file](./config.md). - - + + ```bash constellation apply @@ -36,8 +36,8 @@ constellation apply `apply` stores the state of your cluster's cloud resources in a [`constellation-terraform`](../architecture/orchestration.md#cluster-creation-process) directory in your workspace. - - + + Self-managed infrastructure allows for more flexibility in the setup, by separating the infrastructure setup from the Constellation cluster management. This provides flexibility in DevOps and can meet potential regulatory requirements. @@ -77,8 +77,8 @@ With the required cloud resources set up, continue with initializing your cluste constellation apply --skip-phases=infrastructure ``` - - + + Finally, configure `kubectl` for your cluster: diff --git a/docs/versioned_docs/version-2.17/workflows/recovery.md b/docs/versioned_docs/version-2.17/workflows/recovery.md index aea370e2f..50cd7ee72 100644 --- a/docs/versioned_docs/version-2.17/workflows/recovery.md +++ b/docs/versioned_docs/version-2.17/workflows/recovery.md @@ -16,8 +16,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via serial console output. In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + First, open the AWS console to view all Auto Scaling Groups (ASGs) in the region of your cluster. Select the ASG of the control plane `--control-plane` and check that enough members are in a *Running* state. @@ -47,8 +47,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -82,8 +82,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -118,8 +118,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, open the STACKIT portal to view all servers in your project. Select individual control plane nodes `--control-plane--` and check that enough members are in a *Running* state. @@ -149,8 +149,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + ## Recover a cluster diff --git a/docs/versioned_docs/version-2.17/workflows/scale.md b/docs/versioned_docs/version-2.17/workflows/scale.md index 0b52b9540..28f19e3f1 100644 --- a/docs/versioned_docs/version-2.17/workflows/scale.md +++ b/docs/versioned_docs/version-2.17/workflows/scale.md @@ -51,36 +51,36 @@ kubectl -n kube-system get nodes Alternatively, you can manually scale your cluster up or down: - - + + 1. Go to Auto Scaling Groups and select the worker ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + Dynamic cluster scaling isn't yet supported for STACKIT. Support will be introduced in one of the upcoming releases. - - + + ## Control-plane node scaling @@ -88,35 +88,35 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - - + + 1. Go to Auto Scaling Groups and select the control-plane ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + Dynamic cluster scaling isn't yet supported for STACKIT. Support will be introduced in one of the upcoming releases. - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/versioned_docs/version-2.17/workflows/storage.md b/docs/versioned_docs/version-2.17/workflows/storage.md index f1344d6ad..a5c52be90 100644 --- a/docs/versioned_docs/version-2.17/workflows/storage.md +++ b/docs/versioned_docs/version-2.17/workflows/storage.md @@ -21,37 +21,37 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for AWS Elastic Block Store** Mount [Elastic Block Store](https://aws.amazon.com/ebs/) storage volumes into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-aws-ebs-csi-driver) for more information. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as `ReadWriteOnce`, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for more information. - - + + **Constellation CSI driver for STACKIT / OpenStack Cinder** Mount [Cinder](https://docs.openstack.org/cinder/latest/) block storage volumes into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-cloud-provider-openstack) for more information. - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [AWS EFS](https://docs.aws.amazon.com/en_en/eks/latest/userguide/efs-csi.html), [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction), or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -60,8 +60,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The Constellation CLI automatically installs Constellation's CSI driver for the selected CSP in your cluster. If you don't need a CSI driver or wish to deploy your own, you can disable the automatic installation by setting `deployCSIDriver` to `false` in your Constellation config file. - - + + AWS comes with two storage classes by default. @@ -89,8 +89,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + Azure comes with two storage classes by default. @@ -118,8 +118,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + GCP comes with two storage classes by default. @@ -147,8 +147,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + STACKIT comes with two storage classes by default. @@ -176,8 +176,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + 1. Create a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) diff --git a/docs/versioned_docs/version-2.17/workflows/terminate.md b/docs/versioned_docs/version-2.17/workflows/terminate.md index 11bbbb2ac..2c45bebe3 100644 --- a/docs/versioned_docs/version-2.17/workflows/terminate.md +++ b/docs/versioned_docs/version-2.17/workflows/terminate.md @@ -16,8 +16,8 @@ All ephemeral storage and state of your cluster will be lost. Make sure any data ::: - - + + Terminate the cluster by running: ```bash @@ -40,8 +40,8 @@ resources manually. Just run the `terminate` command again afterward to continue ::: - - + + Terminate the cluster by running: ```bash @@ -56,5 +56,5 @@ rm constellation-state.yaml constellation-admin.conf Only the `constellation-mastersecret.json` and the configuration file remain. - - + + diff --git a/docs/versioned_docs/version-2.17/workflows/terraform-provider.md b/docs/versioned_docs/version-2.17/workflows/terraform-provider.md index 8a3cedc62..ed8f46eda 100644 --- a/docs/versioned_docs/version-2.17/workflows/terraform-provider.md +++ b/docs/versioned_docs/version-2.17/workflows/terraform-provider.md @@ -21,8 +21,9 @@ This example shows how to set up a Constellation cluster with the reference IAM 2. Use one of the [example configurations for using the Constellation Terraform provider](https://github.com/edgelesssys/constellation/tree/main/terraform-provider-constellation/examples/full) or create a `main.tf` file and fill it with the resources you want to create. The [Constellation Terraform provider documentation](https://registry.terraform.io/providers/edgelesssys/constellation/latest) offers thorough documentation on the resources and their attributes. 3. Initialize and apply the Terraform configuration. - - + + + Initialize the providers and apply the configuration. ```bash @@ -31,8 +32,8 @@ This example shows how to set up a Constellation cluster with the reference IAM ``` Optionally, you can prefix the `terraform apply` command with `TF_LOG=INFO` to collect [Terraform logs](https://developer.hashicorp.com/terraform/internals/debugging) while applying the configuration. This may provide helpful output in debugging scenarios. - - + + When creating a cluster on Azure, you need to manually patch the policy of the MAA provider before creating the Constellation cluster, as this feature isn't available in Azure's Terraform provider yet. The Constellation CLI provides a utility for patching, but you can also do it manually. @@ -66,8 +67,8 @@ This example shows how to set up a Constellation cluster with the reference IAM }; ``` - - + + Initialize the providers and apply the configuration. ```bash @@ -76,8 +77,8 @@ This example shows how to set up a Constellation cluster with the reference IAM ``` Optionally, you can prefix the `terraform apply` command with `TF_LOG=INFO` to collect [Terraform logs](https://developer.hashicorp.com/terraform/internals/debugging) while applying the configuration. This may provide helpful output in debugging scenarios. - - + + Initialize the providers and apply the configuration. ```bash @@ -86,9 +87,9 @@ This example shows how to set up a Constellation cluster with the reference IAM ``` Optionally, you can prefix the `terraform apply` command with `TF_LOG=INFO` to collect [Terraform logs](https://developer.hashicorp.com/terraform/internals/debugging) while applying the configuration. This may provide helpful output in debugging scenarios. - + - + 4. Connect to the cluster. ```bash diff --git a/docs/versioned_docs/version-2.2/architecture/attestation.md b/docs/versioned_docs/version-2.2/architecture/attestation.md index c70a61264..c09d0f546 100644 --- a/docs/versioned_docs/version-2.2/architecture/attestation.md +++ b/docs/versioned_docs/version-2.2/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -152,8 +152,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -185,8 +185,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements. @@ -217,8 +217,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + ## Cluster attestation diff --git a/docs/versioned_docs/version-2.2/getting-started/first-steps.md b/docs/versioned_docs/version-2.2/getting-started/first-steps.md index 2850176a0..3dcb4f6c5 100644 --- a/docs/versioned_docs/version-2.2/getting-started/first-steps.md +++ b/docs/versioned_docs/version-2.2/getting-started/first-steps.md @@ -11,36 +11,36 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step 1. Create the configuration file for your selected cloud provider. - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate aws ``` - - + + This creates the file `constellation-conf.yaml` in your current working directory. 2. Fill in your cloud provider specific information. - - + + You need several resources for the cluster. You can use the following `az` script to create them: @@ -71,8 +71,8 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step Run `constellation config instance-types` to get the list of all supported options. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -118,8 +118,8 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step Run `constellation config instance-types` to get the list of all supported options. - - + + You need a service account for the cluster. You can use the following `gcloud` script to create it: @@ -142,8 +142,8 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step 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 with a minimum of 4 vCPUs. 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. - - + + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -171,8 +171,8 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step Supported are all machines from the N2D family with a minimum of 4 vCPUs. It defaults to `n2d-standard-4` (4 vCPUs, 16 GB RAM), but you can use any other VMs from the same 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. - - + + * **region**: The name of your chosen AWS data center region, e.g., `us-east-2`. @@ -211,8 +211,8 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.worker_node_policy`. - - + + :::info diff --git a/docs/versioned_docs/version-2.2/getting-started/install.md b/docs/versioned_docs/version-2.2/getting-started/install.md index 6bf421b16..439b734dd 100644 --- a/docs/versioned_docs/version-2.2/getting-started/install.md +++ b/docs/versioned_docs/version-2.2/getting-started/install.md @@ -18,8 +18,8 @@ Make sure the following requirements are met: The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -35,8 +35,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -52,9 +52,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -70,9 +70,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -88,8 +88,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -105,14 +105,15 @@ If you don't have a cloud subscription, you can try [MiniConstellation](first-st ### Required permissions - - + + The following [resource providers need to be need to be registered](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) in your subscription: -* `Microsoft.Compute` -* `Microsoft.ManagedIdentity` -* `Microsoft.Network` -* `microsoft.insights` + +- `Microsoft.Compute` +- `Microsoft.ManagedIdentity` +- `Microsoft.Network` +- `microsoft.insights` By default, Constellation tries to register these automatically if they haven't been registered before. @@ -124,8 +125,8 @@ You need the following permissions for your user account: If you don't have these permissions with scope *subscription*, ask your administrator to [create the service account and a resource group for your Constellation cluster](first-steps.md). Your user account needs the `Contributor` permission scoped to this resource group. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. @@ -137,8 +138,8 @@ You need the following permissions on this project: Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + To set up a Constellation cluster, you need to perform two tasks that require permissions: create the infrastructure and create roles for cluster nodes. Both of these actions can be performed by different users, e.g., an administrator to create roles and a DevOps engineer to create the infrastructure. @@ -269,8 +270,8 @@ such as `PowerUserAccess`, or use the following minimal set of permissions: Follow Amazon's guide on [understanding](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [managing policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html). - - + + ### Authentication @@ -280,8 +281,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -297,8 +298,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -321,8 +322,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + **Testing** @@ -338,9 +339,9 @@ aws configure Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - + - + ## Next steps diff --git a/docs/versioned_docs/version-2.2/workflows/create.md b/docs/versioned_docs/version-2.2/workflows/create.md index d886fb347..dcb3ff285 100644 --- a/docs/versioned_docs/version-2.2/workflows/create.md +++ b/docs/versioned_docs/version-2.2/workflows/create.md @@ -19,29 +19,29 @@ This step creates the necessary resources for your cluster in your cloud environ Generate a configuration file for your cloud service provider (CSP): - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate aws ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. [Fill in your CSP-specific information](../getting-started/first-steps.md#create-a-cluster) before you continue. diff --git a/docs/versioned_docs/version-2.2/workflows/recovery.md b/docs/versioned_docs/version-2.2/workflows/recovery.md index fd610fc67..0fd171036 100644 --- a/docs/versioned_docs/version-2.2/workflows/recovery.md +++ b/docs/versioned_docs/version-2.2/workflows/recovery.md @@ -16,8 +16,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via [cloud logging](troubleshooting.md#cloud-logging). In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -51,8 +51,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -87,8 +87,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, open the AWS console to view all Auto Scaling Groups (ASGs) in the region of your cluster. Select the ASG of the control plane `--control-plane` and check that enough members are in a *Running* state. @@ -118,8 +118,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + ## Recover a cluster diff --git a/docs/versioned_docs/version-2.2/workflows/scale.md b/docs/versioned_docs/version-2.2/workflows/scale.md index 3b7c0d479..bce045c66 100644 --- a/docs/versioned_docs/version-2.2/workflows/scale.md +++ b/docs/versioned_docs/version-2.2/workflows/scale.md @@ -48,23 +48,23 @@ kubectl -n kube-system get nodes Alternatively, you can manually scale your cluster up or down: - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + :::caution @@ -72,8 +72,8 @@ Scaling isn't yet implemented for AWS. If you require this feature, [let us know ::: - - + + ## Control-plane node scaling @@ -81,24 +81,24 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - + - + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + :::caution @@ -106,7 +106,7 @@ Scaling isn't yet implemented for AWS. If you require this feature, [let us know ::: - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/versioned_docs/version-2.2/workflows/storage.md b/docs/versioned_docs/version-2.2/workflows/storage.md index 878449fa5..c322d97d1 100644 --- a/docs/versioned_docs/version-2.2/workflows/storage.md +++ b/docs/versioned_docs/version-2.2/workflows/storage.md @@ -21,14 +21,14 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as ReadWriteOnce, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. @@ -36,8 +36,8 @@ This includes support for [volume snapshots](https://cloud.google.com/kubernetes You can use them to bring a volume back to a prior state or provision new volumes. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for information about the configuration. - - + + :::caution @@ -47,8 +47,8 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction) or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -56,8 +56,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The following installation guide gives an overview of how to securely use CSI-based cloud storage for persistent volumes in Constellation. - - + + 1. Install the driver: @@ -67,8 +67,8 @@ The following installation guide gives an overview of how to securely use CSI-ba helm install azuredisk-csi-driver charts/edgeless --namespace kube-system ``` - - + + 1. Install the driver: @@ -77,8 +77,8 @@ The following installation guide gives an overview of how to securely use CSI-ba helm install gcp-compute-persistent-disk-csi-driver charts/ --namespace kube-system ``` - - + + :::caution @@ -88,8 +88,8 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + :::info @@ -160,8 +160,8 @@ The default storage class is responsible for all persistent volume claims that d The previous instructions create a storage class with encryption enabled and sets this as the default class. In case you wish to change it, follow the steps below: - - + + 1. List the storage classes in your cluster: @@ -207,8 +207,8 @@ In case you wish to change it, follow the steps below: integrity-encrypted-rwo (default) azuredisk.csi.confidential.cloud Delete Immediate false 1d ``` - - + + 1. List the storage classes in your cluster: @@ -254,8 +254,8 @@ In case you wish to change it, follow the steps below: integrity-encrypted-rwo (default) gcp.csi.confidential.cloud Delete Immediate false 1d ``` - - + + :::caution @@ -265,5 +265,5 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + diff --git a/docs/versioned_docs/version-2.2/workflows/troubleshooting.md b/docs/versioned_docs/version-2.2/workflows/troubleshooting.md index ad5e1c51b..59015efcb 100644 --- a/docs/versioned_docs/version-2.2/workflows/troubleshooting.md +++ b/docs/versioned_docs/version-2.2/workflows/troubleshooting.md @@ -5,6 +5,7 @@ This section aids you in finding problems when working with Constellation. ## Azure: Resource Providers can't be registered On Azure, you may receive the following error when running `create` or `terminate` with limited IAM permissions: + ```shell-session Error: Error ensuring Resource Providers are registered. @@ -21,11 +22,13 @@ To continue, please ensure that the [required resource providers](../getting-sta Afterward, set `ARM_SKIP_PROVIDER_REGISTRATION=true` as an environment variable and either run `create` or `terminate` again. For example: + ```bash ARM_SKIP_PROVIDER_REGISTRATION=true constellation create --control-plane-nodes 1 --worker-nodes 2 -y ``` Or alternatively, for `terminate`: + ```bash ARM_SKIP_PROVIDER_REGISTRATION=true constellation terminate ``` @@ -36,8 +39,8 @@ To provide information during early stages of the node's boot process, Constella You can view these information in the follow places: - - + + 1. In your Azure subscription find the Constellation resource group. 2. Inside the resource group find the Application Insights resource called `constellation-insights-*`. @@ -47,8 +50,8 @@ You can view these information in the follow places: To **find the disk UUIDs** use the following query: `traces | where message contains "Disk UUID"` - - + + 1. Select the project that hosts Constellation. 2. Go to the `Compute Engine` service. @@ -63,16 +66,16 @@ Constellation uses the default bucket to store logs. Its [default retention peri ::: - - + + 1. Open [AWS CloudWatch](https://console.aws.amazon.com/cloudwatch/home) 2. Select [Log Groups](https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups) 3. Select the log group that matches the name of your cluster. 4. Select the log stream for control or worker type nodes. - - + + ## Connect to nodes via SSH diff --git a/docs/versioned_docs/version-2.3/architecture/attestation.md b/docs/versioned_docs/version-2.3/architecture/attestation.md index f335038f6..28e8e62cf 100644 --- a/docs/versioned_docs/version-2.3/architecture/attestation.md +++ b/docs/versioned_docs/version-2.3/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -152,8 +152,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -185,8 +185,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements. @@ -217,8 +217,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + ## Cluster attestation diff --git a/docs/versioned_docs/version-2.3/getting-started/first-steps.md b/docs/versioned_docs/version-2.3/getting-started/first-steps.md index a749ca6a9..02fbdb696 100644 --- a/docs/versioned_docs/version-2.3/getting-started/first-steps.md +++ b/docs/versioned_docs/version-2.3/getting-started/first-steps.md @@ -11,29 +11,29 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step 1. Create the configuration file for your selected cloud provider. - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate aws ``` - - + + This creates the file `constellation-conf.yaml` in your current working directory. @@ -41,9 +41,9 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step First you need to create an [IAM configuration](../workflows/config.md#creating-an-iam-configuration). The easiest way to do this is the following CLI command: - + - + ```bash constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest @@ -57,9 +57,9 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step * `northeurope` * `westeurope` - + - + ```bash constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west2-a --serviceAccountID=constell-test @@ -69,9 +69,9 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step Note that only regions offering CVMs of the `N2D` series are supported. You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available), which you can filter by machine type `N2D`. - + - + ```bash constellation iam create aws --zone=eu-central-1a --prefix=constellTest @@ -88,8 +88,8 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step You can find a list of all [regions in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). - - + + Now, fill the output values of the command into the corresponding fields of the `constellation-conf.yaml` file. diff --git a/docs/versioned_docs/version-2.3/getting-started/install.md b/docs/versioned_docs/version-2.3/getting-started/install.md index d830c7792..36d8f541a 100644 --- a/docs/versioned_docs/version-2.3/getting-started/install.md +++ b/docs/versioned_docs/version-2.3/getting-started/install.md @@ -18,8 +18,8 @@ Make sure the following requirements are met: The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -35,8 +35,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -52,9 +52,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -70,9 +70,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -88,8 +88,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -105,14 +105,15 @@ If you don't have a cloud subscription, you can try [MiniConstellation](first-st ### Required permissions - - + + The following [resource providers need to be registered](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) in your subscription: -* `Microsoft.Compute` -* `Microsoft.ManagedIdentity` -* `Microsoft.Network` -* `microsoft.insights` + +- `Microsoft.Compute` +- `Microsoft.ManagedIdentity` +- `Microsoft.Network` +- `microsoft.insights` By default, Constellation tries to register these automatically if they haven't been registered before. @@ -124,8 +125,8 @@ You need the following permissions for your user account: If you don't have these permissions with scope *subscription*, ask your administrator to [create the service account and a resource group for your Constellation cluster](first-steps.md). Your user account needs the `Contributor` permission scoped to this resource group. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. @@ -137,8 +138,8 @@ You need the following permissions on this project: Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + To set up a Constellation cluster, you need to perform two tasks that require permissions: create the infrastructure and create roles for cluster nodes. Both of these actions can be performed by different users, e.g., an administrator to create roles and a DevOps engineer to create the infrastructure. @@ -269,8 +270,8 @@ such as `PowerUserAccess`, or use the following minimal set of permissions: Follow Amazon's guide on [understanding](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [managing policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html). - - + + ### Authentication @@ -280,8 +281,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -297,8 +298,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -321,8 +322,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + **Testing** @@ -338,9 +339,9 @@ aws configure Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - + - + ## Next steps diff --git a/docs/versioned_docs/version-2.3/workflows/config.md b/docs/versioned_docs/version-2.3/workflows/config.md index afd53812e..652e58a38 100644 --- a/docs/versioned_docs/version-2.3/workflows/config.md +++ b/docs/versioned_docs/version-2.3/workflows/config.md @@ -6,62 +6,62 @@ Before you can create your cluster, you need to configure the identity and acces You can generate a configuration file for your CSP by using the following CLI command: - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate aws ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. ## Choosing a VM type Constellation supports the following VM types: - - + + 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. You can also run `constellation config instance-types` to get the list of all supported options. - - + + 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 with a minimum of 4 vCPUs 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. - - + + By default, Constellation uses `m6a.xlarge` 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 nitroTPM-enabled machines with a minimum of 4 vCPUs (`xlarge` or larger). Refer to the [list of nitroTPM-enabled instance types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enable-nitrotpm-prerequisites.html) or run `constellation config instance-types` to get the list of all supported options. - - + + Fill the desired VM type into the **instanceType** field in the `constellation-conf.yml` file. ## Creating an IAM configuration You can create an IAM configuration for your cluster automatically using the `constellation iam create` command. - - + + You must be authenticated with the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) in the shell session. @@ -84,8 +84,8 @@ Paste the output into the corresponding fields of the `constellation-conf.yaml` Since `clientSecretValue` is a sensitive value, you can leave it empty in the configuration file and pass it via an environment variable instead. To this end, create the environment variable `CONSTELL_AZURE_CLIENT_SECRET_VALUE` and set it to the secret value. ::: - - + + You must be authenticated with the [GCP CLI](https://cloud.google.com/sdk/gcloud) in the shell session. @@ -99,8 +99,8 @@ Note that only regions offering CVMs of the `N2D` series are supported. You can Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [AWS CLI](https://aws.amazon.com/en/cli/) in the shell session. @@ -122,16 +122,16 @@ You can find a list of all [regions in AWS's documentation](https://docs.aws.ama Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + +
Alternatively, you can manually create the IAM configuration on your CSP. The following describes the configuration fields and how you obtain the required information or create the required resources. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -175,9 +175,9 @@ The following describes the configuration fields and how you obtain the required Since this is a sensitive value, alternatively you can leave `clientSecretValue` empty in the configuration file and pass it via an environment variable instead. To this end, create the environment variable `CONSTELL_AZURE_CLIENT_SECRET_VALUE` and set it to the secret value. ::: - + - + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -201,9 +201,9 @@ The following describes the configuration fields and how you obtain the required Afterward, create and download a new JSON key for this service account. Place the downloaded file in your Constellation workspace, and set the config parameter to the filename, e.g., `constellation-129857-15343dba46cb.json`. - + - + * **region**: The name of your chosen AWS data center region, e.g., `us-east-2`. @@ -232,9 +232,9 @@ The following describes the configuration fields and how you obtain the required Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.worker_node_policy`. - + - +
Now that you've configured your CSP, you can [create your cluster](./create.md). diff --git a/docs/versioned_docs/version-2.3/workflows/recovery.md b/docs/versioned_docs/version-2.3/workflows/recovery.md index fd610fc67..0fd171036 100644 --- a/docs/versioned_docs/version-2.3/workflows/recovery.md +++ b/docs/versioned_docs/version-2.3/workflows/recovery.md @@ -16,8 +16,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via [cloud logging](troubleshooting.md#cloud-logging). In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -51,8 +51,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -87,8 +87,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, open the AWS console to view all Auto Scaling Groups (ASGs) in the region of your cluster. Select the ASG of the control plane `--control-plane` and check that enough members are in a *Running* state. @@ -118,8 +118,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + ## Recover a cluster diff --git a/docs/versioned_docs/version-2.3/workflows/scale.md b/docs/versioned_docs/version-2.3/workflows/scale.md index 3b7c0d479..bce045c66 100644 --- a/docs/versioned_docs/version-2.3/workflows/scale.md +++ b/docs/versioned_docs/version-2.3/workflows/scale.md @@ -48,23 +48,23 @@ kubectl -n kube-system get nodes Alternatively, you can manually scale your cluster up or down: - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + :::caution @@ -72,8 +72,8 @@ Scaling isn't yet implemented for AWS. If you require this feature, [let us know ::: - - + + ## Control-plane node scaling @@ -81,24 +81,24 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - + - + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + :::caution @@ -106,7 +106,7 @@ Scaling isn't yet implemented for AWS. If you require this feature, [let us know ::: - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/versioned_docs/version-2.3/workflows/storage.md b/docs/versioned_docs/version-2.3/workflows/storage.md index d0e5b188f..be9998676 100644 --- a/docs/versioned_docs/version-2.3/workflows/storage.md +++ b/docs/versioned_docs/version-2.3/workflows/storage.md @@ -21,14 +21,14 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as ReadWriteOnce, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. @@ -36,8 +36,8 @@ This includes support for [volume snapshots](https://cloud.google.com/kubernetes You can use them to bring a volume back to a prior state or provision new volumes. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for information about the configuration. - - + + :::caution @@ -47,8 +47,8 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction) or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -57,8 +57,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The Constellation CLI automatically installs Constellation's CSI driver for the selected CSP in your cluster. If you don't need a CSI driver or wish to deploy your own, you can disable the automatic installation by setting `deployCSIDriver` to `false` in your Constellation config file. - - + + Azure comes with two storage classes by default. @@ -86,8 +86,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + GCP comes with two storage classes by default. @@ -115,8 +115,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + :::caution @@ -126,8 +126,8 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + 1. Create a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) @@ -186,8 +186,8 @@ The default storage class is responsible for all persistent volume claims that d Constellation creates a storage class with encryption enabled and sets this as the default class. In case you wish to change it, follow the steps below: - - + + 1. List the storage classes in your cluster: @@ -233,8 +233,8 @@ In case you wish to change it, follow the steps below: integrity-encrypted-rwo (default) azuredisk.csi.confidential.cloud Delete Immediate false 1d ``` - - + + 1. List the storage classes in your cluster: @@ -280,8 +280,8 @@ In case you wish to change it, follow the steps below: integrity-encrypted-rwo (default) gcp.csi.confidential.cloud Delete Immediate false 1d ``` - - + + :::caution @@ -291,5 +291,5 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + diff --git a/docs/versioned_docs/version-2.3/workflows/troubleshooting.md b/docs/versioned_docs/version-2.3/workflows/troubleshooting.md index 3a28c9cd0..f948f5d06 100644 --- a/docs/versioned_docs/version-2.3/workflows/troubleshooting.md +++ b/docs/versioned_docs/version-2.3/workflows/troubleshooting.md @@ -5,6 +5,7 @@ This section aids you in finding problems when working with Constellation. ## Azure: Resource Providers can't be registered On Azure, you may receive the following error when running `create` or `terminate` with limited IAM permissions: + ```shell-session Error: Error ensuring Resource Providers are registered. @@ -21,11 +22,13 @@ To continue, please ensure that the [required resource providers](../getting-sta Afterward, set `ARM_SKIP_PROVIDER_REGISTRATION=true` as an environment variable and either run `create` or `terminate` again. For example: + ```bash ARM_SKIP_PROVIDER_REGISTRATION=true constellation create --control-plane-nodes 1 --worker-nodes 2 -y ``` Or alternatively, for `terminate`: + ```bash ARM_SKIP_PROVIDER_REGISTRATION=true constellation terminate ``` @@ -36,8 +39,8 @@ To provide information during early stages of the node's boot process, Constella You can view these information in the follow places: - - + + 1. In your Azure subscription find the Constellation resource group. 2. Inside the resource group find the Application Insights resource called `constellation-insights-*`. @@ -47,8 +50,8 @@ You can view these information in the follow places: To **find the disk UUIDs** use the following query: `traces | where message contains "Disk UUID"` - - + + 1. Select the project that hosts Constellation. 2. Go to the `Compute Engine` service. @@ -63,16 +66,16 @@ Constellation uses the default bucket to store logs. Its [default retention peri ::: - - + + 1. Open [AWS CloudWatch](https://console.aws.amazon.com/cloudwatch/home) 2. Select [Log Groups](https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups) 3. Select the log group that matches the name of your cluster. 4. Select the log stream for control or worker type nodes. - - + + ## Connect to nodes diff --git a/docs/versioned_docs/version-2.4/architecture/attestation.md b/docs/versioned_docs/version-2.4/architecture/attestation.md index f335038f6..28e8e62cf 100644 --- a/docs/versioned_docs/version-2.4/architecture/attestation.md +++ b/docs/versioned_docs/version-2.4/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -152,8 +152,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -185,8 +185,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements. @@ -217,8 +217,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + ## Cluster attestation diff --git a/docs/versioned_docs/version-2.4/getting-started/first-steps.md b/docs/versioned_docs/version-2.4/getting-started/first-steps.md index 768e8dfcd..d277b9e09 100644 --- a/docs/versioned_docs/version-2.4/getting-started/first-steps.md +++ b/docs/versioned_docs/version-2.4/getting-started/first-steps.md @@ -11,29 +11,29 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step 1. Create the configuration file for your selected cloud provider. - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate aws ``` - - + + This creates the file `constellation-conf.yaml` in your current working directory. @@ -41,9 +41,9 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step First you need to create an [IAM configuration](../workflows/config.md#creating-an-iam-configuration). The easiest way to do this is the following CLI command: - + - + ```bash constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest @@ -57,9 +57,9 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step * `northeurope` * `westeurope` - + - + ```bash constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west2-a --serviceAccountID=constell-test @@ -69,9 +69,9 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step Note that only regions offering CVMs of the `N2D` series are supported. You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available), which you can filter by machine type `N2D`. - + - + ```bash constellation iam create aws --zone=eu-central-1a --prefix=constellTest @@ -88,8 +88,8 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step You can find a list of all [regions in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). - - + + Now, fill the output values of the command into the corresponding fields of the `constellation-conf.yaml` file. diff --git a/docs/versioned_docs/version-2.4/getting-started/install.md b/docs/versioned_docs/version-2.4/getting-started/install.md index d830c7792..36d8f541a 100644 --- a/docs/versioned_docs/version-2.4/getting-started/install.md +++ b/docs/versioned_docs/version-2.4/getting-started/install.md @@ -18,8 +18,8 @@ Make sure the following requirements are met: The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -35,8 +35,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -52,9 +52,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -70,9 +70,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -88,8 +88,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -105,14 +105,15 @@ If you don't have a cloud subscription, you can try [MiniConstellation](first-st ### Required permissions - - + + The following [resource providers need to be registered](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) in your subscription: -* `Microsoft.Compute` -* `Microsoft.ManagedIdentity` -* `Microsoft.Network` -* `microsoft.insights` + +- `Microsoft.Compute` +- `Microsoft.ManagedIdentity` +- `Microsoft.Network` +- `microsoft.insights` By default, Constellation tries to register these automatically if they haven't been registered before. @@ -124,8 +125,8 @@ You need the following permissions for your user account: If you don't have these permissions with scope *subscription*, ask your administrator to [create the service account and a resource group for your Constellation cluster](first-steps.md). Your user account needs the `Contributor` permission scoped to this resource group. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. @@ -137,8 +138,8 @@ You need the following permissions on this project: Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + To set up a Constellation cluster, you need to perform two tasks that require permissions: create the infrastructure and create roles for cluster nodes. Both of these actions can be performed by different users, e.g., an administrator to create roles and a DevOps engineer to create the infrastructure. @@ -269,8 +270,8 @@ such as `PowerUserAccess`, or use the following minimal set of permissions: Follow Amazon's guide on [understanding](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [managing policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html). - - + + ### Authentication @@ -280,8 +281,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -297,8 +298,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -321,8 +322,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + **Testing** @@ -338,9 +339,9 @@ aws configure Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - + - + ## Next steps diff --git a/docs/versioned_docs/version-2.4/workflows/config.md b/docs/versioned_docs/version-2.4/workflows/config.md index afd53812e..652e58a38 100644 --- a/docs/versioned_docs/version-2.4/workflows/config.md +++ b/docs/versioned_docs/version-2.4/workflows/config.md @@ -6,62 +6,62 @@ Before you can create your cluster, you need to configure the identity and acces You can generate a configuration file for your CSP by using the following CLI command: - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate aws ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. ## Choosing a VM type Constellation supports the following VM types: - - + + 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. You can also run `constellation config instance-types` to get the list of all supported options. - - + + 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 with a minimum of 4 vCPUs 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. - - + + By default, Constellation uses `m6a.xlarge` 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 nitroTPM-enabled machines with a minimum of 4 vCPUs (`xlarge` or larger). Refer to the [list of nitroTPM-enabled instance types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enable-nitrotpm-prerequisites.html) or run `constellation config instance-types` to get the list of all supported options. - - + + Fill the desired VM type into the **instanceType** field in the `constellation-conf.yml` file. ## Creating an IAM configuration You can create an IAM configuration for your cluster automatically using the `constellation iam create` command. - - + + You must be authenticated with the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) in the shell session. @@ -84,8 +84,8 @@ Paste the output into the corresponding fields of the `constellation-conf.yaml` Since `clientSecretValue` is a sensitive value, you can leave it empty in the configuration file and pass it via an environment variable instead. To this end, create the environment variable `CONSTELL_AZURE_CLIENT_SECRET_VALUE` and set it to the secret value. ::: - - + + You must be authenticated with the [GCP CLI](https://cloud.google.com/sdk/gcloud) in the shell session. @@ -99,8 +99,8 @@ Note that only regions offering CVMs of the `N2D` series are supported. You can Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [AWS CLI](https://aws.amazon.com/en/cli/) in the shell session. @@ -122,16 +122,16 @@ You can find a list of all [regions in AWS's documentation](https://docs.aws.ama Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + +
Alternatively, you can manually create the IAM configuration on your CSP. The following describes the configuration fields and how you obtain the required information or create the required resources. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -175,9 +175,9 @@ The following describes the configuration fields and how you obtain the required Since this is a sensitive value, alternatively you can leave `clientSecretValue` empty in the configuration file and pass it via an environment variable instead. To this end, create the environment variable `CONSTELL_AZURE_CLIENT_SECRET_VALUE` and set it to the secret value. ::: - + - + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -201,9 +201,9 @@ The following describes the configuration fields and how you obtain the required Afterward, create and download a new JSON key for this service account. Place the downloaded file in your Constellation workspace, and set the config parameter to the filename, e.g., `constellation-129857-15343dba46cb.json`. - + - + * **region**: The name of your chosen AWS data center region, e.g., `us-east-2`. @@ -232,9 +232,9 @@ The following describes the configuration fields and how you obtain the required Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.worker_node_policy`. - + - +
Now that you've configured your CSP, you can [create your cluster](./create.md). diff --git a/docs/versioned_docs/version-2.4/workflows/recovery.md b/docs/versioned_docs/version-2.4/workflows/recovery.md index fd610fc67..0fd171036 100644 --- a/docs/versioned_docs/version-2.4/workflows/recovery.md +++ b/docs/versioned_docs/version-2.4/workflows/recovery.md @@ -16,8 +16,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via [cloud logging](troubleshooting.md#cloud-logging). In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -51,8 +51,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -87,8 +87,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, open the AWS console to view all Auto Scaling Groups (ASGs) in the region of your cluster. Select the ASG of the control plane `--control-plane` and check that enough members are in a *Running* state. @@ -118,8 +118,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + ## Recover a cluster diff --git a/docs/versioned_docs/version-2.4/workflows/scale.md b/docs/versioned_docs/version-2.4/workflows/scale.md index 3b7c0d479..bce045c66 100644 --- a/docs/versioned_docs/version-2.4/workflows/scale.md +++ b/docs/versioned_docs/version-2.4/workflows/scale.md @@ -48,23 +48,23 @@ kubectl -n kube-system get nodes Alternatively, you can manually scale your cluster up or down: - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + :::caution @@ -72,8 +72,8 @@ Scaling isn't yet implemented for AWS. If you require this feature, [let us know ::: - - + + ## Control-plane node scaling @@ -81,24 +81,24 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - + - + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + :::caution @@ -106,7 +106,7 @@ Scaling isn't yet implemented for AWS. If you require this feature, [let us know ::: - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/versioned_docs/version-2.4/workflows/storage.md b/docs/versioned_docs/version-2.4/workflows/storage.md index d0e5b188f..be9998676 100644 --- a/docs/versioned_docs/version-2.4/workflows/storage.md +++ b/docs/versioned_docs/version-2.4/workflows/storage.md @@ -21,14 +21,14 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as ReadWriteOnce, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. @@ -36,8 +36,8 @@ This includes support for [volume snapshots](https://cloud.google.com/kubernetes You can use them to bring a volume back to a prior state or provision new volumes. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for information about the configuration. - - + + :::caution @@ -47,8 +47,8 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction) or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -57,8 +57,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The Constellation CLI automatically installs Constellation's CSI driver for the selected CSP in your cluster. If you don't need a CSI driver or wish to deploy your own, you can disable the automatic installation by setting `deployCSIDriver` to `false` in your Constellation config file. - - + + Azure comes with two storage classes by default. @@ -86,8 +86,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + GCP comes with two storage classes by default. @@ -115,8 +115,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + :::caution @@ -126,8 +126,8 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + 1. Create a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) @@ -186,8 +186,8 @@ The default storage class is responsible for all persistent volume claims that d Constellation creates a storage class with encryption enabled and sets this as the default class. In case you wish to change it, follow the steps below: - - + + 1. List the storage classes in your cluster: @@ -233,8 +233,8 @@ In case you wish to change it, follow the steps below: integrity-encrypted-rwo (default) azuredisk.csi.confidential.cloud Delete Immediate false 1d ``` - - + + 1. List the storage classes in your cluster: @@ -280,8 +280,8 @@ In case you wish to change it, follow the steps below: integrity-encrypted-rwo (default) gcp.csi.confidential.cloud Delete Immediate false 1d ``` - - + + :::caution @@ -291,5 +291,5 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + diff --git a/docs/versioned_docs/version-2.4/workflows/troubleshooting.md b/docs/versioned_docs/version-2.4/workflows/troubleshooting.md index 3a28c9cd0..f948f5d06 100644 --- a/docs/versioned_docs/version-2.4/workflows/troubleshooting.md +++ b/docs/versioned_docs/version-2.4/workflows/troubleshooting.md @@ -5,6 +5,7 @@ This section aids you in finding problems when working with Constellation. ## Azure: Resource Providers can't be registered On Azure, you may receive the following error when running `create` or `terminate` with limited IAM permissions: + ```shell-session Error: Error ensuring Resource Providers are registered. @@ -21,11 +22,13 @@ To continue, please ensure that the [required resource providers](../getting-sta Afterward, set `ARM_SKIP_PROVIDER_REGISTRATION=true` as an environment variable and either run `create` or `terminate` again. For example: + ```bash ARM_SKIP_PROVIDER_REGISTRATION=true constellation create --control-plane-nodes 1 --worker-nodes 2 -y ``` Or alternatively, for `terminate`: + ```bash ARM_SKIP_PROVIDER_REGISTRATION=true constellation terminate ``` @@ -36,8 +39,8 @@ To provide information during early stages of the node's boot process, Constella You can view these information in the follow places: - - + + 1. In your Azure subscription find the Constellation resource group. 2. Inside the resource group find the Application Insights resource called `constellation-insights-*`. @@ -47,8 +50,8 @@ You can view these information in the follow places: To **find the disk UUIDs** use the following query: `traces | where message contains "Disk UUID"` - - + + 1. Select the project that hosts Constellation. 2. Go to the `Compute Engine` service. @@ -63,16 +66,16 @@ Constellation uses the default bucket to store logs. Its [default retention peri ::: - - + + 1. Open [AWS CloudWatch](https://console.aws.amazon.com/cloudwatch/home) 2. Select [Log Groups](https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups) 3. Select the log group that matches the name of your cluster. 4. Select the log stream for control or worker type nodes. - - + + ## Connect to nodes diff --git a/docs/versioned_docs/version-2.5/architecture/attestation.md b/docs/versioned_docs/version-2.5/architecture/attestation.md index f335038f6..28e8e62cf 100644 --- a/docs/versioned_docs/version-2.5/architecture/attestation.md +++ b/docs/versioned_docs/version-2.5/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -152,8 +152,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -185,8 +185,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements. @@ -217,8 +217,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + ## Cluster attestation diff --git a/docs/versioned_docs/version-2.5/getting-started/first-steps.md b/docs/versioned_docs/version-2.5/getting-started/first-steps.md index 4e89bb0f2..02b60d45a 100644 --- a/docs/versioned_docs/version-2.5/getting-started/first-steps.md +++ b/docs/versioned_docs/version-2.5/getting-started/first-steps.md @@ -13,9 +13,9 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step First, you need to create a [configuration file](../workflows/config.md) and an [IAM configuration](../workflows/config.md#creating-an-iam-configuration). The easiest way to do this is the following CLI command: - + - + ```bash constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest --generate-config @@ -29,9 +29,9 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step * `northeurope` * `westeurope` - + - + ```bash constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west2-a --serviceAccountID=constell-test --generate-config @@ -41,9 +41,9 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step Note that only regions offering CVMs of the `N2D` series are supported. You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available), which you can filter by machine type `N2D`. - + - + ```bash constellation iam create aws --zone=eu-central-1a --prefix=constellTest --generate-config @@ -60,8 +60,8 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step You can find a list of all [regions in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). - - + + :::tip To learn about all options you have for managing IAM resources and Constellation configuration, see the [Configuration workflow](../workflows/config.md). diff --git a/docs/versioned_docs/version-2.5/getting-started/install.md b/docs/versioned_docs/version-2.5/getting-started/install.md index d830c7792..36d8f541a 100644 --- a/docs/versioned_docs/version-2.5/getting-started/install.md +++ b/docs/versioned_docs/version-2.5/getting-started/install.md @@ -18,8 +18,8 @@ Make sure the following requirements are met: The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -35,8 +35,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -52,9 +52,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -70,9 +70,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -88,8 +88,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -105,14 +105,15 @@ If you don't have a cloud subscription, you can try [MiniConstellation](first-st ### Required permissions - - + + The following [resource providers need to be registered](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) in your subscription: -* `Microsoft.Compute` -* `Microsoft.ManagedIdentity` -* `Microsoft.Network` -* `microsoft.insights` + +- `Microsoft.Compute` +- `Microsoft.ManagedIdentity` +- `Microsoft.Network` +- `microsoft.insights` By default, Constellation tries to register these automatically if they haven't been registered before. @@ -124,8 +125,8 @@ You need the following permissions for your user account: If you don't have these permissions with scope *subscription*, ask your administrator to [create the service account and a resource group for your Constellation cluster](first-steps.md). Your user account needs the `Contributor` permission scoped to this resource group. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. @@ -137,8 +138,8 @@ You need the following permissions on this project: Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + To set up a Constellation cluster, you need to perform two tasks that require permissions: create the infrastructure and create roles for cluster nodes. Both of these actions can be performed by different users, e.g., an administrator to create roles and a DevOps engineer to create the infrastructure. @@ -269,8 +270,8 @@ such as `PowerUserAccess`, or use the following minimal set of permissions: Follow Amazon's guide on [understanding](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [managing policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html). - - + + ### Authentication @@ -280,8 +281,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -297,8 +298,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -321,8 +322,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + **Testing** @@ -338,9 +339,9 @@ aws configure Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - + - + ## Next steps diff --git a/docs/versioned_docs/version-2.5/workflows/config.md b/docs/versioned_docs/version-2.5/workflows/config.md index 100dedc8c..2edf3bdf6 100644 --- a/docs/versioned_docs/version-2.5/workflows/config.md +++ b/docs/versioned_docs/version-2.5/workflows/config.md @@ -6,29 +6,29 @@ Before you can create your cluster, you need to configure the identity and acces You can generate a configuration file for your CSP by using the following CLI command: - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate aws ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. @@ -39,25 +39,25 @@ You can also automatically generate a configuration file by adding the `--genera ## Choosing a VM type Constellation supports the following VM types: - - + + 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. You can also run `constellation config instance-types` to get the list of all supported options. - - + + 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 with a minimum of 4 vCPUs 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. - - + + By default, Constellation uses `m6a.xlarge` 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 nitroTPM-enabled machines with a minimum of 4 vCPUs (`xlarge` or larger). Refer to the [list of nitroTPM-enabled instance types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enable-nitrotpm-prerequisites.html) or run `constellation config instance-types` to get the list of all supported options. - - + + Fill the desired VM type into the **instanceType** field in the `constellation-conf.yml` file. @@ -66,8 +66,8 @@ Fill the desired VM type into the **instanceType** field in the `constellation-c You can create an IAM configuration for your cluster automatically using the `constellation iam create` command. If you haven't generated a configuration file yet, you can do so by adding the `--generate-config` flag to the command. This creates a configuration file and populates it with the created IAM values. - - + + You must be authenticated with the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) in the shell session. @@ -90,8 +90,8 @@ Paste the output into the corresponding fields of the `constellation-conf.yaml` Since `clientSecretValue` is a sensitive value, you can leave it empty in the configuration file and pass it via an environment variable instead. To this end, create the environment variable `CONSTELL_AZURE_CLIENT_SECRET_VALUE` and set it to the secret value. ::: - - + + You must be authenticated with the [GCP CLI](https://cloud.google.com/sdk/gcloud) in the shell session. @@ -105,8 +105,8 @@ Note that only regions offering CVMs of the `N2D` series are supported. You can Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [AWS CLI](https://aws.amazon.com/en/cli/) in the shell session. @@ -128,16 +128,16 @@ You can find a list of all [regions in AWS's documentation](https://docs.aws.ama Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + +
Alternatively, you can manually create the IAM configuration on your CSP. The following describes the configuration fields and how you obtain the required information or create the required resources. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -181,9 +181,9 @@ The following describes the configuration fields and how you obtain the required Since this is a sensitive value, alternatively you can leave `clientSecretValue` empty in the configuration file and pass it via an environment variable instead. To this end, create the environment variable `CONSTELL_AZURE_CLIENT_SECRET_VALUE` and set it to the secret value. ::: - + - + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -207,9 +207,9 @@ The following describes the configuration fields and how you obtain the required Afterward, create and download a new JSON key for this service account. Place the downloaded file in your Constellation workspace, and set the config parameter to the filename, e.g., `constellation-129857-15343dba46cb.json`. - + - + * **region**: The name of your chosen AWS data center region, e.g., `us-east-2`. @@ -238,9 +238,9 @@ The following describes the configuration fields and how you obtain the required Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.worker_node_policy`. - + - +
Now that you've configured your CSP, you can [create your cluster](./create.md). diff --git a/docs/versioned_docs/version-2.5/workflows/create.md b/docs/versioned_docs/version-2.5/workflows/create.md index 7fc991fd7..115effbdf 100644 --- a/docs/versioned_docs/version-2.5/workflows/create.md +++ b/docs/versioned_docs/version-2.5/workflows/create.md @@ -18,8 +18,8 @@ Before you create the cluster, make sure to have a [valid configuration file](./ ### Create - - + + Choose the initial size of your cluster. The following command creates a cluster with one control-plane and two worker nodes: @@ -32,8 +32,8 @@ For details on the flags, consult the command help via `constellation create -h` *create* stores your cluster's state into a [`terraform.tfstate`](../architecture/orchestration.md#cluster-creation-process) file in your workspace. - - + + Constellation supports managing the infrastructure via Terraform. This allows for an easier GitOps integration as well as meeting regulatory requirements. Since the Constellation CLI also uses Terraform under the hood, you can reuse the same Terraform files. @@ -68,8 +68,8 @@ CONSTELL_CSP=$(cat constellation-conf.yaml | yq ".provider | keys | .[0]") jq --null-input --arg cloudprovider "$CONSTELL_CSP" --arg ip "$CONSTELL_IP" --arg initsecret "$CONSTELL_INIT_SECRET" '{"cloudprovider":$cloudprovider,"ip":$ip,"initsecret":$initsecret}' > constellation-id.json ``` - - + + ## The *init* step diff --git a/docs/versioned_docs/version-2.5/workflows/recovery.md b/docs/versioned_docs/version-2.5/workflows/recovery.md index fd610fc67..0fd171036 100644 --- a/docs/versioned_docs/version-2.5/workflows/recovery.md +++ b/docs/versioned_docs/version-2.5/workflows/recovery.md @@ -16,8 +16,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via [cloud logging](troubleshooting.md#cloud-logging). In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -51,8 +51,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -87,8 +87,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, open the AWS console to view all Auto Scaling Groups (ASGs) in the region of your cluster. Select the ASG of the control plane `--control-plane` and check that enough members are in a *Running* state. @@ -118,8 +118,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + ## Recover a cluster diff --git a/docs/versioned_docs/version-2.5/workflows/scale.md b/docs/versioned_docs/version-2.5/workflows/scale.md index 3b7c0d479..bce045c66 100644 --- a/docs/versioned_docs/version-2.5/workflows/scale.md +++ b/docs/versioned_docs/version-2.5/workflows/scale.md @@ -48,23 +48,23 @@ kubectl -n kube-system get nodes Alternatively, you can manually scale your cluster up or down: - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + :::caution @@ -72,8 +72,8 @@ Scaling isn't yet implemented for AWS. If you require this feature, [let us know ::: - - + + ## Control-plane node scaling @@ -81,24 +81,24 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - + - + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + :::caution @@ -106,7 +106,7 @@ Scaling isn't yet implemented for AWS. If you require this feature, [let us know ::: - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/versioned_docs/version-2.5/workflows/storage.md b/docs/versioned_docs/version-2.5/workflows/storage.md index d0e5b188f..be9998676 100644 --- a/docs/versioned_docs/version-2.5/workflows/storage.md +++ b/docs/versioned_docs/version-2.5/workflows/storage.md @@ -21,14 +21,14 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as ReadWriteOnce, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. @@ -36,8 +36,8 @@ This includes support for [volume snapshots](https://cloud.google.com/kubernetes You can use them to bring a volume back to a prior state or provision new volumes. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for information about the configuration. - - + + :::caution @@ -47,8 +47,8 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction) or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -57,8 +57,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The Constellation CLI automatically installs Constellation's CSI driver for the selected CSP in your cluster. If you don't need a CSI driver or wish to deploy your own, you can disable the automatic installation by setting `deployCSIDriver` to `false` in your Constellation config file. - - + + Azure comes with two storage classes by default. @@ -86,8 +86,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + GCP comes with two storage classes by default. @@ -115,8 +115,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + :::caution @@ -126,8 +126,8 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + 1. Create a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) @@ -186,8 +186,8 @@ The default storage class is responsible for all persistent volume claims that d Constellation creates a storage class with encryption enabled and sets this as the default class. In case you wish to change it, follow the steps below: - - + + 1. List the storage classes in your cluster: @@ -233,8 +233,8 @@ In case you wish to change it, follow the steps below: integrity-encrypted-rwo (default) azuredisk.csi.confidential.cloud Delete Immediate false 1d ``` - - + + 1. List the storage classes in your cluster: @@ -280,8 +280,8 @@ In case you wish to change it, follow the steps below: integrity-encrypted-rwo (default) gcp.csi.confidential.cloud Delete Immediate false 1d ``` - - + + :::caution @@ -291,5 +291,5 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + diff --git a/docs/versioned_docs/version-2.5/workflows/terminate.md b/docs/versioned_docs/version-2.5/workflows/terminate.md index a2556fe95..ee64a2784 100644 --- a/docs/versioned_docs/version-2.5/workflows/terminate.md +++ b/docs/versioned_docs/version-2.5/workflows/terminate.md @@ -8,8 +8,8 @@ All ephemeral storage and state of your cluster will be lost. Make sure any data ::: - - + + Terminate the cluster by running: ```bash @@ -32,8 +32,8 @@ resources manually. Just run the `terminate` command again afterward to continue ::: - - + + Terminate the cluster by running: ```bash @@ -48,5 +48,5 @@ rm constellation-id.json constellation-admin.conf Only the `constellation-mastersecret.json` and the configuration file remain. - - + + diff --git a/docs/versioned_docs/version-2.5/workflows/troubleshooting.md b/docs/versioned_docs/version-2.5/workflows/troubleshooting.md index 3a28c9cd0..f948f5d06 100644 --- a/docs/versioned_docs/version-2.5/workflows/troubleshooting.md +++ b/docs/versioned_docs/version-2.5/workflows/troubleshooting.md @@ -5,6 +5,7 @@ This section aids you in finding problems when working with Constellation. ## Azure: Resource Providers can't be registered On Azure, you may receive the following error when running `create` or `terminate` with limited IAM permissions: + ```shell-session Error: Error ensuring Resource Providers are registered. @@ -21,11 +22,13 @@ To continue, please ensure that the [required resource providers](../getting-sta Afterward, set `ARM_SKIP_PROVIDER_REGISTRATION=true` as an environment variable and either run `create` or `terminate` again. For example: + ```bash ARM_SKIP_PROVIDER_REGISTRATION=true constellation create --control-plane-nodes 1 --worker-nodes 2 -y ``` Or alternatively, for `terminate`: + ```bash ARM_SKIP_PROVIDER_REGISTRATION=true constellation terminate ``` @@ -36,8 +39,8 @@ To provide information during early stages of the node's boot process, Constella You can view these information in the follow places: - - + + 1. In your Azure subscription find the Constellation resource group. 2. Inside the resource group find the Application Insights resource called `constellation-insights-*`. @@ -47,8 +50,8 @@ You can view these information in the follow places: To **find the disk UUIDs** use the following query: `traces | where message contains "Disk UUID"` - - + + 1. Select the project that hosts Constellation. 2. Go to the `Compute Engine` service. @@ -63,16 +66,16 @@ Constellation uses the default bucket to store logs. Its [default retention peri ::: - - + + 1. Open [AWS CloudWatch](https://console.aws.amazon.com/cloudwatch/home) 2. Select [Log Groups](https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups) 3. Select the log group that matches the name of your cluster. 4. Select the log stream for control or worker type nodes. - - + + ## Connect to nodes diff --git a/docs/versioned_docs/version-2.6/architecture/attestation.md b/docs/versioned_docs/version-2.6/architecture/attestation.md index 0c7a1487b..20f9909fd 100644 --- a/docs/versioned_docs/version-2.6/architecture/attestation.md +++ b/docs/versioned_docs/version-2.6/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -152,8 +152,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -185,8 +185,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements. @@ -217,8 +217,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + ## Cluster attestation diff --git a/docs/versioned_docs/version-2.6/getting-started/first-steps.md b/docs/versioned_docs/version-2.6/getting-started/first-steps.md index ad89d89c8..aba09f5c7 100644 --- a/docs/versioned_docs/version-2.6/getting-started/first-steps.md +++ b/docs/versioned_docs/version-2.6/getting-started/first-steps.md @@ -17,9 +17,9 @@ If you encounter any problem with the following steps, make sure to use the [lat First, you need to create a [configuration file](../workflows/config.md) and an [IAM configuration](../workflows/config.md#creating-an-iam-configuration). The easiest way to do this is the following CLI command: - + - + ```bash constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest --generate-config @@ -33,9 +33,9 @@ If you encounter any problem with the following steps, make sure to use the [lat * `northeurope` * `westeurope` - + - + ```bash constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west2-a --serviceAccountID=constell-test --generate-config @@ -45,9 +45,9 @@ If you encounter any problem with the following steps, make sure to use the [lat Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available), which you can filter by machine type `C2D` or `N2D`. - + - + ```bash constellation iam create aws --zone=eu-central-1a --prefix=constellTest --generate-config @@ -64,8 +64,8 @@ If you encounter any problem with the following steps, make sure to use the [lat You can find a list of all [regions in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). - - + + :::tip To learn about all options you have for managing IAM resources and Constellation configuration, see the [Configuration workflow](../workflows/config.md). diff --git a/docs/versioned_docs/version-2.6/getting-started/install.md b/docs/versioned_docs/version-2.6/getting-started/install.md index d830c7792..36d8f541a 100644 --- a/docs/versioned_docs/version-2.6/getting-started/install.md +++ b/docs/versioned_docs/version-2.6/getting-started/install.md @@ -18,8 +18,8 @@ Make sure the following requirements are met: The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -35,8 +35,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -52,9 +52,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -70,9 +70,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -88,8 +88,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -105,14 +105,15 @@ If you don't have a cloud subscription, you can try [MiniConstellation](first-st ### Required permissions - - + + The following [resource providers need to be registered](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) in your subscription: -* `Microsoft.Compute` -* `Microsoft.ManagedIdentity` -* `Microsoft.Network` -* `microsoft.insights` + +- `Microsoft.Compute` +- `Microsoft.ManagedIdentity` +- `Microsoft.Network` +- `microsoft.insights` By default, Constellation tries to register these automatically if they haven't been registered before. @@ -124,8 +125,8 @@ You need the following permissions for your user account: If you don't have these permissions with scope *subscription*, ask your administrator to [create the service account and a resource group for your Constellation cluster](first-steps.md). Your user account needs the `Contributor` permission scoped to this resource group. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. @@ -137,8 +138,8 @@ You need the following permissions on this project: Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + To set up a Constellation cluster, you need to perform two tasks that require permissions: create the infrastructure and create roles for cluster nodes. Both of these actions can be performed by different users, e.g., an administrator to create roles and a DevOps engineer to create the infrastructure. @@ -269,8 +270,8 @@ such as `PowerUserAccess`, or use the following minimal set of permissions: Follow Amazon's guide on [understanding](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [managing policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html). - - + + ### Authentication @@ -280,8 +281,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -297,8 +298,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -321,8 +322,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + **Testing** @@ -338,9 +339,9 @@ aws configure Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - + - + ## Next steps diff --git a/docs/versioned_docs/version-2.6/workflows/config.md b/docs/versioned_docs/version-2.6/workflows/config.md index 4824210f1..5a1ba92d1 100644 --- a/docs/versioned_docs/version-2.6/workflows/config.md +++ b/docs/versioned_docs/version-2.6/workflows/config.md @@ -14,29 +14,29 @@ Before you can create your cluster, you need to configure the identity and acces You can generate a configuration file for your CSP by using the following CLI command: - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate aws ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. @@ -47,25 +47,25 @@ You can also automatically generate a configuration file by adding the `--genera ## Choosing a VM type Constellation supports the following VM types: - - + + 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. You can also run `constellation config instance-types` to get the list of all supported options. - - + + 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 with a minimum of 4 vCPUs from the [C2D](https://cloud.google.com/compute/docs/compute-optimized-machines#c2d_machine_types) or [N2D](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) family. You can run `constellation config instance-types` to get the list of all supported options. - - + + By default, Constellation uses `m6a.xlarge` 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 nitroTPM-enabled machines with a minimum of 4 vCPUs (`xlarge` or larger). Refer to the [list of nitroTPM-enabled instance types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enable-nitrotpm-prerequisites.html) or run `constellation config instance-types` to get the list of all supported options. - - + + Fill the desired VM type into the **instanceType** field in the `constellation-conf.yml` file. @@ -79,8 +79,8 @@ See also Constellation's [Kubernetes support policy](../architecture/versions.md You can create an IAM configuration for your cluster automatically using the `constellation iam create` command. If you haven't generated a configuration file yet, you can do so by adding the `--generate-config` flag to the command. This creates a configuration file and populates it with the created IAM values. - - + + You must be authenticated with the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) in the shell session. @@ -103,8 +103,8 @@ Paste the output into the corresponding fields of the `constellation-conf.yaml` Since `clientSecretValue` is a sensitive value, you can leave it empty in the configuration file and pass it via an environment variable instead. To this end, create the environment variable `CONSTELL_AZURE_CLIENT_SECRET_VALUE` and set it to the secret value. ::: - - + + You must be authenticated with the [GCP CLI](https://cloud.google.com/sdk/gcloud) in the shell session. @@ -118,8 +118,8 @@ Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [AWS CLI](https://aws.amazon.com/en/cli/) in the shell session. @@ -141,16 +141,16 @@ You can find a list of all [regions in AWS's documentation](https://docs.aws.ama Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + +
Alternatively, you can manually create the IAM configuration on your CSP. The following describes the configuration fields and how you obtain the required information or create the required resources. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -194,9 +194,9 @@ The following describes the configuration fields and how you obtain the required Since this is a sensitive value, alternatively you can leave `clientSecretValue` empty in the configuration file and pass it via an environment variable instead. To this end, create the environment variable `CONSTELL_AZURE_CLIENT_SECRET_VALUE` and set it to the secret value. ::: - + - + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -220,9 +220,9 @@ The following describes the configuration fields and how you obtain the required Afterward, create and download a new JSON key for this service account. Place the downloaded file in your Constellation workspace, and set the config parameter to the filename, e.g., `constellation-129857-15343dba46cb.json`. - + - + * **region**: The name of your chosen AWS data center region, e.g., `us-east-2`. @@ -251,9 +251,9 @@ The following describes the configuration fields and how you obtain the required Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.worker_node_policy`. - + - +
Now that you've configured your CSP, you can [create your cluster](./create.md). diff --git a/docs/versioned_docs/version-2.6/workflows/create.md b/docs/versioned_docs/version-2.6/workflows/create.md index b078c16ff..81ed55582 100644 --- a/docs/versioned_docs/version-2.6/workflows/create.md +++ b/docs/versioned_docs/version-2.6/workflows/create.md @@ -26,8 +26,8 @@ Before you create the cluster, make sure to have a [valid configuration file](./ ### Create - - + + Choose the initial size of your cluster. The following command creates a cluster with one control-plane and two worker nodes: @@ -40,8 +40,8 @@ For details on the flags, consult the command help via `constellation create -h` *create* stores your cluster's state in a [`constellation-terraform`](../architecture/orchestration.md#cluster-creation-process) directory in your workspace. - - + + Terraform allows for an easier GitOps integration as well as meeting regulatory requirements. Since the Constellation CLI also uses Terraform under the hood, you can reuse the same Terraform files. @@ -80,8 +80,8 @@ CONSTELL_CSP=$(cat constellation-conf.yaml | yq ".provider | keys | .[0]") jq --null-input --arg cloudprovider "$CONSTELL_CSP" --arg ip "$CONSTELL_IP" --arg initsecret "$CONSTELL_INIT_SECRET" '{"cloudprovider":$cloudprovider,"ip":$ip,"initsecret":$initsecret}' > constellation-id.json ``` - - + + ## The *init* step diff --git a/docs/versioned_docs/version-2.6/workflows/recovery.md b/docs/versioned_docs/version-2.6/workflows/recovery.md index c26fb32eb..35596b8c9 100644 --- a/docs/versioned_docs/version-2.6/workflows/recovery.md +++ b/docs/versioned_docs/version-2.6/workflows/recovery.md @@ -16,8 +16,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via [cloud logging](troubleshooting.md#cloud-logging). In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -51,8 +51,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -87,8 +87,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, open the AWS console to view all Auto Scaling Groups (ASGs) in the region of your cluster. Select the ASG of the control plane `--control-plane` and check that enough members are in a *Running* state. @@ -118,8 +118,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + ## Recover a cluster diff --git a/docs/versioned_docs/version-2.6/workflows/scale.md b/docs/versioned_docs/version-2.6/workflows/scale.md index 3b7c0d479..bce045c66 100644 --- a/docs/versioned_docs/version-2.6/workflows/scale.md +++ b/docs/versioned_docs/version-2.6/workflows/scale.md @@ -48,23 +48,23 @@ kubectl -n kube-system get nodes Alternatively, you can manually scale your cluster up or down: - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + :::caution @@ -72,8 +72,8 @@ Scaling isn't yet implemented for AWS. If you require this feature, [let us know ::: - - + + ## Control-plane node scaling @@ -81,24 +81,24 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - + - + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + :::caution @@ -106,7 +106,7 @@ Scaling isn't yet implemented for AWS. If you require this feature, [let us know ::: - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/versioned_docs/version-2.6/workflows/storage.md b/docs/versioned_docs/version-2.6/workflows/storage.md index d0e5b188f..be9998676 100644 --- a/docs/versioned_docs/version-2.6/workflows/storage.md +++ b/docs/versioned_docs/version-2.6/workflows/storage.md @@ -21,14 +21,14 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as ReadWriteOnce, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. @@ -36,8 +36,8 @@ This includes support for [volume snapshots](https://cloud.google.com/kubernetes You can use them to bring a volume back to a prior state or provision new volumes. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for information about the configuration. - - + + :::caution @@ -47,8 +47,8 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction) or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -57,8 +57,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The Constellation CLI automatically installs Constellation's CSI driver for the selected CSP in your cluster. If you don't need a CSI driver or wish to deploy your own, you can disable the automatic installation by setting `deployCSIDriver` to `false` in your Constellation config file. - - + + Azure comes with two storage classes by default. @@ -86,8 +86,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + GCP comes with two storage classes by default. @@ -115,8 +115,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + :::caution @@ -126,8 +126,8 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + 1. Create a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) @@ -186,8 +186,8 @@ The default storage class is responsible for all persistent volume claims that d Constellation creates a storage class with encryption enabled and sets this as the default class. In case you wish to change it, follow the steps below: - - + + 1. List the storage classes in your cluster: @@ -233,8 +233,8 @@ In case you wish to change it, follow the steps below: integrity-encrypted-rwo (default) azuredisk.csi.confidential.cloud Delete Immediate false 1d ``` - - + + 1. List the storage classes in your cluster: @@ -280,8 +280,8 @@ In case you wish to change it, follow the steps below: integrity-encrypted-rwo (default) gcp.csi.confidential.cloud Delete Immediate false 1d ``` - - + + :::caution @@ -291,5 +291,5 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + diff --git a/docs/versioned_docs/version-2.6/workflows/terminate.md b/docs/versioned_docs/version-2.6/workflows/terminate.md index 6c1eebb14..f33489ca5 100644 --- a/docs/versioned_docs/version-2.6/workflows/terminate.md +++ b/docs/versioned_docs/version-2.6/workflows/terminate.md @@ -16,8 +16,8 @@ All ephemeral storage and state of your cluster will be lost. Make sure any data ::: - - + + Terminate the cluster by running: ```bash @@ -40,8 +40,8 @@ resources manually. Just run the `terminate` command again afterward to continue ::: - - + + Terminate the cluster by running: ```bash @@ -56,5 +56,5 @@ rm constellation-id.json constellation-admin.conf Only the `constellation-mastersecret.json` and the configuration file remain. - - + + diff --git a/docs/versioned_docs/version-2.6/workflows/troubleshooting.md b/docs/versioned_docs/version-2.6/workflows/troubleshooting.md index 801bb995a..6bdf1d75c 100644 --- a/docs/versioned_docs/version-2.6/workflows/troubleshooting.md +++ b/docs/versioned_docs/version-2.6/workflows/troubleshooting.md @@ -10,6 +10,7 @@ If something doesn't work, check out the [known issues](https://github.com/edgel ## Azure: Resource Providers can't be registered On Azure, you may receive the following error when running `create` or `terminate` with limited IAM permissions: + ```shell-session Error: Error ensuring Resource Providers are registered. @@ -26,11 +27,13 @@ To continue, please ensure that the [required resource providers](../getting-sta Afterward, set `ARM_SKIP_PROVIDER_REGISTRATION=true` as an environment variable and either run `create` or `terminate` again. For example: + ```bash ARM_SKIP_PROVIDER_REGISTRATION=true constellation create --control-plane-nodes 1 --worker-nodes 2 -y ``` Or alternatively, for `terminate`: + ```bash ARM_SKIP_PROVIDER_REGISTRATION=true constellation terminate ``` @@ -41,8 +44,8 @@ To provide information during early stages of the node's boot process, Constella You can view these information in the follow places: - - + + 1. In your Azure subscription find the Constellation resource group. 2. Inside the resource group find the Application Insights resource called `constellation-insights-*`. @@ -52,8 +55,8 @@ You can view these information in the follow places: To **find the disk UUIDs** use the following query: `traces | where message contains "Disk UUID"` - - + + 1. Select the project that hosts Constellation. 2. Go to the `Compute Engine` service. @@ -68,16 +71,16 @@ Constellation uses the default bucket to store logs. Its [default retention peri ::: - - + + 1. Open [AWS CloudWatch](https://console.aws.amazon.com/cloudwatch/home) 2. Select [Log Groups](https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups) 3. Select the log group that matches the name of your cluster. 4. Select the log stream for control or worker type nodes. - - + + ## Connect to nodes diff --git a/docs/versioned_docs/version-2.7/architecture/attestation.md b/docs/versioned_docs/version-2.7/architecture/attestation.md index 0c7a1487b..20f9909fd 100644 --- a/docs/versioned_docs/version-2.7/architecture/attestation.md +++ b/docs/versioned_docs/version-2.7/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -152,8 +152,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -185,8 +185,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements. @@ -217,8 +217,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + ## Cluster attestation diff --git a/docs/versioned_docs/version-2.7/getting-started/first-steps-local.md b/docs/versioned_docs/version-2.7/getting-started/first-steps-local.md index 707074bb9..81d8e141d 100644 --- a/docs/versioned_docs/version-2.7/getting-started/first-steps-local.md +++ b/docs/versioned_docs/version-2.7/getting-started/first-steps-local.md @@ -30,8 +30,8 @@ Both options use virtualization to create a local cluster with control-plane nod ## Create a cluster - - + + 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/). @@ -59,8 +59,8 @@ 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. - - + + 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. @@ -138,8 +138,8 @@ attaching persistent storage, or autoscaling aren't available. export KUBECONFIG="$PWD/constellation-admin.conf" ``` - - + + ## Connect to the cluster @@ -192,8 +192,8 @@ worker-0 Ready 32s v1.24.6 ## Terminate your cluster - - + + Once you are done, you can clean up the created resources using the following command: @@ -204,8 +204,8 @@ 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. - - + + Once you are done, you can clean up the created resources using the following command: @@ -233,8 +233,8 @@ 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. - - + + ## Troubleshooting diff --git a/docs/versioned_docs/version-2.7/getting-started/first-steps.md b/docs/versioned_docs/version-2.7/getting-started/first-steps.md index 1569afc14..eca497438 100644 --- a/docs/versioned_docs/version-2.7/getting-started/first-steps.md +++ b/docs/versioned_docs/version-2.7/getting-started/first-steps.md @@ -17,9 +17,9 @@ If you encounter any problem with the following steps, make sure to use the [lat First, you need to create a [configuration file](../workflows/config.md) and an [IAM configuration](../workflows/config.md#creating-an-iam-configuration). The easiest way to do this is the following CLI command: - + - + ```bash constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest --generate-config @@ -33,9 +33,9 @@ If you encounter any problem with the following steps, make sure to use the [lat * `northeurope` * `westeurope` - + - + ```bash constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west2-a --serviceAccountID=constell-test --generate-config @@ -45,9 +45,9 @@ If you encounter any problem with the following steps, make sure to use the [lat Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available), which you can filter by machine type `C2D` or `N2D`. - + - + ```bash constellation iam create aws --zone=eu-central-1a --prefix=constellTest --generate-config @@ -66,8 +66,8 @@ If you encounter any problem with the following steps, make sure to use the [lat You can find a list of all [regions in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). - - + + :::tip To learn about all options you have for managing IAM resources and Constellation configuration, see the [Configuration workflow](../workflows/config.md). diff --git a/docs/versioned_docs/version-2.7/getting-started/install.md b/docs/versioned_docs/version-2.7/getting-started/install.md index d0b60441e..ac0ef3da8 100644 --- a/docs/versioned_docs/version-2.7/getting-started/install.md +++ b/docs/versioned_docs/version-2.7/getting-started/install.md @@ -18,8 +18,8 @@ Make sure the following requirements are met: The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -35,8 +35,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -52,9 +52,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -70,9 +70,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -88,8 +88,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -105,38 +105,41 @@ If you don't have a cloud subscription, you can try [MiniConstellation](first-st ### Required permissions - - + + The following [resource providers need to be registered](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) in your subscription: -* `Microsoft.Attestation` -* `Microsoft.Compute` -* `Microsoft.Insights` -* `Microsoft.ManagedIdentity` -* `Microsoft.Network` + +- `Microsoft.Attestation` +- `Microsoft.Compute` +- `Microsoft.Insights` +- `Microsoft.ManagedIdentity` +- `Microsoft.Network` By default, Constellation tries to register these automatically if they haven't been registered before. To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: -* `*/register/action` \[1] -* `Microsoft.Authorization/roleAssignments/*` -* `Microsoft.Authorization/roleDefinitions/*` -* `Microsoft.ManagedIdentity/userAssignedIdentities/*` -* `Microsoft.Resources/subscriptions/resourcegroups/*` + +- `*/register/action` \[1] +- `Microsoft.Authorization/roleAssignments/*` +- `Microsoft.Authorization/roleDefinitions/*` +- `Microsoft.ManagedIdentity/userAssignedIdentities/*` +- `Microsoft.Resources/subscriptions/resourcegroups/*` The built-in `Owner` role is a superset of these permissions. To [create a Constellation cluster](../workflows/create.md#the-create-step), you need the following permissions: -* `Microsoft.Attestation/attestationProviders/*` -* `Microsoft.Compute/virtualMachineScaleSets/*` -* `Microsoft.Insights/components/*` -* `Microsoft.ManagedIdentity/userAssignedIdentities/*` -* `Microsoft.Network/loadBalancers/*` -* `Microsoft.Network/loadBalancers/backendAddressPools/*` -* `Microsoft.Network/networkSecurityGroups/*` -* `Microsoft.Network/publicIPAddresses/*` -* `Microsoft.Network/virtualNetworks/*` -* `Microsoft.Network/virtualNetworks/subnets/*` + +- `Microsoft.Attestation/attestationProviders/*` +- `Microsoft.Compute/virtualMachineScaleSets/*` +- `Microsoft.Insights/components/*` +- `Microsoft.ManagedIdentity/userAssignedIdentities/*` +- `Microsoft.Network/loadBalancers/*` +- `Microsoft.Network/loadBalancers/backendAddressPools/*` +- `Microsoft.Network/networkSecurityGroups/*` +- `Microsoft.Network/publicIPAddresses/*` +- `Microsoft.Network/virtualNetworks/*` +- `Microsoft.Network/virtualNetworks/subnets/*` The built-in `Contributor` role is a superset of these permissions. @@ -144,89 +147,91 @@ Follow Microsoft's guide on [understanding](https://learn.microsoft.com/en-us/az 1: You can omit `*/register/Action` if the resource providers mentioned above are already registered and the `ARM_SKIP_PROVIDER_REGISTRATION` environment variable is set to `true` when creating the IAM configuration. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: -* `iam.serviceAccountKeys.create` -* `iam.serviceAccountKeys.delete` -* `iam.serviceAccountKeys.get` -* `iam.serviceAccounts.create` -* `iam.serviceAccounts.delete` -* `iam.serviceAccounts.get` -* `resourcemanager.projects.getIamPolicy` -* `resourcemanager.projects.setIamPolicy` + +- `iam.serviceAccountKeys.create` +- `iam.serviceAccountKeys.delete` +- `iam.serviceAccountKeys.get` +- `iam.serviceAccounts.create` +- `iam.serviceAccounts.delete` +- `iam.serviceAccounts.get` +- `resourcemanager.projects.getIamPolicy` +- `resourcemanager.projects.setIamPolicy` Together, the built-in roles `roles/editor` and `roles/resourcemanager.projectIamAdmin` form a superset of these permissions. To [create a Constellation cluster](../workflows/create.md#the-create-step), you need the following permissions: -* `compute.addresses.createInternal` -* `compute.addresses.deleteInternal` -* `compute.addresses.get` -* `compute.addresses.useInternal` -* `compute.backendServices.create` -* `compute.backendServices.delete` -* `compute.backendServices.get` -* `compute.backendServices.use` -* `compute.disks.create` -* `compute.firewalls.create` -* `compute.firewalls.delete` -* `compute.firewalls.get` -* `compute.globalAddresses.create` -* `compute.globalAddresses.delete` -* `compute.globalAddresses.get` -* `compute.globalAddresses.use` -* `compute.globalForwardingRules.create` -* `compute.globalForwardingRules.delete` -* `compute.globalForwardingRules.get` -* `compute.globalForwardingRules.setLabels` -* `compute.globalOperations.get` -* `compute.healthChecks.create` -* `compute.healthChecks.delete` -* `compute.healthChecks.get` -* `compute.healthChecks.useReadOnly` -* `compute.instanceGroupManagers.create` -* `compute.instanceGroupManagers.delete` -* `compute.instanceGroupManagers.get` -* `compute.instanceGroups.create` -* `compute.instanceGroups.delete` -* `compute.instanceGroups.get` -* `compute.instanceGroups.use` -* `compute.instances.create` -* `compute.instances.setLabels` -* `compute.instances.setMetadata` -* `compute.instances.setTags` -* `compute.instanceTemplates.create` -* `compute.instanceTemplates.delete` -* `compute.instanceTemplates.get` -* `compute.instanceTemplates.useReadOnly` -* `compute.networks.create` -* `compute.networks.delete` -* `compute.networks.get` -* `compute.networks.updatePolicy` -* `compute.routers.create` -* `compute.routers.delete` -* `compute.routers.get` -* `compute.routers.update` -* `compute.subnetworks.create` -* `compute.subnetworks.delete` -* `compute.subnetworks.get` -* `compute.subnetworks.use` -* `compute.targetTcpProxies.create` -* `compute.targetTcpProxies.delete` -* `compute.targetTcpProxies.get` -* `compute.targetTcpProxies.use` -* `iam.serviceAccounts.actAs` + +- `compute.addresses.createInternal` +- `compute.addresses.deleteInternal` +- `compute.addresses.get` +- `compute.addresses.useInternal` +- `compute.backendServices.create` +- `compute.backendServices.delete` +- `compute.backendServices.get` +- `compute.backendServices.use` +- `compute.disks.create` +- `compute.firewalls.create` +- `compute.firewalls.delete` +- `compute.firewalls.get` +- `compute.globalAddresses.create` +- `compute.globalAddresses.delete` +- `compute.globalAddresses.get` +- `compute.globalAddresses.use` +- `compute.globalForwardingRules.create` +- `compute.globalForwardingRules.delete` +- `compute.globalForwardingRules.get` +- `compute.globalForwardingRules.setLabels` +- `compute.globalOperations.get` +- `compute.healthChecks.create` +- `compute.healthChecks.delete` +- `compute.healthChecks.get` +- `compute.healthChecks.useReadOnly` +- `compute.instanceGroupManagers.create` +- `compute.instanceGroupManagers.delete` +- `compute.instanceGroupManagers.get` +- `compute.instanceGroups.create` +- `compute.instanceGroups.delete` +- `compute.instanceGroups.get` +- `compute.instanceGroups.use` +- `compute.instances.create` +- `compute.instances.setLabels` +- `compute.instances.setMetadata` +- `compute.instances.setTags` +- `compute.instanceTemplates.create` +- `compute.instanceTemplates.delete` +- `compute.instanceTemplates.get` +- `compute.instanceTemplates.useReadOnly` +- `compute.networks.create` +- `compute.networks.delete` +- `compute.networks.get` +- `compute.networks.updatePolicy` +- `compute.routers.create` +- `compute.routers.delete` +- `compute.routers.get` +- `compute.routers.update` +- `compute.subnetworks.create` +- `compute.subnetworks.delete` +- `compute.subnetworks.get` +- `compute.subnetworks.use` +- `compute.targetTcpProxies.create` +- `compute.targetTcpProxies.delete` +- `compute.targetTcpProxies.get` +- `compute.targetTcpProxies.use` +- `iam.serviceAccounts.actAs` Together, the built-in roles `roles/editor`, `roles/compute.instanceAdmin` and `roles/resourcemanager.projectIamAdmin` form a superset of these permissions. Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + To set up a Constellation cluster, you need to perform two tasks that require permissions: create the infrastructure and create roles for cluster nodes. Both of these actions can be performed by different users, e.g., an administrator to create roles and a DevOps engineer to create the infrastructure. @@ -361,8 +366,8 @@ The built-in `PowerUserAccess` policy is a superset of these permissions. Follow Amazon's guide on [understanding](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [managing policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html). - - + + ### Authentication @@ -372,8 +377,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -389,8 +394,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -413,8 +418,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + **Testing** @@ -430,9 +435,9 @@ aws configure Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - + - + ## Next steps diff --git a/docs/versioned_docs/version-2.7/workflows/config.md b/docs/versioned_docs/version-2.7/workflows/config.md index 7145028a8..5640bfd7d 100644 --- a/docs/versioned_docs/version-2.7/workflows/config.md +++ b/docs/versioned_docs/version-2.7/workflows/config.md @@ -14,29 +14,29 @@ Before you can create your cluster, you need to configure the identity and acces You can generate a configuration file for your CSP by using the following CLI command: - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate aws ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. @@ -47,25 +47,25 @@ You can also automatically generate a configuration file by adding the `--genera ## Choosing a VM type Constellation supports the following VM types: - - + + 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. You can also run `constellation config instance-types` to get the list of all supported options. - - + + 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 with a minimum of 4 vCPUs from the [C2D](https://cloud.google.com/compute/docs/compute-optimized-machines#c2d_machine_types) or [N2D](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) family. You can run `constellation config instance-types` to get the list of all supported options. - - + + By default, Constellation uses `m6a.xlarge` 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 nitroTPM-enabled machines with a minimum of 4 vCPUs (`xlarge` or larger). Refer to the [list of nitroTPM-enabled instance types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enable-nitrotpm-prerequisites.html) or run `constellation config instance-types` to get the list of all supported options. - - + + Fill the desired VM type into the **instanceType** field in the `constellation-conf.yml` file. @@ -79,8 +79,8 @@ See also Constellation's [Kubernetes support policy](../architecture/versions.md You can create an IAM configuration for your cluster automatically using the `constellation iam create` command. If you haven't generated a configuration file yet, you can do so by adding the `--generate-config` flag to the command. This creates a configuration file and populates it with the created IAM values. - - + + You must be authenticated with the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -103,8 +103,8 @@ Paste the output into the corresponding fields of the `constellation-conf.yaml` Since `clientSecretValue` is a sensitive value, you can leave it empty in the configuration file and pass it via an environment variable instead. To this end, create the environment variable `CONSTELL_AZURE_CLIENT_SECRET_VALUE` and set it to the secret value. ::: - - + + You must be authenticated with the [GCP CLI](https://cloud.google.com/sdk/gcloud) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -118,8 +118,8 @@ Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [AWS CLI](https://aws.amazon.com/en/cli/) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -143,16 +143,16 @@ You can find a list of all [regions in AWS's documentation](https://docs.aws.ama Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + +
Alternatively, you can manually create the IAM configuration on your CSP. The following describes the configuration fields and how you obtain the required information or create the required resources. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -196,9 +196,9 @@ The following describes the configuration fields and how you obtain the required Since this is a sensitive value, alternatively you can leave `clientSecretValue` empty in the configuration file and pass it via an environment variable instead. To this end, create the environment variable `CONSTELL_AZURE_CLIENT_SECRET_VALUE` and set it to the secret value. ::: - + - + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -222,9 +222,9 @@ The following describes the configuration fields and how you obtain the required Afterward, create and download a new JSON key for this service account. Place the downloaded file in your Constellation workspace, and set the config parameter to the filename, e.g., `constellation-129857-15343dba46cb.json`. - + - + * **region**: The name of your chosen AWS data center region, e.g., `us-east-2`. @@ -255,9 +255,9 @@ The following describes the configuration fields and how you obtain the required Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.worker_node_policy`. - + - +
Now that you've configured your CSP, you can [create your cluster](./create.md). diff --git a/docs/versioned_docs/version-2.7/workflows/create.md b/docs/versioned_docs/version-2.7/workflows/create.md index 33d2f12f8..5c4dd2948 100644 --- a/docs/versioned_docs/version-2.7/workflows/create.md +++ b/docs/versioned_docs/version-2.7/workflows/create.md @@ -26,8 +26,8 @@ Before you create the cluster, make sure to have a [valid configuration file](./ ### Create - - + + Choose the initial size of your cluster. The following command creates a cluster with one control-plane and two worker nodes: @@ -40,8 +40,8 @@ For details on the flags, consult the command help via `constellation create -h` *create* stores your cluster's state in a [`constellation-terraform`](../architecture/orchestration.md#cluster-creation-process) directory in your workspace. - - + + Terraform allows for an easier GitOps integration as well as meeting regulatory requirements. Since the Constellation CLI also uses Terraform under the hood, you can reuse the same Terraform files. @@ -80,8 +80,8 @@ CONSTELL_CSP=$(cat constellation-conf.yaml | yq ".provider | keys | .[0]") jq --null-input --arg cloudprovider "$CONSTELL_CSP" --arg ip "$CONSTELL_IP" --arg initsecret "$CONSTELL_INIT_SECRET" '{"cloudprovider":$cloudprovider,"ip":$ip,"initsecret":$initsecret}' > constellation-id.json ``` - - + + ## The *init* step diff --git a/docs/versioned_docs/version-2.7/workflows/recovery.md b/docs/versioned_docs/version-2.7/workflows/recovery.md index c26fb32eb..35596b8c9 100644 --- a/docs/versioned_docs/version-2.7/workflows/recovery.md +++ b/docs/versioned_docs/version-2.7/workflows/recovery.md @@ -16,8 +16,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via [cloud logging](troubleshooting.md#cloud-logging). In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -51,8 +51,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -87,8 +87,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, open the AWS console to view all Auto Scaling Groups (ASGs) in the region of your cluster. Select the ASG of the control plane `--control-plane` and check that enough members are in a *Running* state. @@ -118,8 +118,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + ## Recover a cluster diff --git a/docs/versioned_docs/version-2.7/workflows/scale.md b/docs/versioned_docs/version-2.7/workflows/scale.md index 3b7c0d479..bce045c66 100644 --- a/docs/versioned_docs/version-2.7/workflows/scale.md +++ b/docs/versioned_docs/version-2.7/workflows/scale.md @@ -48,23 +48,23 @@ kubectl -n kube-system get nodes Alternatively, you can manually scale your cluster up or down: - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + :::caution @@ -72,8 +72,8 @@ Scaling isn't yet implemented for AWS. If you require this feature, [let us know ::: - - + + ## Control-plane node scaling @@ -81,24 +81,24 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - + - + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + :::caution @@ -106,7 +106,7 @@ Scaling isn't yet implemented for AWS. If you require this feature, [let us know ::: - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/versioned_docs/version-2.7/workflows/storage.md b/docs/versioned_docs/version-2.7/workflows/storage.md index d0e5b188f..be9998676 100644 --- a/docs/versioned_docs/version-2.7/workflows/storage.md +++ b/docs/versioned_docs/version-2.7/workflows/storage.md @@ -21,14 +21,14 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as ReadWriteOnce, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. @@ -36,8 +36,8 @@ This includes support for [volume snapshots](https://cloud.google.com/kubernetes You can use them to bring a volume back to a prior state or provision new volumes. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for information about the configuration. - - + + :::caution @@ -47,8 +47,8 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction) or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -57,8 +57,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The Constellation CLI automatically installs Constellation's CSI driver for the selected CSP in your cluster. If you don't need a CSI driver or wish to deploy your own, you can disable the automatic installation by setting `deployCSIDriver` to `false` in your Constellation config file. - - + + Azure comes with two storage classes by default. @@ -86,8 +86,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + GCP comes with two storage classes by default. @@ -115,8 +115,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + :::caution @@ -126,8 +126,8 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + 1. Create a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) @@ -186,8 +186,8 @@ The default storage class is responsible for all persistent volume claims that d Constellation creates a storage class with encryption enabled and sets this as the default class. In case you wish to change it, follow the steps below: - - + + 1. List the storage classes in your cluster: @@ -233,8 +233,8 @@ In case you wish to change it, follow the steps below: integrity-encrypted-rwo (default) azuredisk.csi.confidential.cloud Delete Immediate false 1d ``` - - + + 1. List the storage classes in your cluster: @@ -280,8 +280,8 @@ In case you wish to change it, follow the steps below: integrity-encrypted-rwo (default) gcp.csi.confidential.cloud Delete Immediate false 1d ``` - - + + :::caution @@ -291,5 +291,5 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + diff --git a/docs/versioned_docs/version-2.7/workflows/terminate.md b/docs/versioned_docs/version-2.7/workflows/terminate.md index 6c1eebb14..f33489ca5 100644 --- a/docs/versioned_docs/version-2.7/workflows/terminate.md +++ b/docs/versioned_docs/version-2.7/workflows/terminate.md @@ -16,8 +16,8 @@ All ephemeral storage and state of your cluster will be lost. Make sure any data ::: - - + + Terminate the cluster by running: ```bash @@ -40,8 +40,8 @@ resources manually. Just run the `terminate` command again afterward to continue ::: - - + + Terminate the cluster by running: ```bash @@ -56,5 +56,5 @@ rm constellation-id.json constellation-admin.conf Only the `constellation-mastersecret.json` and the configuration file remain. - - + + diff --git a/docs/versioned_docs/version-2.7/workflows/troubleshooting.md b/docs/versioned_docs/version-2.7/workflows/troubleshooting.md index 2ddf3335d..cd095be28 100644 --- a/docs/versioned_docs/version-2.7/workflows/troubleshooting.md +++ b/docs/versioned_docs/version-2.7/workflows/troubleshooting.md @@ -75,8 +75,8 @@ To provide information during early stages of a node's boot process, Constellati You can view this information in the following places: - - + + 1. In your Azure subscription find the Constellation resource group. 2. Inside the resource group find the Application Insights resource called `constellation-insights-*`. @@ -86,8 +86,8 @@ You can view this information in the following places: To **find the disk UUIDs** use the following query: `traces | where message contains "Disk UUID"` - - + + 1. Select the project that hosts Constellation. 2. Go to the `Compute Engine` service. @@ -102,16 +102,16 @@ Constellation uses the default bucket to store logs. Its [default retention peri ::: - - + + 1. Open [AWS CloudWatch](https://console.aws.amazon.com/cloudwatch/home) 2. Select [Log Groups](https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups) 3. Select the log group that matches the name of your cluster. 4. Select the log stream for control or worker type nodes. - - + + ### Node shell access diff --git a/docs/versioned_docs/version-2.8/architecture/attestation.md b/docs/versioned_docs/version-2.8/architecture/attestation.md index 07ac3aa72..592063193 100644 --- a/docs/versioned_docs/version-2.8/architecture/attestation.md +++ b/docs/versioned_docs/version-2.8/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -152,8 +152,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -185,8 +185,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements. @@ -217,16 +217,16 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + ### CVM verification To verify the integrity of the received attestation statement, a chain of trust from the CVM technology to the interface providing the statement has to be established. For verification of the CVM technology, Constellation may expose additional options in its config file. - - + + On Azure, AMD SEV-SNP is used to provide runtime encryption to the VMs. An SEV-SNP attestation report is used to establish trust in the vTPM running inside the VM. @@ -248,18 +248,18 @@ You may customize certain parameters for verification of the attestation stateme More explicitly, it controls the verification of the `IDKeyDigest` value in the SEV-SNP attestation report. You can provide a list of accepted key digests and specify a policy on how this list is compared against the reported `IDKeyDigest`. - - + + There is no additional configuration available for GCP. - - + + There is no additional configuration available for AWS. - - + + ## Cluster attestation diff --git a/docs/versioned_docs/version-2.8/getting-started/first-steps-local.md b/docs/versioned_docs/version-2.8/getting-started/first-steps-local.md index 707074bb9..81d8e141d 100644 --- a/docs/versioned_docs/version-2.8/getting-started/first-steps-local.md +++ b/docs/versioned_docs/version-2.8/getting-started/first-steps-local.md @@ -30,8 +30,8 @@ Both options use virtualization to create a local cluster with control-plane nod ## Create a cluster - - + + 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/). @@ -59,8 +59,8 @@ 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. - - + + 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. @@ -138,8 +138,8 @@ attaching persistent storage, or autoscaling aren't available. export KUBECONFIG="$PWD/constellation-admin.conf" ``` - - + + ## Connect to the cluster @@ -192,8 +192,8 @@ worker-0 Ready 32s v1.24.6 ## Terminate your cluster - - + + Once you are done, you can clean up the created resources using the following command: @@ -204,8 +204,8 @@ 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. - - + + Once you are done, you can clean up the created resources using the following command: @@ -233,8 +233,8 @@ 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. - - + + ## Troubleshooting diff --git a/docs/versioned_docs/version-2.8/getting-started/first-steps.md b/docs/versioned_docs/version-2.8/getting-started/first-steps.md index 4449e6d37..43ed0f923 100644 --- a/docs/versioned_docs/version-2.8/getting-started/first-steps.md +++ b/docs/versioned_docs/version-2.8/getting-started/first-steps.md @@ -17,9 +17,9 @@ If you encounter any problem with the following steps, make sure to use the [lat First, you need to create a [configuration file](../workflows/config.md) and an [IAM configuration](../workflows/config.md#creating-an-iam-configuration). The easiest way to do this is the following CLI command: - + - + ```bash constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest --generate-config @@ -34,9 +34,9 @@ If you encounter any problem with the following steps, make sure to use the [lat * `westeurope` * `southeastasia` - + - + ```bash constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west2-a --serviceAccountID=constell-test --generate-config @@ -46,9 +46,9 @@ If you encounter any problem with the following steps, make sure to use the [lat Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available), which you can filter by machine type `C2D` or `N2D`. - + - + ```bash constellation iam create aws --zone=eu-central-1a --prefix=constellTest --generate-config @@ -67,8 +67,8 @@ If you encounter any problem with the following steps, make sure to use the [lat You can find a list of all [regions in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). - - + + :::tip To learn about all options you have for managing IAM resources and Constellation configuration, see the [Configuration workflow](../workflows/config.md). diff --git a/docs/versioned_docs/version-2.8/getting-started/install.md b/docs/versioned_docs/version-2.8/getting-started/install.md index 11167c34c..2aa274b98 100644 --- a/docs/versioned_docs/version-2.8/getting-started/install.md +++ b/docs/versioned_docs/version-2.8/getting-started/install.md @@ -18,8 +18,8 @@ Make sure the following requirements are met: The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -35,8 +35,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -52,9 +52,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -70,9 +70,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -88,8 +88,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -105,39 +105,42 @@ If you don't have a cloud subscription, you can also set up a [local Constellati ### Required permissions - - + + The following [resource providers need to be registered](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) in your subscription: -* `Microsoft.Attestation` -* `Microsoft.Compute` -* `Microsoft.Insights` -* `Microsoft.ManagedIdentity` -* `Microsoft.Network` + +- `Microsoft.Attestation` +- `Microsoft.Compute` +- `Microsoft.Insights` +- `Microsoft.ManagedIdentity` +- `Microsoft.Network` By default, Constellation tries to register these automatically if they haven't been registered before. To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: -* `*/register/action` \[1] -* `Microsoft.Authorization/roleAssignments/*` -* `Microsoft.Authorization/roleDefinitions/*` -* `Microsoft.ManagedIdentity/userAssignedIdentities/*` -* `Microsoft.Resources/subscriptions/resourcegroups/*` + +- `*/register/action` \[1] +- `Microsoft.Authorization/roleAssignments/*` +- `Microsoft.Authorization/roleDefinitions/*` +- `Microsoft.ManagedIdentity/userAssignedIdentities/*` +- `Microsoft.Resources/subscriptions/resourcegroups/*` The built-in `Owner` role is a superset of these permissions. To [create a Constellation cluster](../workflows/create.md#the-create-step), you need the following permissions: -* `Microsoft.Attestation/attestationProviders/*` -* `Microsoft.Compute/virtualMachineScaleSets/*` -* `Microsoft.Insights/components/*` -* `Microsoft.ManagedIdentity/userAssignedIdentities/*` -* `Microsoft.Network/loadBalancers/*` -* `Microsoft.Network/loadBalancers/backendAddressPools/*` -* `Microsoft.Network/networkSecurityGroups/*` -* `Microsoft.Network/publicIPAddresses/*` -* `Microsoft.Network/virtualNetworks/*` -* `Microsoft.Network/virtualNetworks/subnets/*` -* `Microsoft.Network/natGateways/*` + +- `Microsoft.Attestation/attestationProviders/*` +- `Microsoft.Compute/virtualMachineScaleSets/*` +- `Microsoft.Insights/components/*` +- `Microsoft.ManagedIdentity/userAssignedIdentities/*` +- `Microsoft.Network/loadBalancers/*` +- `Microsoft.Network/loadBalancers/backendAddressPools/*` +- `Microsoft.Network/networkSecurityGroups/*` +- `Microsoft.Network/publicIPAddresses/*` +- `Microsoft.Network/virtualNetworks/*` +- `Microsoft.Network/virtualNetworks/subnets/*` +- `Microsoft.Network/natGateways/*` The built-in `Contributor` role is a superset of these permissions. @@ -145,89 +148,91 @@ Follow Microsoft's guide on [understanding](https://learn.microsoft.com/en-us/az 1: You can omit `*/register/Action` if the resource providers mentioned above are already registered and the `ARM_SKIP_PROVIDER_REGISTRATION` environment variable is set to `true` when creating the IAM configuration. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: -* `iam.serviceAccountKeys.create` -* `iam.serviceAccountKeys.delete` -* `iam.serviceAccountKeys.get` -* `iam.serviceAccounts.create` -* `iam.serviceAccounts.delete` -* `iam.serviceAccounts.get` -* `resourcemanager.projects.getIamPolicy` -* `resourcemanager.projects.setIamPolicy` + +- `iam.serviceAccountKeys.create` +- `iam.serviceAccountKeys.delete` +- `iam.serviceAccountKeys.get` +- `iam.serviceAccounts.create` +- `iam.serviceAccounts.delete` +- `iam.serviceAccounts.get` +- `resourcemanager.projects.getIamPolicy` +- `resourcemanager.projects.setIamPolicy` Together, the built-in roles `roles/editor` and `roles/resourcemanager.projectIamAdmin` form a superset of these permissions. To [create a Constellation cluster](../workflows/create.md#the-create-step), you need the following permissions: -* `compute.addresses.createInternal` -* `compute.addresses.deleteInternal` -* `compute.addresses.get` -* `compute.addresses.useInternal` -* `compute.backendServices.create` -* `compute.backendServices.delete` -* `compute.backendServices.get` -* `compute.backendServices.use` -* `compute.disks.create` -* `compute.firewalls.create` -* `compute.firewalls.delete` -* `compute.firewalls.get` -* `compute.globalAddresses.create` -* `compute.globalAddresses.delete` -* `compute.globalAddresses.get` -* `compute.globalAddresses.use` -* `compute.globalForwardingRules.create` -* `compute.globalForwardingRules.delete` -* `compute.globalForwardingRules.get` -* `compute.globalForwardingRules.setLabels` -* `compute.globalOperations.get` -* `compute.healthChecks.create` -* `compute.healthChecks.delete` -* `compute.healthChecks.get` -* `compute.healthChecks.useReadOnly` -* `compute.instanceGroupManagers.create` -* `compute.instanceGroupManagers.delete` -* `compute.instanceGroupManagers.get` -* `compute.instanceGroups.create` -* `compute.instanceGroups.delete` -* `compute.instanceGroups.get` -* `compute.instanceGroups.use` -* `compute.instances.create` -* `compute.instances.setLabels` -* `compute.instances.setMetadata` -* `compute.instances.setTags` -* `compute.instanceTemplates.create` -* `compute.instanceTemplates.delete` -* `compute.instanceTemplates.get` -* `compute.instanceTemplates.useReadOnly` -* `compute.networks.create` -* `compute.networks.delete` -* `compute.networks.get` -* `compute.networks.updatePolicy` -* `compute.routers.create` -* `compute.routers.delete` -* `compute.routers.get` -* `compute.routers.update` -* `compute.subnetworks.create` -* `compute.subnetworks.delete` -* `compute.subnetworks.get` -* `compute.subnetworks.use` -* `compute.targetTcpProxies.create` -* `compute.targetTcpProxies.delete` -* `compute.targetTcpProxies.get` -* `compute.targetTcpProxies.use` -* `iam.serviceAccounts.actAs` + +- `compute.addresses.createInternal` +- `compute.addresses.deleteInternal` +- `compute.addresses.get` +- `compute.addresses.useInternal` +- `compute.backendServices.create` +- `compute.backendServices.delete` +- `compute.backendServices.get` +- `compute.backendServices.use` +- `compute.disks.create` +- `compute.firewalls.create` +- `compute.firewalls.delete` +- `compute.firewalls.get` +- `compute.globalAddresses.create` +- `compute.globalAddresses.delete` +- `compute.globalAddresses.get` +- `compute.globalAddresses.use` +- `compute.globalForwardingRules.create` +- `compute.globalForwardingRules.delete` +- `compute.globalForwardingRules.get` +- `compute.globalForwardingRules.setLabels` +- `compute.globalOperations.get` +- `compute.healthChecks.create` +- `compute.healthChecks.delete` +- `compute.healthChecks.get` +- `compute.healthChecks.useReadOnly` +- `compute.instanceGroupManagers.create` +- `compute.instanceGroupManagers.delete` +- `compute.instanceGroupManagers.get` +- `compute.instanceGroups.create` +- `compute.instanceGroups.delete` +- `compute.instanceGroups.get` +- `compute.instanceGroups.use` +- `compute.instances.create` +- `compute.instances.setLabels` +- `compute.instances.setMetadata` +- `compute.instances.setTags` +- `compute.instanceTemplates.create` +- `compute.instanceTemplates.delete` +- `compute.instanceTemplates.get` +- `compute.instanceTemplates.useReadOnly` +- `compute.networks.create` +- `compute.networks.delete` +- `compute.networks.get` +- `compute.networks.updatePolicy` +- `compute.routers.create` +- `compute.routers.delete` +- `compute.routers.get` +- `compute.routers.update` +- `compute.subnetworks.create` +- `compute.subnetworks.delete` +- `compute.subnetworks.get` +- `compute.subnetworks.use` +- `compute.targetTcpProxies.create` +- `compute.targetTcpProxies.delete` +- `compute.targetTcpProxies.get` +- `compute.targetTcpProxies.use` +- `iam.serviceAccounts.actAs` Together, the built-in roles `roles/editor`, `roles/compute.instanceAdmin` and `roles/resourcemanager.projectIamAdmin` form a superset of these permissions. Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + To set up a Constellation cluster, you need to perform two tasks that require permissions: create the infrastructure and create roles for cluster nodes. Both of these actions can be performed by different users, e.g., an administrator to create roles and a DevOps engineer to create the infrastructure. @@ -362,8 +367,8 @@ The built-in `PowerUserAccess` policy is a superset of these permissions. Follow Amazon's guide on [understanding](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [managing policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html). - - + + ### Authentication @@ -373,8 +378,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -390,8 +395,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -414,8 +419,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + **Testing** @@ -431,9 +436,9 @@ aws configure Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - + - + ## Next steps diff --git a/docs/versioned_docs/version-2.8/workflows/config.md b/docs/versioned_docs/version-2.8/workflows/config.md index ca1719b85..3330abe8a 100644 --- a/docs/versioned_docs/version-2.8/workflows/config.md +++ b/docs/versioned_docs/version-2.8/workflows/config.md @@ -14,29 +14,29 @@ Before you can create your cluster, you need to configure the identity and acces You can generate a configuration file for your CSP by using the following CLI command: - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate aws ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. @@ -47,25 +47,25 @@ You can also automatically generate a configuration file by adding the `--genera ## Choosing a VM type Constellation supports the following VM types: - - + + 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. You can also run `constellation config instance-types` to get the list of all supported options. - - + + 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 with a minimum of 4 vCPUs from the [C2D](https://cloud.google.com/compute/docs/compute-optimized-machines#c2d_machine_types) or [N2D](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) family. You can run `constellation config instance-types` to get the list of all supported options. - - + + By default, Constellation uses `m6a.xlarge` 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 nitroTPM-enabled machines with a minimum of 4 vCPUs (`xlarge` or larger). Refer to the [list of nitroTPM-enabled instance types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enable-nitrotpm-prerequisites.html) or run `constellation config instance-types` to get the list of all supported options. - - + + Fill the desired VM type into the **instanceType** field in the `constellation-conf.yml` file. @@ -79,8 +79,8 @@ See also Constellation's [Kubernetes support policy](../architecture/versions.md You can create an IAM configuration for your cluster automatically using the `constellation iam create` command. If you haven't generated a configuration file yet, you can do so by adding the `--generate-config` flag to the command. This creates a configuration file and populates it with the created IAM values. - - + + You must be authenticated with the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -104,8 +104,8 @@ Paste the output into the corresponding fields of the `constellation-conf.yaml` Since `clientSecretValue` is a sensitive value, you can leave it empty in the configuration file and pass it via an environment variable instead. To this end, create the environment variable `CONSTELL_AZURE_CLIENT_SECRET_VALUE` and set it to the secret value. ::: - - + + You must be authenticated with the [GCP CLI](https://cloud.google.com/sdk/gcloud) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -119,8 +119,8 @@ Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [AWS CLI](https://aws.amazon.com/en/cli/) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -144,16 +144,16 @@ You can find a list of all [regions in AWS's documentation](https://docs.aws.ama Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + +
Alternatively, you can manually create the IAM configuration on your CSP. The following describes the configuration fields and how you obtain the required information or create the required resources. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -198,9 +198,9 @@ The following describes the configuration fields and how you obtain the required Since this is a sensitive value, alternatively you can leave `clientSecretValue` empty in the configuration file and pass it via an environment variable instead. To this end, create the environment variable `CONSTELL_AZURE_CLIENT_SECRET_VALUE` and set it to the secret value. ::: - + - + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -224,9 +224,9 @@ The following describes the configuration fields and how you obtain the required Afterward, create and download a new JSON key for this service account. Place the downloaded file in your Constellation workspace, and set the config parameter to the filename, e.g., `constellation-129857-15343dba46cb.json`. - + - + * **region**: The name of your chosen AWS data center region, e.g., `us-east-2`. @@ -257,9 +257,9 @@ The following describes the configuration fields and how you obtain the required Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.worker_node_policy`. - + - +
Now that you've configured your CSP, you can [create your cluster](./create.md). diff --git a/docs/versioned_docs/version-2.8/workflows/create.md b/docs/versioned_docs/version-2.8/workflows/create.md index 33d2f12f8..5c4dd2948 100644 --- a/docs/versioned_docs/version-2.8/workflows/create.md +++ b/docs/versioned_docs/version-2.8/workflows/create.md @@ -26,8 +26,8 @@ Before you create the cluster, make sure to have a [valid configuration file](./ ### Create - - + + Choose the initial size of your cluster. The following command creates a cluster with one control-plane and two worker nodes: @@ -40,8 +40,8 @@ For details on the flags, consult the command help via `constellation create -h` *create* stores your cluster's state in a [`constellation-terraform`](../architecture/orchestration.md#cluster-creation-process) directory in your workspace. - - + + Terraform allows for an easier GitOps integration as well as meeting regulatory requirements. Since the Constellation CLI also uses Terraform under the hood, you can reuse the same Terraform files. @@ -80,8 +80,8 @@ CONSTELL_CSP=$(cat constellation-conf.yaml | yq ".provider | keys | .[0]") jq --null-input --arg cloudprovider "$CONSTELL_CSP" --arg ip "$CONSTELL_IP" --arg initsecret "$CONSTELL_INIT_SECRET" '{"cloudprovider":$cloudprovider,"ip":$ip,"initsecret":$initsecret}' > constellation-id.json ``` - - + + ## The *init* step diff --git a/docs/versioned_docs/version-2.8/workflows/recovery.md b/docs/versioned_docs/version-2.8/workflows/recovery.md index c26fb32eb..35596b8c9 100644 --- a/docs/versioned_docs/version-2.8/workflows/recovery.md +++ b/docs/versioned_docs/version-2.8/workflows/recovery.md @@ -16,8 +16,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via [cloud logging](troubleshooting.md#cloud-logging). In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -51,8 +51,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -87,8 +87,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, open the AWS console to view all Auto Scaling Groups (ASGs) in the region of your cluster. Select the ASG of the control plane `--control-plane` and check that enough members are in a *Running* state. @@ -118,8 +118,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + ## Recover a cluster diff --git a/docs/versioned_docs/version-2.8/workflows/scale.md b/docs/versioned_docs/version-2.8/workflows/scale.md index 9531e90c9..46b048870 100644 --- a/docs/versioned_docs/version-2.8/workflows/scale.md +++ b/docs/versioned_docs/version-2.8/workflows/scale.md @@ -48,30 +48,30 @@ kubectl -n kube-system get nodes Alternatively, you can manually scale your cluster up or down: - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + 1. Go to Auto Scaling Groups and select the worker ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + ## Control-plane node scaling @@ -79,30 +79,30 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - + - + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + 1. Go to Auto Scaling Groups and select the control-plane ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/versioned_docs/version-2.8/workflows/storage.md b/docs/versioned_docs/version-2.8/workflows/storage.md index d0e5b188f..be9998676 100644 --- a/docs/versioned_docs/version-2.8/workflows/storage.md +++ b/docs/versioned_docs/version-2.8/workflows/storage.md @@ -21,14 +21,14 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as ReadWriteOnce, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. @@ -36,8 +36,8 @@ This includes support for [volume snapshots](https://cloud.google.com/kubernetes You can use them to bring a volume back to a prior state or provision new volumes. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for information about the configuration. - - + + :::caution @@ -47,8 +47,8 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction) or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -57,8 +57,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The Constellation CLI automatically installs Constellation's CSI driver for the selected CSP in your cluster. If you don't need a CSI driver or wish to deploy your own, you can disable the automatic installation by setting `deployCSIDriver` to `false` in your Constellation config file. - - + + Azure comes with two storage classes by default. @@ -86,8 +86,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + GCP comes with two storage classes by default. @@ -115,8 +115,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + :::caution @@ -126,8 +126,8 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + 1. Create a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) @@ -186,8 +186,8 @@ The default storage class is responsible for all persistent volume claims that d Constellation creates a storage class with encryption enabled and sets this as the default class. In case you wish to change it, follow the steps below: - - + + 1. List the storage classes in your cluster: @@ -233,8 +233,8 @@ In case you wish to change it, follow the steps below: integrity-encrypted-rwo (default) azuredisk.csi.confidential.cloud Delete Immediate false 1d ``` - - + + 1. List the storage classes in your cluster: @@ -280,8 +280,8 @@ In case you wish to change it, follow the steps below: integrity-encrypted-rwo (default) gcp.csi.confidential.cloud Delete Immediate false 1d ``` - - + + :::caution @@ -291,5 +291,5 @@ You may use other (non-confidential) CSI drivers that are compatible with Kubern ::: - - + + diff --git a/docs/versioned_docs/version-2.8/workflows/terminate.md b/docs/versioned_docs/version-2.8/workflows/terminate.md index 6c1eebb14..f33489ca5 100644 --- a/docs/versioned_docs/version-2.8/workflows/terminate.md +++ b/docs/versioned_docs/version-2.8/workflows/terminate.md @@ -16,8 +16,8 @@ All ephemeral storage and state of your cluster will be lost. Make sure any data ::: - - + + Terminate the cluster by running: ```bash @@ -40,8 +40,8 @@ resources manually. Just run the `terminate` command again afterward to continue ::: - - + + Terminate the cluster by running: ```bash @@ -56,5 +56,5 @@ rm constellation-id.json constellation-admin.conf Only the `constellation-mastersecret.json` and the configuration file remain. - - + + diff --git a/docs/versioned_docs/version-2.8/workflows/troubleshooting.md b/docs/versioned_docs/version-2.8/workflows/troubleshooting.md index 2ddf3335d..cd095be28 100644 --- a/docs/versioned_docs/version-2.8/workflows/troubleshooting.md +++ b/docs/versioned_docs/version-2.8/workflows/troubleshooting.md @@ -75,8 +75,8 @@ To provide information during early stages of a node's boot process, Constellati You can view this information in the following places: - - + + 1. In your Azure subscription find the Constellation resource group. 2. Inside the resource group find the Application Insights resource called `constellation-insights-*`. @@ -86,8 +86,8 @@ You can view this information in the following places: To **find the disk UUIDs** use the following query: `traces | where message contains "Disk UUID"` - - + + 1. Select the project that hosts Constellation. 2. Go to the `Compute Engine` service. @@ -102,16 +102,16 @@ Constellation uses the default bucket to store logs. Its [default retention peri ::: - - + + 1. Open [AWS CloudWatch](https://console.aws.amazon.com/cloudwatch/home) 2. Select [Log Groups](https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups) 3. Select the log group that matches the name of your cluster. 4. Select the log stream for control or worker type nodes. - - + + ### Node shell access diff --git a/docs/versioned_docs/version-2.9/architecture/attestation.md b/docs/versioned_docs/version-2.9/architecture/attestation.md index 07ac3aa72..592063193 100644 --- a/docs/versioned_docs/version-2.9/architecture/attestation.md +++ b/docs/versioned_docs/version-2.9/architecture/attestation.md @@ -121,8 +121,8 @@ Constellation allows to specify in the config which measurements should be enfor Enforcing non-reproducible measurements controlled by the cloud provider means that changes in these values require manual updates to the cluster's config. By default, Constellation only enforces measurements that are stable values produced by the infrastructure or by Constellation directly. - - + + Constellation uses the [vTPM](https://docs.microsoft.com/en-us/azure/virtual-machines/trusted-launch#vtpm) feature of Azure CVMs for runtime measurements. This vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. @@ -152,8 +152,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://cloud.google.com/compute/confidential-vm/docs/about-cvm) feature of CVMs on GCP for runtime measurements. Note that this vTPM doesn't run inside the hardware-protected CVM context, but is emulated by the hypervisor. @@ -185,8 +185,8 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + Constellation uses the [vTPM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html) (NitroTPM) feature of the [AWS Nitro System](http://aws.amazon.com/ec2/nitro/) on AWS for runtime measurements. @@ -217,16 +217,16 @@ The latter means that the value can be generated offline and compared to the one | 15 | ClusterID | Constellation Bootstrapper | Yes | | 16–23 | Unused | - | - | - - + + ### CVM verification To verify the integrity of the received attestation statement, a chain of trust from the CVM technology to the interface providing the statement has to be established. For verification of the CVM technology, Constellation may expose additional options in its config file. - - + + On Azure, AMD SEV-SNP is used to provide runtime encryption to the VMs. An SEV-SNP attestation report is used to establish trust in the vTPM running inside the VM. @@ -248,18 +248,18 @@ You may customize certain parameters for verification of the attestation stateme More explicitly, it controls the verification of the `IDKeyDigest` value in the SEV-SNP attestation report. You can provide a list of accepted key digests and specify a policy on how this list is compared against the reported `IDKeyDigest`. - - + + There is no additional configuration available for GCP. - - + + There is no additional configuration available for AWS. - - + + ## Cluster attestation diff --git a/docs/versioned_docs/version-2.9/getting-started/first-steps-local.md b/docs/versioned_docs/version-2.9/getting-started/first-steps-local.md index 8fcd71811..f9cfa5cd3 100644 --- a/docs/versioned_docs/version-2.9/getting-started/first-steps-local.md +++ b/docs/versioned_docs/version-2.9/getting-started/first-steps-local.md @@ -45,8 +45,8 @@ sudo iptables -P FORWARD ACCEPT ## Create a cluster - - + + 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/). @@ -74,8 +74,8 @@ 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. - - + + 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. @@ -153,8 +153,8 @@ attaching persistent storage, or autoscaling aren't available. export KUBECONFIG="$PWD/constellation-admin.conf" ``` - - + + ## Connect to the cluster @@ -207,8 +207,8 @@ worker-0 Ready 32s v1.24.6 ## Terminate your cluster - - + + Once you are done, you can clean up the created resources using the following command: @@ -219,8 +219,8 @@ 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. - - + + Once you are done, you can clean up the created resources using the following command: @@ -248,8 +248,8 @@ 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. - - + + ## Troubleshooting diff --git a/docs/versioned_docs/version-2.9/getting-started/first-steps.md b/docs/versioned_docs/version-2.9/getting-started/first-steps.md index 0329c5776..a29ff276c 100644 --- a/docs/versioned_docs/version-2.9/getting-started/first-steps.md +++ b/docs/versioned_docs/version-2.9/getting-started/first-steps.md @@ -15,39 +15,39 @@ If you encounter any problem with the following steps, make sure to use the [lat 1. Create the [configuration file](../workflows/config.md) for your cloud provider. - + - + ```bash constellation config generate azure ``` - + - + ```bash constellation config generate gcp ``` - + - + ```bash constellation config generate aws ``` - + - + 2. Create your [IAM configuration](../workflows/config.md#creating-an-iam-configuration). - + - + ```bash constellation iam create azure --region=westus --resourceGroup=constellTest --servicePrincipal=spTest --update-config @@ -62,9 +62,9 @@ If you encounter any problem with the following steps, make sure to use the [lat * `westeurope` * `southeastasia` - + - + ```bash constellation iam create gcp --projectID=yourproject-12345 --zone=europe-west2-a --serviceAccountID=constell-test --update-config @@ -74,9 +74,9 @@ If you encounter any problem with the following steps, make sure to use the [lat Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. You can find a [list of all regions in Google's documentation](https://cloud.google.com/compute/docs/regions-zones#available), which you can filter by machine type `C2D` or `N2D`. - + - + ```bash constellation iam create aws --zone=us-east-2a --prefix=constellTest --update-config @@ -103,8 +103,8 @@ If you encounter any problem with the following steps, make sure to use the [lat You can find a list of all [regions in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). - - + + :::tip To learn about all options you have for managing IAM resources and Constellation configuration, see the [Configuration workflow](../workflows/config.md). diff --git a/docs/versioned_docs/version-2.9/getting-started/install.md b/docs/versioned_docs/version-2.9/getting-started/install.md index 11167c34c..2aa274b98 100644 --- a/docs/versioned_docs/version-2.9/getting-started/install.md +++ b/docs/versioned_docs/version-2.9/getting-started/install.md @@ -18,8 +18,8 @@ Make sure the following requirements are met: The CLI executable is available at [GitHub](https://github.com/edgelesssys/constellation/releases). Install it with the following commands: - - + + 1. Download the CLI: @@ -35,8 +35,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-amd64 /usr/local/bin/constellation ``` - - + + 1. Download the CLI: @@ -52,9 +52,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-linux-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -70,9 +70,9 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-arm64 /usr/local/bin/constellation ``` - + - + 1. Download the CLI: @@ -88,8 +88,8 @@ curl -LO https://github.com/edgelesssys/constellation/releases/latest/download/c sudo install constellation-darwin-amd64 /usr/local/bin/constellation ``` - - + + :::tip The CLI supports autocompletion for various shells. To set it up, run `constellation completion` and follow the given steps. @@ -105,39 +105,42 @@ If you don't have a cloud subscription, you can also set up a [local Constellati ### Required permissions - - + + The following [resource providers need to be registered](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider) in your subscription: -* `Microsoft.Attestation` -* `Microsoft.Compute` -* `Microsoft.Insights` -* `Microsoft.ManagedIdentity` -* `Microsoft.Network` + +- `Microsoft.Attestation` +- `Microsoft.Compute` +- `Microsoft.Insights` +- `Microsoft.ManagedIdentity` +- `Microsoft.Network` By default, Constellation tries to register these automatically if they haven't been registered before. To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: -* `*/register/action` \[1] -* `Microsoft.Authorization/roleAssignments/*` -* `Microsoft.Authorization/roleDefinitions/*` -* `Microsoft.ManagedIdentity/userAssignedIdentities/*` -* `Microsoft.Resources/subscriptions/resourcegroups/*` + +- `*/register/action` \[1] +- `Microsoft.Authorization/roleAssignments/*` +- `Microsoft.Authorization/roleDefinitions/*` +- `Microsoft.ManagedIdentity/userAssignedIdentities/*` +- `Microsoft.Resources/subscriptions/resourcegroups/*` The built-in `Owner` role is a superset of these permissions. To [create a Constellation cluster](../workflows/create.md#the-create-step), you need the following permissions: -* `Microsoft.Attestation/attestationProviders/*` -* `Microsoft.Compute/virtualMachineScaleSets/*` -* `Microsoft.Insights/components/*` -* `Microsoft.ManagedIdentity/userAssignedIdentities/*` -* `Microsoft.Network/loadBalancers/*` -* `Microsoft.Network/loadBalancers/backendAddressPools/*` -* `Microsoft.Network/networkSecurityGroups/*` -* `Microsoft.Network/publicIPAddresses/*` -* `Microsoft.Network/virtualNetworks/*` -* `Microsoft.Network/virtualNetworks/subnets/*` -* `Microsoft.Network/natGateways/*` + +- `Microsoft.Attestation/attestationProviders/*` +- `Microsoft.Compute/virtualMachineScaleSets/*` +- `Microsoft.Insights/components/*` +- `Microsoft.ManagedIdentity/userAssignedIdentities/*` +- `Microsoft.Network/loadBalancers/*` +- `Microsoft.Network/loadBalancers/backendAddressPools/*` +- `Microsoft.Network/networkSecurityGroups/*` +- `Microsoft.Network/publicIPAddresses/*` +- `Microsoft.Network/virtualNetworks/*` +- `Microsoft.Network/virtualNetworks/subnets/*` +- `Microsoft.Network/natGateways/*` The built-in `Contributor` role is a superset of these permissions. @@ -145,89 +148,91 @@ Follow Microsoft's guide on [understanding](https://learn.microsoft.com/en-us/az 1: You can omit `*/register/Action` if the resource providers mentioned above are already registered and the `ARM_SKIP_PROVIDER_REGISTRATION` environment variable is set to `true` when creating the IAM configuration. - - + + Create a new project for Constellation or use an existing one. Enable the [Compute Engine API](https://console.cloud.google.com/apis/library/compute.googleapis.com) on it. To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: -* `iam.serviceAccountKeys.create` -* `iam.serviceAccountKeys.delete` -* `iam.serviceAccountKeys.get` -* `iam.serviceAccounts.create` -* `iam.serviceAccounts.delete` -* `iam.serviceAccounts.get` -* `resourcemanager.projects.getIamPolicy` -* `resourcemanager.projects.setIamPolicy` + +- `iam.serviceAccountKeys.create` +- `iam.serviceAccountKeys.delete` +- `iam.serviceAccountKeys.get` +- `iam.serviceAccounts.create` +- `iam.serviceAccounts.delete` +- `iam.serviceAccounts.get` +- `resourcemanager.projects.getIamPolicy` +- `resourcemanager.projects.setIamPolicy` Together, the built-in roles `roles/editor` and `roles/resourcemanager.projectIamAdmin` form a superset of these permissions. To [create a Constellation cluster](../workflows/create.md#the-create-step), you need the following permissions: -* `compute.addresses.createInternal` -* `compute.addresses.deleteInternal` -* `compute.addresses.get` -* `compute.addresses.useInternal` -* `compute.backendServices.create` -* `compute.backendServices.delete` -* `compute.backendServices.get` -* `compute.backendServices.use` -* `compute.disks.create` -* `compute.firewalls.create` -* `compute.firewalls.delete` -* `compute.firewalls.get` -* `compute.globalAddresses.create` -* `compute.globalAddresses.delete` -* `compute.globalAddresses.get` -* `compute.globalAddresses.use` -* `compute.globalForwardingRules.create` -* `compute.globalForwardingRules.delete` -* `compute.globalForwardingRules.get` -* `compute.globalForwardingRules.setLabels` -* `compute.globalOperations.get` -* `compute.healthChecks.create` -* `compute.healthChecks.delete` -* `compute.healthChecks.get` -* `compute.healthChecks.useReadOnly` -* `compute.instanceGroupManagers.create` -* `compute.instanceGroupManagers.delete` -* `compute.instanceGroupManagers.get` -* `compute.instanceGroups.create` -* `compute.instanceGroups.delete` -* `compute.instanceGroups.get` -* `compute.instanceGroups.use` -* `compute.instances.create` -* `compute.instances.setLabels` -* `compute.instances.setMetadata` -* `compute.instances.setTags` -* `compute.instanceTemplates.create` -* `compute.instanceTemplates.delete` -* `compute.instanceTemplates.get` -* `compute.instanceTemplates.useReadOnly` -* `compute.networks.create` -* `compute.networks.delete` -* `compute.networks.get` -* `compute.networks.updatePolicy` -* `compute.routers.create` -* `compute.routers.delete` -* `compute.routers.get` -* `compute.routers.update` -* `compute.subnetworks.create` -* `compute.subnetworks.delete` -* `compute.subnetworks.get` -* `compute.subnetworks.use` -* `compute.targetTcpProxies.create` -* `compute.targetTcpProxies.delete` -* `compute.targetTcpProxies.get` -* `compute.targetTcpProxies.use` -* `iam.serviceAccounts.actAs` + +- `compute.addresses.createInternal` +- `compute.addresses.deleteInternal` +- `compute.addresses.get` +- `compute.addresses.useInternal` +- `compute.backendServices.create` +- `compute.backendServices.delete` +- `compute.backendServices.get` +- `compute.backendServices.use` +- `compute.disks.create` +- `compute.firewalls.create` +- `compute.firewalls.delete` +- `compute.firewalls.get` +- `compute.globalAddresses.create` +- `compute.globalAddresses.delete` +- `compute.globalAddresses.get` +- `compute.globalAddresses.use` +- `compute.globalForwardingRules.create` +- `compute.globalForwardingRules.delete` +- `compute.globalForwardingRules.get` +- `compute.globalForwardingRules.setLabels` +- `compute.globalOperations.get` +- `compute.healthChecks.create` +- `compute.healthChecks.delete` +- `compute.healthChecks.get` +- `compute.healthChecks.useReadOnly` +- `compute.instanceGroupManagers.create` +- `compute.instanceGroupManagers.delete` +- `compute.instanceGroupManagers.get` +- `compute.instanceGroups.create` +- `compute.instanceGroups.delete` +- `compute.instanceGroups.get` +- `compute.instanceGroups.use` +- `compute.instances.create` +- `compute.instances.setLabels` +- `compute.instances.setMetadata` +- `compute.instances.setTags` +- `compute.instanceTemplates.create` +- `compute.instanceTemplates.delete` +- `compute.instanceTemplates.get` +- `compute.instanceTemplates.useReadOnly` +- `compute.networks.create` +- `compute.networks.delete` +- `compute.networks.get` +- `compute.networks.updatePolicy` +- `compute.routers.create` +- `compute.routers.delete` +- `compute.routers.get` +- `compute.routers.update` +- `compute.subnetworks.create` +- `compute.subnetworks.delete` +- `compute.subnetworks.get` +- `compute.subnetworks.use` +- `compute.targetTcpProxies.create` +- `compute.targetTcpProxies.delete` +- `compute.targetTcpProxies.get` +- `compute.targetTcpProxies.use` +- `iam.serviceAccounts.actAs` Together, the built-in roles `roles/editor`, `roles/compute.instanceAdmin` and `roles/resourcemanager.projectIamAdmin` form a superset of these permissions. Follow Google's guide on [understanding](https://cloud.google.com/iam/docs/understanding-roles) and [assigning roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access). - - + + To set up a Constellation cluster, you need to perform two tasks that require permissions: create the infrastructure and create roles for cluster nodes. Both of these actions can be performed by different users, e.g., an administrator to create roles and a DevOps engineer to create the infrastructure. @@ -362,8 +367,8 @@ The built-in `PowerUserAccess` policy is a superset of these permissions. Follow Amazon's guide on [understanding](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) and [managing policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html). - - + + ### Authentication @@ -373,8 +378,8 @@ You need to authenticate with your CSP. The following lists the required steps f The steps for a *testing* environment are simpler. However, they may expose secrets to the CSP. If in doubt, follow the *production* steps. ::: - - + + **Testing** @@ -390,8 +395,8 @@ az login Other options are described in Azure's [authentication guide](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli). - - + + **Testing** @@ -414,8 +419,8 @@ Use one of the following options on a trusted machine: Follow [Google's guide](https://cloud.google.com/docs/authentication/production#manually) for setting up your credentials. - - + + **Testing** @@ -431,9 +436,9 @@ aws configure Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - + - + ## Next steps diff --git a/docs/versioned_docs/version-2.9/workflows/config.md b/docs/versioned_docs/version-2.9/workflows/config.md index 7d4a297fb..43313d88e 100644 --- a/docs/versioned_docs/version-2.9/workflows/config.md +++ b/docs/versioned_docs/version-2.9/workflows/config.md @@ -14,49 +14,49 @@ Before you can create your cluster, you need to configure the identity and acces You can generate a configuration file for your CSP by using the following CLI command: - - + + ```bash constellation config generate azure ``` - - + + ```bash constellation config generate gcp ``` - - + + ```bash constellation config generate aws ``` - - + + This creates the file `constellation-conf.yaml` in the current directory. ## Choosing a VM type Constellation supports the following VM types: - - + + 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. You can also run `constellation config instance-types` to get the list of all supported options. - - + + 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 with a minimum of 4 vCPUs from the [C2D](https://cloud.google.com/compute/docs/compute-optimized-machines#c2d_machine_types) or [N2D](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) family. You can run `constellation config instance-types` to get the list of all supported options. - - + + By default, Constellation uses `m6a.xlarge` 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. @@ -75,8 +75,8 @@ AWS is currently investigating the issue. SNP-based attestation will be enabled as soon as a fix is verified. ::: - - + + Fill the desired VM type into the **instanceType** field in the `constellation-conf.yml` file. @@ -90,8 +90,8 @@ See also Constellation's [Kubernetes support policy](../architecture/versions.md You can create an IAM configuration for your cluster automatically using the `constellation iam create` command. If you already have a Constellation configuration file, you can add the `--update-config` flag to the command. This writes the needed IAM fields into your configuration. Furthermore, the flag updates the zone/region of the configuration if it hasn't been set yet. - - + + You must be authenticated with the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -111,8 +111,8 @@ Note that CVMs are currently only supported in a few regions, check [Azure's pro Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [GCP CLI](https://cloud.google.com/sdk/gcloud) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -126,8 +126,8 @@ Note that only regions offering CVMs of the `C2D` or `N2D` series are supported. Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + + You must be authenticated with the [AWS CLI](https://aws.amazon.com/en/cli/) in the shell session with a user that has the [required permissions for IAM creation](../getting-started/install.md#set-up-cloud-credentials). @@ -151,16 +151,16 @@ You can find a list of all [regions in AWS's documentation](https://docs.aws.ama Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - - + +
Alternatively, you can manually create the IAM configuration on your CSP. The following describes the configuration fields and how you obtain the required information or create the required resources. - - + + * **subscription**: The UUID of your Azure subscription, e.g., `8b8bd01f-efd9-4113-9bd1-c82137c32da7`. @@ -189,9 +189,9 @@ The following describes the configuration fields and how you obtain the required The user-assigned identity is used by instances of the cluster to access other cloud resources. For more information about managed identities refer to [Azure's documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities). - + - + * **project**: The ID of your GCP project, e.g., `constellation-129857`. @@ -215,9 +215,9 @@ The following describes the configuration fields and how you obtain the required Afterward, create and download a new JSON key for this service account. Place the downloaded file in your Constellation workspace, and set the config parameter to the filename, e.g., `constellation-129857-15343dba46cb.json`. - + - + * **region**: The name of your chosen AWS data center region, e.g., `us-east-2`. @@ -248,9 +248,9 @@ The following describes the configuration fields and how you obtain the required Alternatively, you can create the AWS profile with a tool of your choice. Use the JSON policy in [main.tf](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam/main.tf) in the resource `aws_iam_policy.worker_node_policy`. - + - +
Now that you've configured your CSP, you can [create your cluster](./create.md). diff --git a/docs/versioned_docs/version-2.9/workflows/create.md b/docs/versioned_docs/version-2.9/workflows/create.md index 33d2f12f8..5c4dd2948 100644 --- a/docs/versioned_docs/version-2.9/workflows/create.md +++ b/docs/versioned_docs/version-2.9/workflows/create.md @@ -26,8 +26,8 @@ Before you create the cluster, make sure to have a [valid configuration file](./ ### Create - - + + Choose the initial size of your cluster. The following command creates a cluster with one control-plane and two worker nodes: @@ -40,8 +40,8 @@ For details on the flags, consult the command help via `constellation create -h` *create* stores your cluster's state in a [`constellation-terraform`](../architecture/orchestration.md#cluster-creation-process) directory in your workspace. - - + + Terraform allows for an easier GitOps integration as well as meeting regulatory requirements. Since the Constellation CLI also uses Terraform under the hood, you can reuse the same Terraform files. @@ -80,8 +80,8 @@ CONSTELL_CSP=$(cat constellation-conf.yaml | yq ".provider | keys | .[0]") jq --null-input --arg cloudprovider "$CONSTELL_CSP" --arg ip "$CONSTELL_IP" --arg initsecret "$CONSTELL_INIT_SECRET" '{"cloudprovider":$cloudprovider,"ip":$ip,"initsecret":$initsecret}' > constellation-id.json ``` - - + + ## The *init* step diff --git a/docs/versioned_docs/version-2.9/workflows/recovery.md b/docs/versioned_docs/version-2.9/workflows/recovery.md index c26fb32eb..35596b8c9 100644 --- a/docs/versioned_docs/version-2.9/workflows/recovery.md +++ b/docs/versioned_docs/version-2.9/workflows/recovery.md @@ -16,8 +16,8 @@ You can check the health status of the nodes via the cloud service provider (CSP Constellation provides logging information on the boot process and status via [cloud logging](troubleshooting.md#cloud-logging). In the following, you'll find detailed descriptions for identifying clusters stuck in recovery for each CSP. - - + + In the Azure portal, find the cluster's resource group. Inside the resource group, open the control plane *Virtual machine scale set* `constellation-scale-set-controlplanes-`. @@ -51,8 +51,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, check that the control plane *Instance Group* has enough members in a *Ready* state. In the GCP Console, go to **Instance Groups** and check the group for the cluster's control plane `-control-plane-`. @@ -87,8 +87,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + First, open the AWS console to view all Auto Scaling Groups (ASGs) in the region of your cluster. Select the ASG of the control plane `--control-plane` and check that enough members are in a *Running* state. @@ -118,8 +118,8 @@ If this fails due to an unhealthy control plane, you will see log messages simil This means that you have to recover the node manually. - - + + ## Recover a cluster diff --git a/docs/versioned_docs/version-2.9/workflows/scale.md b/docs/versioned_docs/version-2.9/workflows/scale.md index 06898ad0c..63b727c7d 100644 --- a/docs/versioned_docs/version-2.9/workflows/scale.md +++ b/docs/versioned_docs/version-2.9/workflows/scale.md @@ -51,30 +51,30 @@ kubectl -n kube-system get nodes Alternatively, you can manually scale your cluster up or down: - - + + 1. Find your Constellation resource group. 2. Select the `scale-set-workers`. 3. Go to **settings** and **scaling**. 4. Set the new **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **worker** instance group. 3. Set the new **number of instances** and **save**. - - + + 1. Go to Auto Scaling Groups and select the worker ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + ## Control-plane node scaling @@ -82,30 +82,30 @@ Control-plane nodes can **only be scaled manually and only scaled up**! To increase the number of control-plane nodes, follow these steps: - + - + 1. Find your Constellation resource group. 2. Select the `scale-set-controlplanes`. 3. Go to **settings** and **scaling**. 4. Set the new (increased) **instance count** and **save**. - - + + 1. In Compute Engine go to [Instance Groups](https://console.cloud.google.com/compute/instanceGroups/). 2. **Edit** the **control-plane** instance group. 3. Set the new (increased) **number of instances** and **save**. - - + + 1. Go to Auto Scaling Groups and select the control-plane ASG to scale up. 2. Click **Edit** 3. Set the new (increased) **Desired capacity** and **Update**. - - + + If you scale down the number of control-planes nodes, the removed nodes won't be able to exit the `etcd` cluster correctly. This will endanger the quorum that's required to run a stable Kubernetes control plane. diff --git a/docs/versioned_docs/version-2.9/workflows/storage.md b/docs/versioned_docs/version-2.9/workflows/storage.md index 9e3d96346..06fbc4de6 100644 --- a/docs/versioned_docs/version-2.9/workflows/storage.md +++ b/docs/versioned_docs/version-2.9/workflows/storage.md @@ -21,30 +21,30 @@ For more details see [encrypted persistent storage](../architecture/encrypted-st Constellation supports the following drivers, which offer node-level encryption and optional integrity protection. - - + + **Constellation CSI driver for Azure Disk**: Mount Azure [Disk Storage](https://azure.microsoft.com/en-us/services/storage/disks/#overview) into your Constellation cluster. See the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-azuredisk-csi-driver) for more information. Since Azure Disks are mounted as `ReadWriteOnce`, they're only available to a single pod. - - + + **Constellation CSI driver for GCP Persistent Disk**: Mount [Persistent Disk](https://cloud.google.com/persistent-disk) block storage into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-gcp-compute-persistent-disk-csi-driver) for more information. - - + + **Constellation CSI driver for AWS Elastic Block Store** Mount [Elastic Block Store](https://aws.amazon.com/ebs/) storage volumes into your Constellation cluster. Follow the instructions on how to [install the Constellation CSI driver](#installation) or check out the [repository](https://github.com/edgelesssys/constellation-aws-ebs-csi-driver) for more information. - - + + Note that in case the options above aren't a suitable solution for you, Constellation is compatible with all other CSI-based storage options. For example, you can use [AWS EFS](https://docs.aws.amazon.com/en_en/eks/latest/userguide/efs-csi.html), [Azure Files](https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction), or [GCP Filestore](https://cloud.google.com/filestore) with Constellation out of the box. Constellation is just not providing transparent encryption on the node level for these storage types yet. @@ -53,8 +53,8 @@ Note that in case the options above aren't a suitable solution for you, Constell The Constellation CLI automatically installs Constellation's CSI driver for the selected CSP in your cluster. If you don't need a CSI driver or wish to deploy your own, you can disable the automatic installation by setting `deployCSIDriver` to `false` in your Constellation config file. - - + + Azure comes with two storage classes by default. @@ -82,8 +82,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + GCP comes with two storage classes by default. @@ -111,8 +111,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + AWS comes with two storage classes by default. @@ -140,8 +140,8 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - + + 1. Create a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) diff --git a/docs/versioned_docs/version-2.9/workflows/terminate.md b/docs/versioned_docs/version-2.9/workflows/terminate.md index 6c1eebb14..f33489ca5 100644 --- a/docs/versioned_docs/version-2.9/workflows/terminate.md +++ b/docs/versioned_docs/version-2.9/workflows/terminate.md @@ -16,8 +16,8 @@ All ephemeral storage and state of your cluster will be lost. Make sure any data ::: - - + + Terminate the cluster by running: ```bash @@ -40,8 +40,8 @@ resources manually. Just run the `terminate` command again afterward to continue ::: - - + + Terminate the cluster by running: ```bash @@ -56,5 +56,5 @@ rm constellation-id.json constellation-admin.conf Only the `constellation-mastersecret.json` and the configuration file remain. - - + + diff --git a/docs/versioned_docs/version-2.9/workflows/troubleshooting.md b/docs/versioned_docs/version-2.9/workflows/troubleshooting.md index 2ddf3335d..cd095be28 100644 --- a/docs/versioned_docs/version-2.9/workflows/troubleshooting.md +++ b/docs/versioned_docs/version-2.9/workflows/troubleshooting.md @@ -75,8 +75,8 @@ To provide information during early stages of a node's boot process, Constellati You can view this information in the following places: - - + + 1. In your Azure subscription find the Constellation resource group. 2. Inside the resource group find the Application Insights resource called `constellation-insights-*`. @@ -86,8 +86,8 @@ You can view this information in the following places: To **find the disk UUIDs** use the following query: `traces | where message contains "Disk UUID"` - - + + 1. Select the project that hosts Constellation. 2. Go to the `Compute Engine` service. @@ -102,16 +102,16 @@ Constellation uses the default bucket to store logs. Its [default retention peri ::: - - + + 1. Open [AWS CloudWatch](https://console.aws.amazon.com/cloudwatch/home) 2. Select [Log Groups](https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups) 3. Select the log group that matches the name of your cluster. 4. Select the log stream for control or worker type nodes. - - + + ### Node shell access