diff --git a/docs/docs/workflows/create.md b/docs/docs/workflows/create.md index 7858b5d8bff..51253dc7bd7 100644 --- a/docs/docs/workflows/create.md +++ b/docs/docs/workflows/create.md @@ -36,217 +36,19 @@ 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. - -:::info -Familiarize with the [Terraform usage policy](../reference/terraform.md) before manually interacting with Terraform to create a cluster. -Please also refrain from changing the Terraform resource definitions, as Constellation is tightly coupled to them. -::: - -Download the Terraform files for the selected CSP from the [GitHub repository](https://github.com/edgelesssys/constellation/tree/main/terraform/infrastructure). - -Find the image reference for your CSP and region, execute: - -```bash -CONSTELL_VER=vX.Y.Z -curl -s https://cdn.confidential.cloud/constellation/v2/ref/-/stream/stable/$CONSTELL_VER/image/info.json | jq -``` - -From the list, select the `reference` for your CSP / Attestation combination and save it in the `IMAGE_REF` environment variable. - -Create a `terraform.tfvars` file. -There, define all needed variables found in `variables.tf` using the values from the `constellation-config.yaml`. - - - - -```bash -echo "name = \"$(yq '.name' constellation-conf.yaml)\"" >> terraform.tfvars -echo "debug = $(yq '.debugCluster' constellation-conf.yaml)" >> terraform.tfvars -echo "custom_endpoint = \"$(yq '.customEndpoint' constellation-conf.yaml)\"" >> terraform.tfvars -echo "node_groups = { - control_plane_default = { - role = \"$(yq '.nodeGroups.control_plane_default.role' constellation-conf.yaml)\" - zone = \"$(yq '.nodeGroups.control_plane_default.zone' constellation-conf.yaml)\" - instance_type = \"$(yq '.nodeGroups.control_plane_default.instanceType' constellation-conf.yaml)\" - disk_size = \"$(yq '.nodeGroups.control_plane_default.stateDiskSizeGB' constellation-conf.yaml)\" - disk_type = \"$(yq '.nodeGroups.control_plane_default.stateDiskType' constellation-conf.yaml)\" - initial_count = \"$(yq '.nodeGroups.control_plane_default.initialCount' constellation-conf.yaml)\" - } - worker_default = { - role = \"$(yq '.nodeGroups.worker_default.role' constellation-conf.yaml)\" - zone = \"$(yq '.nodeGroups.worker_default.zone' constellation-conf.yaml)\" - instance_type = \"$(yq '.nodeGroups.worker_default.instanceType' constellation-conf.yaml)\" - disk_size = \"$(yq '.nodeGroups.worker_default.stateDiskSizeGB' constellation-conf.yaml)\" - disk_type = \"$(yq '.nodeGroups.worker_default.stateDiskType' constellation-conf.yaml)\" - initial_count = \"$(yq '.nodeGroups.worker_default.initialCount' constellation-conf.yaml)\" - } -}" >> terraform.tfvars -echo "iam_instance_profile_control_plane = \"$(yq '.provider.aws.iamProfileControlPlane' constellation-conf.yaml)\"" >> terraform.tfvars -echo "iam_instance_profile_worker_nodes = \"$(yq '.provider.aws.iamProfileWorkerNodes' constellation-conf.yaml)\"" >> terraform.tfvars -echo "region = \"$(yq '.provider.aws.region' constellation-conf.yaml)\"" >> terraform.tfvars -echo "zone = \"$(yq '.provider.aws.zone' constellation-conf.yaml)\"" >> terraform.tfvars -echo "ami = \"$(yq '.provider.aws.zone' constellation-conf.yaml)\"" >> terraform.tfvars -echo "enable_snp = $(yq '.attestation | has("awsSEVSNP")' constellation-conf.yaml)" >> terraform.tfvars -terraform fmt terraform.tfvars -``` - - - - -```bash -echo "name = \"$(yq '.name' constellation-conf.yaml)\"" >> terraform.tfvars -echo "debug = $(yq '.debugCluster' constellation-conf.yaml)" >> terraform.tfvars -echo "custom_endpoint = \"$(yq '.customEndpoint' constellation-conf.yaml)\"" >> terraform.tfvars -echo "image_id = \"$IMAGE_REF\"" >> terraform.tfvars -echo "node_groups = { - control_plane_default = { - role = \"$(yq '.nodeGroups.control_plane_default.role' constellation-conf.yaml)\" - zones = [ \"$(yq '.nodeGroups.worker_default.zone' constellation-conf.yaml)\" ] - instance_type = \"$(yq '.nodeGroups.control_plane_default.instanceType' constellation-conf.yaml)\" - disk_size = \"$(yq '.nodeGroups.control_plane_default.stateDiskSizeGB' constellation-conf.yaml)\" - disk_type = \"$(yq '.nodeGroups.control_plane_default.stateDiskType' constellation-conf.yaml)\" - initial_count = \"$(yq '.nodeGroups.control_plane_default.initialCount' constellation-conf.yaml)\" - } - worker_default = { - role = \"$(yq '.nodeGroups.worker_default.role' constellation-conf.yaml)\" - zones = [ \"$(yq '.nodeGroups.worker_default.zone' constellation-conf.yaml)\" ] - instance_type = \"$(yq '.nodeGroups.worker_default.instanceType' constellation-conf.yaml)\" - disk_size = \"$(yq '.nodeGroups.worker_default.stateDiskSizeGB' constellation-conf.yaml)\" - disk_type = \"$(yq '.nodeGroups.worker_default.stateDiskType' constellation-conf.yaml)\" - initial_count = \"$(yq '.nodeGroups.worker_default.initialCount' constellation-conf.yaml)\" - } -}" >> terraform.tfvars -echo "location = \"$(yq '.provider.azure.location' constellation-conf.yaml)\"" >> terraform.tfvars -echo "create_maa = $(yq '.attestation | has("azureSEVSNP")' constellation-conf.yaml)" >> terraform.tfvars -echo "confidential_vm = $(yq '.attestation | has("azureSEVSNP")' constellation-conf.yaml)" >> terraform.tfvars -echo "secure_boot = $(yq '.provider.azure.secureBoot' constellation-conf.yaml)" >> terraform.tfvars -echo "resource_group = \"$(yq '.provider.azure.resourceGroup' constellation-conf.yaml)\"" >> terraform.tfvars -echo "user_assigned_identity = \"$(yq '.provider.azure.userAssignedIdentity' constellation-conf.yaml)\"" >> terraform.tfvars -terraform fmt terraform.tfvars -``` - - - - -```bash -echo "name = \"$(yq '.name' constellation-conf.yaml)\"" >> terraform.tfvars -echo "debug = $(yq '.debugCluster' constellation-conf.yaml)" >> terraform.tfvars -echo "custom_endpoint = \"$(yq '.customEndpoint' constellation-conf.yaml)\"" >> terraform.tfvars -echo "image_id = \"$IMAGE_REF\"" >> terraform.tfvars -echo "node_groups = { - control_plane_default = { - role = \"$(yq '.nodeGroups.control_plane_default.role' constellation-conf.yaml)\" - zone = \"$(yq '.nodeGroups.control_plane_default.zone' constellation-conf.yaml)\" - instance_type = \"$(yq '.nodeGroups.control_plane_default.instanceType' constellation-conf.yaml)\" - disk_size = \"$(yq '.nodeGroups.control_plane_default.stateDiskSizeGB' constellation-conf.yaml)\" - disk_type = \"$(yq '.nodeGroups.control_plane_default.stateDiskType' constellation-conf.yaml)\" - initial_count = \"$(yq '.nodeGroups.control_plane_default.initialCount' constellation-conf.yaml)\" - } - worker_default = { - role = \"$(yq '.nodeGroups.worker_default.role' constellation-conf.yaml)\" - zone = \"$(yq '.nodeGroups.worker_default.zone' constellation-conf.yaml)\" - instance_type = \"$(yq '.nodeGroups.worker_default.instanceType' constellation-conf.yaml)\" - disk_size = \"$(yq '.nodeGroups.worker_default.stateDiskSizeGB' constellation-conf.yaml)\" - disk_type = \"$(yq '.nodeGroups.worker_default.stateDiskType' constellation-conf.yaml)\" - initial_count = \"$(yq '.nodeGroups.worker_default.initialCount' constellation-conf.yaml)\" - } -}" >> terraform.tfvars -echo "project = \"$(yq '.provider.gcp.project' constellation-conf.yaml)\"" >> terraform.tfvars -echo "region = \"$(yq '.provider.gcp.region' constellation-conf.yaml)\"" >> terraform.tfvars -echo "zone = \"$(yq '.provider.gcp.zone' constellation-conf.yaml)\"" >> terraform.tfvars -terraform fmt terraform.tfvars -``` - - - - -Initialize and apply Terraform to create the configured infrastructure: - -```bash -terraform init -terraform apply -``` - -The Constellation [apply step](#the-apply-step) requires the already created `constellation-config.yaml` and the `constellation-state.yaml`. -Create the `constellation-state.yaml` using the output from the Terraform state and the `constellation-conf.yaml`: - - - - -```bash -yq eval '.version ="v1"' --inplace constellation-state.yaml -yq eval ".infrastructure.initSecret =\"$(terraform output initSecret | jq -r | tr -d '\n' | hexdump -ve '/1 "%02x"' && echo '')\"" --inplace constellation-state.yaml -yq eval ".infrastructure.clusterEndpoint =\"$(terraform output out_of_cluster_endpoint | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.inClusterEndpoint =\"$(terraform output in_cluster_endpoint | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.ipCidrNode =\"$(terraform output ip_cidr_nodes | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.uid =\"$(terraform output uid | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.name =\"$(terraform output name | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.apiServerCertSANs =$(terraform output -json api_server_cert_sans)" --inplace constellation-state.yaml -``` + - - +Self-managed infrastructure allows for more flexibility in the setup, by excluding the default infrastructure setup from the Constellation cluster management. +This provides flexibility in DevOps and can meet potential regulatory requirements. +We recommend using Terraform for infrastructure management, but you can use any tool of your choice. :::info - If the enforcement policy is set to `MAAFallback` in `constellation-config.yaml`, a manual update to the MAA provider's policy is necessary. - You can apply the update with the following commands, where `` is the version of Constellation that should be set up. (e.g. `v2.12.0`) - - ```bash - git clone --branch https://github.com/edgelesssys/constellation - cd constellation/hack/maa-patch - go run . $(terraform output attestationURL | jq -r) - ``` + When using Terraform, you can use the [Terraform module](./terraform-module.md) for ease of use to manage the entire Constellation cluster. ::: -```bash -yq eval '.version ="v1"' --inplace constellation-state.yaml -yq eval ".infrastructure.initSecret =\"$(terraform output initSecret | jq -r | tr -d '\n' | hexdump -ve '/1 "%02x"' && echo '')\"" --inplace constellation-state.yaml -yq eval ".infrastructure.clusterEndpoint =\"$(terraform output out_of_cluster_endpoint | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.inClusterEndpoint =\"$(terraform output in_cluster_endpoint | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.ipCidrNode =\"$(terraform output ip_cidr_nodes | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.uid =\"$(terraform output uid | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.name =\"$(terraform output name | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.apiServerCertSANs =$(terraform output -json api_server_cert_sans)" --inplace constellation-state.yaml -yq eval ".infrastructure.azure.resourceGroup =\"$(terraform output resource_group | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.azure.subscriptionID =\"$(terraform output subscription_id | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.azure.networkSecurityGroupName =\"$(terraform output network_security_group_name | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.azure.loadBalancerName =\"$(terraform output loadbalancer_name | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.azure.userAssignedIdentity =\"$(terraform output user_assigned_identity_client_id | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.azure.attestationURL =\"$(terraform output attestationURL | jq -r)\"" --inplace constellation-state.yaml -``` - - - - -```bash -yq eval '.version ="v1"' --inplace constellation-state.yaml -yq eval ".infrastructure.initSecret =\"$(terraform output initSecret | jq -r | tr -d '\n' | hexdump -ve '/1 "%02x"' && echo '')\"" --inplace constellation-state.yaml -yq eval ".infrastructure.clusterEndpoint =\"$(terraform output out_of_cluster_endpoint | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.inClusterEndpoint =\"$(terraform output in_cluster_endpoint | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.ipCidrNode =\"$(terraform output ip_cidr_nodes | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.uid =\"$(terraform output uid | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.name =\"$(terraform output name | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.apiServerCertSANs =$(terraform output -json api_server_cert_sans)" --inplace constellation-state.yaml -yq eval ".infrastructure.gcp.projectID =\"$(terraform output project | jq -r)\"" --inplace constellation-state.yaml -yq eval ".infrastructure.gcp.ipCidrPod =\"$(terraform output ip_cidr_pods | jq -r)\"" --inplace constellation-state.yaml -``` - - - - - - -Self-managed infrastructure allows for managing the cloud resources necessary for a Constellation cluster separate from the Constellation CLI. -This provides flexibility in DevOps and can meet potential regulatory requirements. - -To self-manage the infrastructure of your cluster, download the Terraform files for the selected CSP from the [Constellation GitHub repository](https://github.com/edgelesssys/constellation/tree/main/terraform/infrastructure). -They contain a minimum configuration for the resources necessary to run a Constellation cluster on the corresponding CSP. From this base, you can now add, edit, or substitute resources per your own requirements with the infrastructure +If using a tool other than Terraform, you can still refer to the Terraform files for the selected CSP from the [Constellation GitHub repository](https://github.com/edgelesssys/constellation/tree/main/terraform/infrastructure) for a minimum Constellation cluster configuration. From this base, you can now add, edit, or substitute resources per your own requirements with the infrastructure management tooling of your choice. You need to keep the essential functionality of the base configuration in order for your cluster to function correctly. :::info diff --git a/docs/docs/workflows/terraform-module.md b/docs/docs/workflows/terraform-module.md index 61f1b6dc7b5..3aa14c161b3 100644 --- a/docs/docs/workflows/terraform-module.md +++ b/docs/docs/workflows/terraform-module.md @@ -7,7 +7,7 @@ The necessary module package is available as part of the release and consists of - a Terraform installation of at least `v1.4.4` ## Quick setup -The convenience module allows to set up a Constellation cluster with a single module including all configurability that's otherwise possible through the CLI. It's easiest to consume the module through a remote source, as shown below. +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. In all examples, remember to replace `$VERSION` with the desired version, e.g., `v2.13.0`. @@ -18,7 +18,7 @@ In all examples, remember to replace `$VERSION` with the desired version, e.g., cd c11n ``` -2. Create a `main.tf` file to call the CSP specific Constellation module. +1. Create a `main.tf` file to call the CSP specific Constellation module. @@ -110,16 +110,16 @@ Using the remote URL of the terraform-module zip as source, the instructions ins 1. Update the `source` field by inserting the `$NEW_VERSION`. ``` source = "https://github.com/edgelesssys/constellation/releases/download/$NEW_VERSION/terraform-module.zip//modules/$CSP-constellation" # TODO check the link during the release. - ``` + ``` 2. (Optional) Update the image version. `image` is a mandatory field and needs to be updated to `$NEW_VERSION` to perform a node image upgrade. 3. (Optional) Update the Kubernetes version. - If `kubernetes_version` isn't set, the latest version default on the newer Constellation release will be used, which might imply a Kubernetes upgrade. If you want to avoid implicit upgrades, explicitly set the field. For the versions support refer to [Kubernetes support policy](../architecture/versions.md#kubernetes-support-policy) + If `kubernetes_version` isn't set, the latest version default on the newer Constellation release will be used, which might imply a Kubernetes upgrade. If you want to avoid implicit upgrades, explicitly set the field. For the supported versions, refer to [Kubernetes support policy](../architecture/versions.md#kubernetes-support-policy). - #TODO should we add the info from [version support](/dev-docs/workflows/versions-support.md) on the official page to provide info on image / microservice support too? + #TODO should we add the info from /dev-docs/workflows/versions-support.md on the official page to provide info on image / microservice support too? 4. (Optional) Update the microservice version.