From 6359e46dd5ee7a875a15a76674d263279bf2c14c Mon Sep 17 00:00:00 2001 From: Moritz Eckert Date: Thu, 14 Mar 2024 14:29:27 +0100 Subject: [PATCH] docs: order csp strictly alphabetically --- docs/docs/architecture/attestation.md | 108 ++++++------ docs/docs/getting-started/first-steps.md | 99 +++++------ docs/docs/getting-started/install.md | 136 +++++++-------- docs/docs/workflows/config.md | 155 +++++++++--------- docs/docs/workflows/recovery.md | 62 +++---- docs/docs/workflows/scale.md | 27 ++- docs/docs/workflows/storage.md | 72 ++++---- docs/docs/workflows/terraform-provider.md | 19 +-- .../version-2.16/architecture/attestation.md | 108 ++++++------ .../getting-started/first-steps.md | 99 +++++------ .../version-2.16/getting-started/install.md | 136 +++++++-------- .../version-2.16/workflows/config.md | 155 +++++++++--------- .../version-2.16/workflows/recovery.md | 62 +++---- .../version-2.16/workflows/scale.md | 27 ++- .../version-2.16/workflows/storage.md | 72 ++++---- .../workflows/terraform-provider.md | 19 +-- 16 files changed, 664 insertions(+), 692 deletions(-) diff --git a/docs/docs/architecture/attestation.md b/docs/docs/architecture/attestation.md index 5e9523988..5a8638964 100644 --- a/docs/docs/architecture/attestation.md +++ b/docs/docs/architecture/attestation.md @@ -122,6 +122,38 @@ Enforcing non-reproducible measurements controlled by the cloud provider means t 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. + +The vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. +The VMs are attested by obtaining signed PCR values over the VM's boot configuration from the TPM and comparing them to a known, good state (measured boot). + +The following table lists all PCR values of the vTPM and the measured components. +It also lists what components of the boot chain did the measurements and if the value is reproducible and verifiable. +The latter means that the value can be generated offline and compared to the one in the vTPM. + +| PCR | Components | Measured by | Reproducible and verifiable | +| ----------- | ---------------------------------------------------------------- | -------------------------------------- | --------------------------- | +| 0 | Firmware | AWS | No | +| 1 | Firmware | AWS | No | +| 2 | Firmware | AWS | No | +| 3 | Firmware | AWS | No | +| 4 | Constellation Bootloader, Kernel, initramfs, Kernel command line | AWS, Constellation Bootloader | Yes | +| 5 | Firmware | AWS | No | +| 6 | Firmware | AWS | No | +| 7 | Secure Boot Policy | AWS, Constellation Bootloader | No | +| 8 | - | - | - | +| 9 | initramfs, Kernel command line | Linux Kernel | Yes | +| 10 | User space | Linux IMA | No[^1] | +| 11 | Unified Kernel Image components | Constellation Bootloader | Yes | +| 12 | Reserved | (User space, Constellation Bootloader) | Yes | +| 13 | Reserved | (Constellation Bootloader) | Yes | +| 14 | Secure Boot State | Constellation Bootloader | No | +| 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. @@ -185,38 +217,6 @@ 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. - -The vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. -The VMs are attested by obtaining signed PCR values over the VM's boot configuration from the TPM and comparing them to a known, good state (measured boot). - -The following table lists all PCR values of the vTPM and the measured components. -It also lists what components of the boot chain did the measurements and if the value is reproducible and verifiable. -The latter means that the value can be generated offline and compared to the one in the vTPM. - -| PCR | Components | Measured by | Reproducible and verifiable | -| ----------- | ---------------------------------------------------------------- | -------------------------------------- | --------------------------- | -| 0 | Firmware | AWS | No | -| 1 | Firmware | AWS | No | -| 2 | Firmware | AWS | No | -| 3 | Firmware | AWS | No | -| 4 | Constellation Bootloader, Kernel, initramfs, Kernel command line | AWS, Constellation Bootloader | Yes | -| 5 | Firmware | AWS | No | -| 6 | Firmware | AWS | No | -| 7 | Secure Boot Policy | AWS, Constellation Bootloader | No | -| 8 | - | - | - | -| 9 | initramfs, Kernel command line | Linux Kernel | Yes | -| 10 | User space | Linux IMA | No[^1] | -| 11 | Unified Kernel Image components | Constellation Bootloader | Yes | -| 12 | Reserved | (User space, Constellation Bootloader) | Yes | -| 13 | Reserved | (Constellation Bootloader) | Yes | -| 14 | Secure Boot State | Constellation Bootloader | No | -| 15 | ClusterID | Constellation Bootstrapper | Yes | -| 16–23 | Unused | - | - | - @@ -258,6 +258,28 @@ To verify the integrity of the received attestation statement, a chain of trust 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. +You may customize certain parameters for verification of the attestation statement using the Constellation config file. + +* TCB versions + + You can set the minimum version numbers of components in the SEV-SNP TCB. + Use the latest versions to enforce that only machines with the most recent firmware updates are allowed to join the cluster. + Alternatively, you can set a lower minimum version to allow slightly out-of-date machines to still be able to join the cluster. + +* AMD Root Key Certificate + + This certificate is the root of trust for verifying the SEV-SNP certificate chain. + +* AMD Signing Key Certificate + + 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. @@ -287,28 +309,6 @@ 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 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. -You may customize certain parameters for verification of the attestation statement using the Constellation config file. - -* TCB versions - - You can set the minimum version numbers of components in the SEV-SNP TCB. - Use the latest versions to enforce that only machines with the most recent firmware updates are allowed to join the cluster. - Alternatively, you can set a lower minimum version to allow slightly out-of-date machines to still be able to join the cluster. - -* AMD Root Key Certificate - - This certificate is the root of trust for verifying the SEV-SNP certificate chain. - -* AMD Signing Key Certificate - - 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. - diff --git a/docs/docs/getting-started/first-steps.md b/docs/docs/getting-started/first-steps.md index 546078c8b..ff4975496 100644 --- a/docs/docs/getting-started/first-steps.md +++ b/docs/docs/getting-started/first-steps.md @@ -16,23 +16,6 @@ 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 @@ -40,7 +23,20 @@ If you encounter any problem with the following steps, make sure to use the [lat ``` + + ```bash + constellation config generate azure + ``` + + + + + ```bash + constellation config generate gcp + ``` + + ```bash @@ -48,48 +44,11 @@ If you encounter any problem with the following steps, make sure to use the [lat ``` - 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 - ``` - - This command creates IAM configuration on the Azure region `westus` creating a new resource group `constellTest` and a new service principal `spTest`. It also updates the configuration file `constellation-conf.yaml` in your current directory with the IAM values filled in. - - CVMs are available in several Azure regions. Constellation OS images are currently replicated to the following: - - * `germanywestcentral` - * `westus` - * `eastus` - * `northeurope` - * `westeurope` - * `southeastasia` - - If you require the OS image to be available in another region, [let us know](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&template=feature_request.md&title=Support+new+Azure+image+region:+xx-xxxx-x). - - 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 - ``` - - This command creates IAM configuration in the GCP project `yourproject-12345` on the GCP zone `europe-west2-a` creating a new service account `constell-test`. It also updates the configuration file `constellation-conf.yaml` in your current directory with the IAM values filled in. - - 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 @@ -118,7 +77,39 @@ 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 + ``` + + This command creates IAM configuration on the Azure region `westus` creating a new resource group `constellTest` and a new service principal `spTest`. It also updates the configuration file `constellation-conf.yaml` in your current directory with the IAM values filled in. + + CVMs are available in several Azure regions. Constellation OS images are currently replicated to the following: + + * `germanywestcentral` + * `westus` + * `eastus` + * `northeurope` + * `westeurope` + * `southeastasia` + + If you require the OS image to be available in another region, [let us know](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&template=feature_request.md&title=Support+new+Azure+image+region:+xx-xxxx-x). + + 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 + ``` + + This command creates IAM configuration in the GCP project `yourproject-12345` on the GCP zone `europe-west2-a` creating a new service account `constell-test`. It also updates the configuration file `constellation-conf.yaml` in your current directory with the IAM values filled in. + + 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). diff --git a/docs/docs/getting-started/install.md b/docs/docs/getting-started/install.md index 9d35c912b..999601b5b 100644 --- a/docs/docs/getting-started/install.md +++ b/docs/docs/getting-started/install.md @@ -133,6 +133,57 @@ 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. + +To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "ec2:DescribeAccountAttributes", + "iam:AddRoleToInstanceProfile", + "iam:AttachRolePolicy", + "iam:CreateInstanceProfile", + "iam:CreatePolicy", + "iam:CreateRole", + "iam:DeleteInstanceProfile", + "iam:DeletePolicy", + "iam:DeletePolicyVersion", + "iam:DeleteRole", + "iam:DetachRolePolicy", + "iam:GetInstanceProfile", + "iam:GetPolicy", + "iam:GetPolicyVersion", + "iam:GetRole", + "iam:ListAttachedRolePolicies", + "iam:ListInstanceProfilesForRole", + "iam:ListPolicyVersions", + "iam:ListRolePolicies", + "iam:PassRole", + "iam:RemoveRoleFromInstanceProfile", + "sts:GetCallerIdentity" + ], + "Resource": "*" + } + ] +} +``` + +The built-in `AdministratorAccess` policy is a superset of these permissions. + +To [create a Constellation cluster](../workflows/create.md), see the permissions of [main.tf](https://github.com/edgelesssys/constellation/blob/main/terraform/infrastructure/iam/aws/main.tf). + +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: @@ -263,57 +314,6 @@ 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. - -To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "ec2:DescribeAccountAttributes", - "iam:AddRoleToInstanceProfile", - "iam:AttachRolePolicy", - "iam:CreateInstanceProfile", - "iam:CreatePolicy", - "iam:CreateRole", - "iam:DeleteInstanceProfile", - "iam:DeletePolicy", - "iam:DeletePolicyVersion", - "iam:DeleteRole", - "iam:DetachRolePolicy", - "iam:GetInstanceProfile", - "iam:GetPolicy", - "iam:GetPolicyVersion", - "iam:GetRole", - "iam:ListAttachedRolePolicies", - "iam:ListInstanceProfilesForRole", - "iam:ListPolicyVersions", - "iam:ListRolePolicies", - "iam:PassRole", - "iam:RemoveRoleFromInstanceProfile", - "sts:GetCallerIdentity" - ], - "Resource": "*" - } - ] -} -``` - -The built-in `AdministratorAccess` policy is a superset of these permissions. - -To [create a Constellation cluster](../workflows/create.md), see the permissions of [main.tf](https://github.com/edgelesssys/constellation/blob/main/terraform/infrastructure/iam/aws/main.tf). - -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). - @@ -334,6 +334,23 @@ The steps for a *testing* environment are simpler. However, they may expose secr ::: + + +**Testing** + +You can use the [AWS CloudShell](https://console.aws.amazon.com/cloudshell/home). Make sure you are [authorized to use it](https://docs.aws.amazon.com/cloudshell/latest/userguide/sec-auth-with-identities.html). + +**Production** + +Use the latest version of the [AWS CLI](https://aws.amazon.com/cli/) on a trusted machine: + +```bash +aws configure +``` + +Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). + + **Testing** @@ -374,23 +391,6 @@ 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** - -You can use the [AWS CloudShell](https://console.aws.amazon.com/cloudshell/home). Make sure you are [authorized to use it](https://docs.aws.amazon.com/cloudshell/latest/userguide/sec-auth-with-identities.html). - -**Production** - -Use the latest version of the [AWS CLI](https://aws.amazon.com/cli/) on a trusted machine: - -```bash -aws configure -``` - -Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - diff --git a/docs/docs/workflows/config.md b/docs/docs/workflows/config.md index 7e8933466..edbffa8a6 100644 --- a/docs/docs/workflows/config.md +++ b/docs/docs/workflows/config.md @@ -15,6 +15,13 @@ 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 @@ -28,13 +35,6 @@ constellation config generate azure constellation config generate gcp ``` - - - -```bash -constellation config generate aws -``` - @@ -51,18 +51,6 @@ This creates the file `constellation-conf.yaml` in the current directory. 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. @@ -74,6 +62,18 @@ 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. + @@ -154,6 +154,31 @@ You can create an IAM configuration for your cluster automatically using the `co 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). + +```bash +constellation iam create aws --zone=us-east-2a --prefix=constellTest +``` + +This command creates IAM configuration for the AWS zone `us-east-2a` using the prefix `constellTest` for all named resources being created. + +Constellation OS images are currently replicated to the following regions: + +* `eu-central-1` +* `eu-west-1` +* `eu-west-3` +* `us-east-2` +* `ap-south-1` + +If you require the OS image to be available in another region, [let us know](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&template=feature_request.md&title=Support+new+AWS+image+region:+xx-xxxx-x). + +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). + +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). @@ -194,31 +219,6 @@ 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). - -```bash -constellation iam create aws --zone=us-east-2a --prefix=constellTest -``` - -This command creates IAM configuration for the AWS zone `us-east-2a` using the prefix `constellTest` for all named resources being created. - -Constellation OS images are currently replicated to the following regions: - -* `eu-central-1` -* `eu-west-1` -* `eu-west-3` -* `us-east-2` -* `ap-south-1` - -If you require the OS image to be available in another region, [let us know](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&template=feature_request.md&title=Support+new+AWS+image+region:+xx-xxxx-x). - -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). - -Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - @@ -233,6 +233,38 @@ STACKIT requires manual creation and configuration of service accounts. Look at 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`. + + Constellation OS images are currently replicated to the following regions: + * `eu-central-1` + * `eu-west-1` + * `eu-west-3` + * `us-east-2` + * `ap-south-1` + + If you require the OS image to be available in another region, [let us know](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&template=feature_request.md&title=Support+new+AWS+image+region:+xx-xxxx-x). + + 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). + +* **zone**: The name of your chosen AWS data center availability zone, e.g., `us-east-2a`. + + Learn more about [availability zones in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-availability-zones). + +* **iamProfileControlPlane**: The name of an IAM instance profile attached to all control-plane nodes. + + You can create the resource with [Terraform](https://www.terraform.io/). For that, use the [provided Terraform script](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam) to generate the necessary profile. The profile name will be provided as Terraform output value: `control_plane_instance_profile_name`. + + 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.control_plane_policy`. + +* **iamProfileWorkerNodes**: The name of an IAM instance profile attached to all worker nodes. + + You can create the resource with [Terraform](https://www.terraform.io/). For that, use the [provided Terraform script](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam) to generate the necessary profile. The profile name will be provided as Terraform output value: `worker_nodes_instance_profile_name`. + + 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`. @@ -270,7 +302,6 @@ The following describes the configuration fields and how you obtain the required 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`. @@ -296,40 +327,6 @@ 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`. - - Constellation OS images are currently replicated to the following regions: - * `eu-central-1` - * `eu-west-1` - * `eu-west-3` - * `us-east-2` - * `ap-south-1` - - If you require the OS image to be available in another region, [let us know](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&template=feature_request.md&title=Support+new+AWS+image+region:+xx-xxxx-x). - - 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). - -* **zone**: The name of your chosen AWS data center availability zone, e.g., `us-east-2a`. - - Learn more about [availability zones in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-availability-zones). - -* **iamProfileControlPlane**: The name of an IAM instance profile attached to all control-plane nodes. - - You can create the resource with [Terraform](https://www.terraform.io/). For that, use the [provided Terraform script](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam) to generate the necessary profile. The profile name will be provided as Terraform output value: `control_plane_instance_profile_name`. - - 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.control_plane_policy`. - -* **iamProfileWorkerNodes**: The name of an IAM instance profile attached to all worker nodes. - - You can create the resource with [Terraform](https://www.terraform.io/). For that, use the [provided Terraform script](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam) to generate the necessary profile. The profile name will be provided as Terraform output value: `worker_nodes_instance_profile_name`. - - 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`. - - - STACKIT requires manual creation and configuration of service accounts. Look at the [first steps](../getting-started/first-steps.md) for more information. diff --git a/docs/docs/workflows/recovery.md b/docs/docs/workflows/recovery.md index 9bbb32652..aea370e2f 100644 --- a/docs/docs/workflows/recovery.md +++ b/docs/docs/workflows/recovery.md @@ -17,6 +17,37 @@ Constellation provides logging information on the boot process and status via se 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. + +Second, check the boot logs of these *Instances*. In the ASG's *Instance management* view, select each desired instance. In the upper right corner, select **Action > Monitor and troubleshoot > Get system log**. + +In the serial console output, search for `Waiting for decryption key`. +Similar output to the following means your node was restarted and needs to decrypt the [state disk](../architecture/images.md#state-disk): + +```json +{"level":"INFO","ts":"2022-09-08T10:21:53Z","caller":"cmd/main.go:55","msg":"Starting disk-mapper","version":"2.0.0","cloudProvider":"gcp"} +{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"setupManager","caller":"setup/setup.go:72","msg":"Preparing existing state disk"} +{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:65","msg":"Starting RejoinClient"} +{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"recoveryServer","caller":"recoveryserver/server.go:59","msg":"Starting RecoveryServer"} +``` + +The node will then try to connect to the [*JoinService*](../architecture/microservices.md#joinservice) and obtain the decryption key. +If this fails due to an unhealthy control plane, you will see log messages similar to the following: + +```json +{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:77","msg":"Received list with JoinService endpoints","endpoints":["192.168.178.4:30090","192.168.178.2:30090"]} +{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:96","msg":"Requesting rejoin ticket","endpoint":"192.168.178.4:30090"} +{"level":"WARN","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:101","msg":"Failed to rejoin on endpoint","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing dial tcp 192.168.178.4:30090: connect: connection refused\"","endpoint":"192.168.178.4:30090"} +{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:96","msg":"Requesting rejoin ticket","endpoint":"192.168.178.2:30090"} +{"level":"WARN","ts":"2022-09-08T10:22:13Z","logger":"rejoinClient","caller":"rejoinclient/client.go:101","msg":"Failed to rejoin on endpoint","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing dial tcp 192.168.178.2:30090: i/o timeout\"","endpoint":"192.168.178.2:30090"} +{"level":"ERROR","ts":"2022-09-08T10:22:13Z","logger":"rejoinClient","caller":"rejoinclient/client.go:110","msg":"Failed to rejoin on all endpoints"} +``` + +This means that you have to recover the node manually. + + In the Azure portal, find the cluster's resource group. @@ -87,37 +118,6 @@ 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. - -Second, check the boot logs of these *Instances*. In the ASG's *Instance management* view, select each desired instance. In the upper right corner, select **Action > Monitor and troubleshoot > Get system log**. - -In the serial console output, search for `Waiting for decryption key`. -Similar output to the following means your node was restarted and needs to decrypt the [state disk](../architecture/images.md#state-disk): - -```json -{"level":"INFO","ts":"2022-09-08T10:21:53Z","caller":"cmd/main.go:55","msg":"Starting disk-mapper","version":"2.0.0","cloudProvider":"gcp"} -{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"setupManager","caller":"setup/setup.go:72","msg":"Preparing existing state disk"} -{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:65","msg":"Starting RejoinClient"} -{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"recoveryServer","caller":"recoveryserver/server.go:59","msg":"Starting RecoveryServer"} -``` - -The node will then try to connect to the [*JoinService*](../architecture/microservices.md#joinservice) and obtain the decryption key. -If this fails due to an unhealthy control plane, you will see log messages similar to the following: - -```json -{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:77","msg":"Received list with JoinService endpoints","endpoints":["192.168.178.4:30090","192.168.178.2:30090"]} -{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:96","msg":"Requesting rejoin ticket","endpoint":"192.168.178.4:30090"} -{"level":"WARN","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:101","msg":"Failed to rejoin on endpoint","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing dial tcp 192.168.178.4:30090: connect: connection refused\"","endpoint":"192.168.178.4:30090"} -{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:96","msg":"Requesting rejoin ticket","endpoint":"192.168.178.2:30090"} -{"level":"WARN","ts":"2022-09-08T10:22:13Z","logger":"rejoinClient","caller":"rejoinclient/client.go:101","msg":"Failed to rejoin on endpoint","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing dial tcp 192.168.178.2:30090: i/o timeout\"","endpoint":"192.168.178.2:30090"} -{"level":"ERROR","ts":"2022-09-08T10:22:13Z","logger":"rejoinClient","caller":"rejoinclient/client.go:110","msg":"Failed to rejoin on all endpoints"} -``` - -This means that you have to recover the node manually. - diff --git a/docs/docs/workflows/scale.md b/docs/docs/workflows/scale.md index 06898ad0c..32bdd2e7b 100644 --- a/docs/docs/workflows/scale.md +++ b/docs/docs/workflows/scale.md @@ -52,6 +52,13 @@ 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. @@ -66,13 +73,6 @@ Alternatively, you can manually scale your cluster up or down: 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**. - @@ -83,7 +83,13 @@ 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. @@ -98,13 +104,6 @@ To increase the number of control-plane nodes, follow these steps: 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**. - diff --git a/docs/docs/workflows/storage.md b/docs/docs/workflows/storage.md index 1cae8dacc..f1344d6ad 100644 --- a/docs/docs/workflows/storage.md +++ b/docs/docs/workflows/storage.md @@ -22,6 +22,13 @@ 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**: @@ -36,13 +43,6 @@ Since Azure Disks are mounted as `ReadWriteOnce`, they're only available to a si 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. - @@ -61,6 +61,35 @@ The Constellation CLI automatically installs Constellation's CSI driver for the 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. + +* `encrypted-rwo` + * Uses [SSDs of `gp3` type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volume-types.html) + * ext-4 filesystem + * Encryption of all data written to disk +* `integrity-encrypted-rwo` + * Uses [SSDs of `gp3` type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volume-types.html) + * ext-4 filesystem + * Encryption of all data written to disk + * Integrity protection of data written to disk + +For more information on encryption algorithms and key sizes, refer to [cryptographic algorithms](../architecture/encrypted-storage.md#cryptographic-algorithms). + +:::info + +The default storage class is set to `encrypted-rwo` for performance reasons. +If you want integrity-protected storage, set the `storageClassName` parameter of your persistent volume claim to `integrity-encrypted-rwo`. + +Alternatively, you can create your own storage class with integrity protection enabled by adding `csi.storage.k8s.io/fstype: ext4-integrity` to the class `parameters`. +Or use another filesystem by specifying another file system type with the suffix `-integrity`, e.g., `csi.storage.k8s.io/fstype: xfs-integrity`. + +Note that volume expansion isn't supported for integrity-protected disks. + +::: + + Azure comes with two storage classes by default. @@ -118,35 +147,6 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - - -AWS comes with two storage classes by default. - -* `encrypted-rwo` - * Uses [SSDs of `gp3` type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volume-types.html) - * ext-4 filesystem - * Encryption of all data written to disk -* `integrity-encrypted-rwo` - * Uses [SSDs of `gp3` type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volume-types.html) - * ext-4 filesystem - * Encryption of all data written to disk - * Integrity protection of data written to disk - -For more information on encryption algorithms and key sizes, refer to [cryptographic algorithms](../architecture/encrypted-storage.md#cryptographic-algorithms). - -:::info - -The default storage class is set to `encrypted-rwo` for performance reasons. -If you want integrity-protected storage, set the `storageClassName` parameter of your persistent volume claim to `integrity-encrypted-rwo`. - -Alternatively, you can create your own storage class with integrity protection enabled by adding `csi.storage.k8s.io/fstype: ext4-integrity` to the class `parameters`. -Or use another filesystem by specifying another file system type with the suffix `-integrity`, e.g., `csi.storage.k8s.io/fstype: xfs-integrity`. - -Note that volume expansion isn't supported for integrity-protected disks. - -::: - diff --git a/docs/docs/workflows/terraform-provider.md b/docs/docs/workflows/terraform-provider.md index 78e63f326..8a3cedc62 100644 --- a/docs/docs/workflows/terraform-provider.md +++ b/docs/docs/workflows/terraform-provider.md @@ -22,7 +22,16 @@ 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 + terraform init + terraform apply + ``` + + 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. @@ -57,16 +66,6 @@ This example shows how to set up a Constellation cluster with the reference IAM }; ``` - - - Initialize the providers and apply the configuration. - - ```bash - terraform init - terraform apply - ``` - - 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. diff --git a/docs/versioned_docs/version-2.16/architecture/attestation.md b/docs/versioned_docs/version-2.16/architecture/attestation.md index 5e9523988..5a8638964 100644 --- a/docs/versioned_docs/version-2.16/architecture/attestation.md +++ b/docs/versioned_docs/version-2.16/architecture/attestation.md @@ -122,6 +122,38 @@ Enforcing non-reproducible measurements controlled by the cloud provider means t 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. + +The vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. +The VMs are attested by obtaining signed PCR values over the VM's boot configuration from the TPM and comparing them to a known, good state (measured boot). + +The following table lists all PCR values of the vTPM and the measured components. +It also lists what components of the boot chain did the measurements and if the value is reproducible and verifiable. +The latter means that the value can be generated offline and compared to the one in the vTPM. + +| PCR | Components | Measured by | Reproducible and verifiable | +| ----------- | ---------------------------------------------------------------- | -------------------------------------- | --------------------------- | +| 0 | Firmware | AWS | No | +| 1 | Firmware | AWS | No | +| 2 | Firmware | AWS | No | +| 3 | Firmware | AWS | No | +| 4 | Constellation Bootloader, Kernel, initramfs, Kernel command line | AWS, Constellation Bootloader | Yes | +| 5 | Firmware | AWS | No | +| 6 | Firmware | AWS | No | +| 7 | Secure Boot Policy | AWS, Constellation Bootloader | No | +| 8 | - | - | - | +| 9 | initramfs, Kernel command line | Linux Kernel | Yes | +| 10 | User space | Linux IMA | No[^1] | +| 11 | Unified Kernel Image components | Constellation Bootloader | Yes | +| 12 | Reserved | (User space, Constellation Bootloader) | Yes | +| 13 | Reserved | (Constellation Bootloader) | Yes | +| 14 | Secure Boot State | Constellation Bootloader | No | +| 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. @@ -185,38 +217,6 @@ 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. - -The vTPM adheres to the [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) specification. -The VMs are attested by obtaining signed PCR values over the VM's boot configuration from the TPM and comparing them to a known, good state (measured boot). - -The following table lists all PCR values of the vTPM and the measured components. -It also lists what components of the boot chain did the measurements and if the value is reproducible and verifiable. -The latter means that the value can be generated offline and compared to the one in the vTPM. - -| PCR | Components | Measured by | Reproducible and verifiable | -| ----------- | ---------------------------------------------------------------- | -------------------------------------- | --------------------------- | -| 0 | Firmware | AWS | No | -| 1 | Firmware | AWS | No | -| 2 | Firmware | AWS | No | -| 3 | Firmware | AWS | No | -| 4 | Constellation Bootloader, Kernel, initramfs, Kernel command line | AWS, Constellation Bootloader | Yes | -| 5 | Firmware | AWS | No | -| 6 | Firmware | AWS | No | -| 7 | Secure Boot Policy | AWS, Constellation Bootloader | No | -| 8 | - | - | - | -| 9 | initramfs, Kernel command line | Linux Kernel | Yes | -| 10 | User space | Linux IMA | No[^1] | -| 11 | Unified Kernel Image components | Constellation Bootloader | Yes | -| 12 | Reserved | (User space, Constellation Bootloader) | Yes | -| 13 | Reserved | (Constellation Bootloader) | Yes | -| 14 | Secure Boot State | Constellation Bootloader | No | -| 15 | ClusterID | Constellation Bootstrapper | Yes | -| 16–23 | Unused | - | - | - @@ -258,6 +258,28 @@ To verify the integrity of the received attestation statement, a chain of trust 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. +You may customize certain parameters for verification of the attestation statement using the Constellation config file. + +* TCB versions + + You can set the minimum version numbers of components in the SEV-SNP TCB. + Use the latest versions to enforce that only machines with the most recent firmware updates are allowed to join the cluster. + Alternatively, you can set a lower minimum version to allow slightly out-of-date machines to still be able to join the cluster. + +* AMD Root Key Certificate + + This certificate is the root of trust for verifying the SEV-SNP certificate chain. + +* AMD Signing Key Certificate + + 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. @@ -287,28 +309,6 @@ 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 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. -You may customize certain parameters for verification of the attestation statement using the Constellation config file. - -* TCB versions - - You can set the minimum version numbers of components in the SEV-SNP TCB. - Use the latest versions to enforce that only machines with the most recent firmware updates are allowed to join the cluster. - Alternatively, you can set a lower minimum version to allow slightly out-of-date machines to still be able to join the cluster. - -* AMD Root Key Certificate - - This certificate is the root of trust for verifying the SEV-SNP certificate chain. - -* AMD Signing Key Certificate - - 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. - 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 546078c8b..ff4975496 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 @@ -16,23 +16,6 @@ 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 @@ -40,7 +23,20 @@ If you encounter any problem with the following steps, make sure to use the [lat ``` + + ```bash + constellation config generate azure + ``` + + + + + ```bash + constellation config generate gcp + ``` + + ```bash @@ -48,48 +44,11 @@ If you encounter any problem with the following steps, make sure to use the [lat ``` - 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 - ``` - - This command creates IAM configuration on the Azure region `westus` creating a new resource group `constellTest` and a new service principal `spTest`. It also updates the configuration file `constellation-conf.yaml` in your current directory with the IAM values filled in. - - CVMs are available in several Azure regions. Constellation OS images are currently replicated to the following: - - * `germanywestcentral` - * `westus` - * `eastus` - * `northeurope` - * `westeurope` - * `southeastasia` - - If you require the OS image to be available in another region, [let us know](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&template=feature_request.md&title=Support+new+Azure+image+region:+xx-xxxx-x). - - 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 - ``` - - This command creates IAM configuration in the GCP project `yourproject-12345` on the GCP zone `europe-west2-a` creating a new service account `constell-test`. It also updates the configuration file `constellation-conf.yaml` in your current directory with the IAM values filled in. - - 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 @@ -118,7 +77,39 @@ 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 + ``` + + This command creates IAM configuration on the Azure region `westus` creating a new resource group `constellTest` and a new service principal `spTest`. It also updates the configuration file `constellation-conf.yaml` in your current directory with the IAM values filled in. + + CVMs are available in several Azure regions. Constellation OS images are currently replicated to the following: + + * `germanywestcentral` + * `westus` + * `eastus` + * `northeurope` + * `westeurope` + * `southeastasia` + + If you require the OS image to be available in another region, [let us know](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&template=feature_request.md&title=Support+new+Azure+image+region:+xx-xxxx-x). + + 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 + ``` + + This command creates IAM configuration in the GCP project `yourproject-12345` on the GCP zone `europe-west2-a` creating a new service account `constell-test`. It also updates the configuration file `constellation-conf.yaml` in your current directory with the IAM values filled in. + + 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). 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 9d35c912b..999601b5b 100644 --- a/docs/versioned_docs/version-2.16/getting-started/install.md +++ b/docs/versioned_docs/version-2.16/getting-started/install.md @@ -133,6 +133,57 @@ 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. + +To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "ec2:DescribeAccountAttributes", + "iam:AddRoleToInstanceProfile", + "iam:AttachRolePolicy", + "iam:CreateInstanceProfile", + "iam:CreatePolicy", + "iam:CreateRole", + "iam:DeleteInstanceProfile", + "iam:DeletePolicy", + "iam:DeletePolicyVersion", + "iam:DeleteRole", + "iam:DetachRolePolicy", + "iam:GetInstanceProfile", + "iam:GetPolicy", + "iam:GetPolicyVersion", + "iam:GetRole", + "iam:ListAttachedRolePolicies", + "iam:ListInstanceProfilesForRole", + "iam:ListPolicyVersions", + "iam:ListRolePolicies", + "iam:PassRole", + "iam:RemoveRoleFromInstanceProfile", + "sts:GetCallerIdentity" + ], + "Resource": "*" + } + ] +} +``` + +The built-in `AdministratorAccess` policy is a superset of these permissions. + +To [create a Constellation cluster](../workflows/create.md), see the permissions of [main.tf](https://github.com/edgelesssys/constellation/blob/main/terraform/infrastructure/iam/aws/main.tf). + +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: @@ -263,57 +314,6 @@ 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. - -To [create the IAM configuration](../workflows/config.md#creating-an-iam-configuration) for Constellation, you need the following permissions: - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "ec2:DescribeAccountAttributes", - "iam:AddRoleToInstanceProfile", - "iam:AttachRolePolicy", - "iam:CreateInstanceProfile", - "iam:CreatePolicy", - "iam:CreateRole", - "iam:DeleteInstanceProfile", - "iam:DeletePolicy", - "iam:DeletePolicyVersion", - "iam:DeleteRole", - "iam:DetachRolePolicy", - "iam:GetInstanceProfile", - "iam:GetPolicy", - "iam:GetPolicyVersion", - "iam:GetRole", - "iam:ListAttachedRolePolicies", - "iam:ListInstanceProfilesForRole", - "iam:ListPolicyVersions", - "iam:ListRolePolicies", - "iam:PassRole", - "iam:RemoveRoleFromInstanceProfile", - "sts:GetCallerIdentity" - ], - "Resource": "*" - } - ] -} -``` - -The built-in `AdministratorAccess` policy is a superset of these permissions. - -To [create a Constellation cluster](../workflows/create.md), see the permissions of [main.tf](https://github.com/edgelesssys/constellation/blob/main/terraform/infrastructure/iam/aws/main.tf). - -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). - @@ -334,6 +334,23 @@ The steps for a *testing* environment are simpler. However, they may expose secr ::: + + +**Testing** + +You can use the [AWS CloudShell](https://console.aws.amazon.com/cloudshell/home). Make sure you are [authorized to use it](https://docs.aws.amazon.com/cloudshell/latest/userguide/sec-auth-with-identities.html). + +**Production** + +Use the latest version of the [AWS CLI](https://aws.amazon.com/cli/) on a trusted machine: + +```bash +aws configure +``` + +Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). + + **Testing** @@ -374,23 +391,6 @@ 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** - -You can use the [AWS CloudShell](https://console.aws.amazon.com/cloudshell/home). Make sure you are [authorized to use it](https://docs.aws.amazon.com/cloudshell/latest/userguide/sec-auth-with-identities.html). - -**Production** - -Use the latest version of the [AWS CLI](https://aws.amazon.com/cli/) on a trusted machine: - -```bash -aws configure -``` - -Options and first steps are described in the [AWS CLI documentation](https://docs.aws.amazon.com/cli/index.html). - diff --git a/docs/versioned_docs/version-2.16/workflows/config.md b/docs/versioned_docs/version-2.16/workflows/config.md index 3b4140faa..fe7886149 100644 --- a/docs/versioned_docs/version-2.16/workflows/config.md +++ b/docs/versioned_docs/version-2.16/workflows/config.md @@ -15,6 +15,13 @@ 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 @@ -28,13 +35,6 @@ constellation config generate azure constellation config generate gcp ``` - - - -```bash -constellation config generate aws -``` - @@ -51,18 +51,6 @@ This creates the file `constellation-conf.yaml` in the current directory. 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. @@ -74,6 +62,18 @@ 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. + @@ -154,6 +154,31 @@ You can create an IAM configuration for your cluster automatically using the `co 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). + +```bash +constellation iam create aws --zone=us-east-2a --prefix=constellTest +``` + +This command creates IAM configuration for the AWS zone `us-east-2a` using the prefix `constellTest` for all named resources being created. + +Constellation OS images are currently replicated to the following regions: + +* `eu-central-1` +* `eu-west-1` +* `eu-west-3` +* `us-east-2` +* `ap-south-1` + +If you require the OS image to be available in another region, [let us know](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&template=feature_request.md&title=Support+new+AWS+image+region:+xx-xxxx-x). + +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). + +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). @@ -194,31 +219,6 @@ 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). - -```bash -constellation iam create aws --zone=us-east-2a --prefix=constellTest -``` - -This command creates IAM configuration for the AWS zone `us-east-2a` using the prefix `constellTest` for all named resources being created. - -Constellation OS images are currently replicated to the following regions: - -* `eu-central-1` -* `eu-west-1` -* `eu-west-3` -* `us-east-2` -* `ap-south-1` - -If you require the OS image to be available in another region, [let us know](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&template=feature_request.md&title=Support+new+AWS+image+region:+xx-xxxx-x). - -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). - -Paste the output into the corresponding fields of the `constellation-conf.yaml` file. - @@ -233,6 +233,38 @@ STACKIT requires manual creation and configuration of service accounts. Look at 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`. + + Constellation OS images are currently replicated to the following regions: + * `eu-central-1` + * `eu-west-1` + * `eu-west-3` + * `us-east-2` + * `ap-south-1` + + If you require the OS image to be available in another region, [let us know](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&template=feature_request.md&title=Support+new+AWS+image+region:+xx-xxxx-x). + + 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). + +* **zone**: The name of your chosen AWS data center availability zone, e.g., `us-east-2a`. + + Learn more about [availability zones in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-availability-zones). + +* **iamProfileControlPlane**: The name of an IAM instance profile attached to all control-plane nodes. + + You can create the resource with [Terraform](https://www.terraform.io/). For that, use the [provided Terraform script](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam) to generate the necessary profile. The profile name will be provided as Terraform output value: `control_plane_instance_profile_name`. + + 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.control_plane_policy`. + +* **iamProfileWorkerNodes**: The name of an IAM instance profile attached to all worker nodes. + + You can create the resource with [Terraform](https://www.terraform.io/). For that, use the [provided Terraform script](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam) to generate the necessary profile. The profile name will be provided as Terraform output value: `worker_nodes_instance_profile_name`. + + 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`. @@ -270,7 +302,6 @@ The following describes the configuration fields and how you obtain the required 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`. @@ -296,40 +327,6 @@ 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`. - - Constellation OS images are currently replicated to the following regions: - * `eu-central-1` - * `eu-west-1` - * `eu-west-3` - * `us-east-2` - * `ap-south-1` - - If you require the OS image to be available in another region, [let us know](https://github.com/edgelesssys/constellation/issues/new?assignees=&labels=&template=feature_request.md&title=Support+new+AWS+image+region:+xx-xxxx-x). - - 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). - -* **zone**: The name of your chosen AWS data center availability zone, e.g., `us-east-2a`. - - Learn more about [availability zones in AWS's documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-availability-zones). - -* **iamProfileControlPlane**: The name of an IAM instance profile attached to all control-plane nodes. - - You can create the resource with [Terraform](https://www.terraform.io/). For that, use the [provided Terraform script](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam) to generate the necessary profile. The profile name will be provided as Terraform output value: `control_plane_instance_profile_name`. - - 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.control_plane_policy`. - -* **iamProfileWorkerNodes**: The name of an IAM instance profile attached to all worker nodes. - - You can create the resource with [Terraform](https://www.terraform.io/). For that, use the [provided Terraform script](https://github.com/edgelesssys/constellation/tree/release/v2.2/hack/terraform/aws/iam) to generate the necessary profile. The profile name will be provided as Terraform output value: `worker_nodes_instance_profile_name`. - - 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`. - - - STACKIT requires manual creation and configuration of service accounts. Look at the [first steps](../getting-started/first-steps.md) for more information. diff --git a/docs/versioned_docs/version-2.16/workflows/recovery.md b/docs/versioned_docs/version-2.16/workflows/recovery.md index b7224a141..1bfb172aa 100644 --- a/docs/versioned_docs/version-2.16/workflows/recovery.md +++ b/docs/versioned_docs/version-2.16/workflows/recovery.md @@ -17,6 +17,37 @@ Constellation provides logging information on the boot process and status via se 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. + +Second, check the boot logs of these *Instances*. In the ASG's *Instance management* view, select each desired instance. In the upper right corner, select **Action > Monitor and troubleshoot > Get system log**. + +In the serial console output, search for `Waiting for decryption key`. +Similar output to the following means your node was restarted and needs to decrypt the [state disk](../architecture/images.md#state-disk): + +```json +{"level":"INFO","ts":"2022-09-08T10:21:53Z","caller":"cmd/main.go:55","msg":"Starting disk-mapper","version":"2.0.0","cloudProvider":"gcp"} +{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"setupManager","caller":"setup/setup.go:72","msg":"Preparing existing state disk"} +{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:65","msg":"Starting RejoinClient"} +{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"recoveryServer","caller":"recoveryserver/server.go:59","msg":"Starting RecoveryServer"} +``` + +The node will then try to connect to the [*JoinService*](../architecture/microservices.md#joinservice) and obtain the decryption key. +If this fails due to an unhealthy control plane, you will see log messages similar to the following: + +```json +{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:77","msg":"Received list with JoinService endpoints","endpoints":["192.168.178.4:30090","192.168.178.2:30090"]} +{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:96","msg":"Requesting rejoin ticket","endpoint":"192.168.178.4:30090"} +{"level":"WARN","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:101","msg":"Failed to rejoin on endpoint","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing dial tcp 192.168.178.4:30090: connect: connection refused\"","endpoint":"192.168.178.4:30090"} +{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:96","msg":"Requesting rejoin ticket","endpoint":"192.168.178.2:30090"} +{"level":"WARN","ts":"2022-09-08T10:22:13Z","logger":"rejoinClient","caller":"rejoinclient/client.go:101","msg":"Failed to rejoin on endpoint","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing dial tcp 192.168.178.2:30090: i/o timeout\"","endpoint":"192.168.178.2:30090"} +{"level":"ERROR","ts":"2022-09-08T10:22:13Z","logger":"rejoinClient","caller":"rejoinclient/client.go:110","msg":"Failed to rejoin on all endpoints"} +``` + +This means that you have to recover the node manually. + + In the Azure portal, find the cluster's resource group. @@ -87,37 +118,6 @@ 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. - -Second, check the boot logs of these *Instances*. In the ASG's *Instance management* view, select each desired instance. In the upper right corner, select **Action > Monitor and troubleshoot > Get system log**. - -In the serial console output, search for `Waiting for decryption key`. -Similar output to the following means your node was restarted and needs to decrypt the [state disk](../architecture/images.md#state-disk): - -```json -{"level":"INFO","ts":"2022-09-08T10:21:53Z","caller":"cmd/main.go:55","msg":"Starting disk-mapper","version":"2.0.0","cloudProvider":"gcp"} -{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"setupManager","caller":"setup/setup.go:72","msg":"Preparing existing state disk"} -{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:65","msg":"Starting RejoinClient"} -{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"recoveryServer","caller":"recoveryserver/server.go:59","msg":"Starting RecoveryServer"} -``` - -The node will then try to connect to the [*JoinService*](../architecture/microservices.md#joinservice) and obtain the decryption key. -If this fails due to an unhealthy control plane, you will see log messages similar to the following: - -```json -{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:77","msg":"Received list with JoinService endpoints","endpoints":["192.168.178.4:30090","192.168.178.2:30090"]} -{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:96","msg":"Requesting rejoin ticket","endpoint":"192.168.178.4:30090"} -{"level":"WARN","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:101","msg":"Failed to rejoin on endpoint","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing dial tcp 192.168.178.4:30090: connect: connection refused\"","endpoint":"192.168.178.4:30090"} -{"level":"INFO","ts":"2022-09-08T10:21:53Z","logger":"rejoinClient","caller":"rejoinclient/client.go:96","msg":"Requesting rejoin ticket","endpoint":"192.168.178.2:30090"} -{"level":"WARN","ts":"2022-09-08T10:22:13Z","logger":"rejoinClient","caller":"rejoinclient/client.go:101","msg":"Failed to rejoin on endpoint","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing dial tcp 192.168.178.2:30090: i/o timeout\"","endpoint":"192.168.178.2:30090"} -{"level":"ERROR","ts":"2022-09-08T10:22:13Z","logger":"rejoinClient","caller":"rejoinclient/client.go:110","msg":"Failed to rejoin on all endpoints"} -``` - -This means that you have to recover the node manually. - diff --git a/docs/versioned_docs/version-2.16/workflows/scale.md b/docs/versioned_docs/version-2.16/workflows/scale.md index 06898ad0c..32bdd2e7b 100644 --- a/docs/versioned_docs/version-2.16/workflows/scale.md +++ b/docs/versioned_docs/version-2.16/workflows/scale.md @@ -52,6 +52,13 @@ 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. @@ -66,13 +73,6 @@ Alternatively, you can manually scale your cluster up or down: 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**. - @@ -83,7 +83,13 @@ 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. @@ -98,13 +104,6 @@ To increase the number of control-plane nodes, follow these steps: 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**. - diff --git a/docs/versioned_docs/version-2.16/workflows/storage.md b/docs/versioned_docs/version-2.16/workflows/storage.md index 1cae8dacc..f1344d6ad 100644 --- a/docs/versioned_docs/version-2.16/workflows/storage.md +++ b/docs/versioned_docs/version-2.16/workflows/storage.md @@ -22,6 +22,13 @@ 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**: @@ -36,13 +43,6 @@ Since Azure Disks are mounted as `ReadWriteOnce`, they're only available to a si 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. - @@ -61,6 +61,35 @@ The Constellation CLI automatically installs Constellation's CSI driver for the 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. + +* `encrypted-rwo` + * Uses [SSDs of `gp3` type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volume-types.html) + * ext-4 filesystem + * Encryption of all data written to disk +* `integrity-encrypted-rwo` + * Uses [SSDs of `gp3` type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volume-types.html) + * ext-4 filesystem + * Encryption of all data written to disk + * Integrity protection of data written to disk + +For more information on encryption algorithms and key sizes, refer to [cryptographic algorithms](../architecture/encrypted-storage.md#cryptographic-algorithms). + +:::info + +The default storage class is set to `encrypted-rwo` for performance reasons. +If you want integrity-protected storage, set the `storageClassName` parameter of your persistent volume claim to `integrity-encrypted-rwo`. + +Alternatively, you can create your own storage class with integrity protection enabled by adding `csi.storage.k8s.io/fstype: ext4-integrity` to the class `parameters`. +Or use another filesystem by specifying another file system type with the suffix `-integrity`, e.g., `csi.storage.k8s.io/fstype: xfs-integrity`. + +Note that volume expansion isn't supported for integrity-protected disks. + +::: + + Azure comes with two storage classes by default. @@ -118,35 +147,6 @@ Note that volume expansion isn't supported for integrity-protected disks. ::: - - - -AWS comes with two storage classes by default. - -* `encrypted-rwo` - * Uses [SSDs of `gp3` type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volume-types.html) - * ext-4 filesystem - * Encryption of all data written to disk -* `integrity-encrypted-rwo` - * Uses [SSDs of `gp3` type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volume-types.html) - * ext-4 filesystem - * Encryption of all data written to disk - * Integrity protection of data written to disk - -For more information on encryption algorithms and key sizes, refer to [cryptographic algorithms](../architecture/encrypted-storage.md#cryptographic-algorithms). - -:::info - -The default storage class is set to `encrypted-rwo` for performance reasons. -If you want integrity-protected storage, set the `storageClassName` parameter of your persistent volume claim to `integrity-encrypted-rwo`. - -Alternatively, you can create your own storage class with integrity protection enabled by adding `csi.storage.k8s.io/fstype: ext4-integrity` to the class `parameters`. -Or use another filesystem by specifying another file system type with the suffix `-integrity`, e.g., `csi.storage.k8s.io/fstype: xfs-integrity`. - -Note that volume expansion isn't supported for integrity-protected disks. - -::: - 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 78e63f326..8a3cedc62 100644 --- a/docs/versioned_docs/version-2.16/workflows/terraform-provider.md +++ b/docs/versioned_docs/version-2.16/workflows/terraform-provider.md @@ -22,7 +22,16 @@ 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 + terraform init + terraform apply + ``` + + 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. @@ -57,16 +66,6 @@ This example shows how to set up a Constellation cluster with the reference IAM }; ``` - - - Initialize the providers and apply the configuration. - - ```bash - terraform init - terraform apply - ``` - - 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.