From 03154c6e6456b14a1c6416a92516c8e6b9fa6348 Mon Sep 17 00:00:00 2001 From: 3u13r Date: Mon, 23 Jan 2023 10:37:28 +0100 Subject: [PATCH] docs: document terraform support (#1037) --- .../terraform/terraform/aws/variables.tf | 12 ++++++ docs/docs/getting-started/first-steps.md | 5 ++- docs/docs/workflows/create.md | 42 +++++++++++++++++++ docs/docs/workflows/terminate.md | 21 ++++++++++ 4 files changed, 79 insertions(+), 1 deletion(-) diff --git a/cli/internal/terraform/terraform/aws/variables.tf b/cli/internal/terraform/terraform/aws/variables.tf index 68adf2f3e..6f8588873 100644 --- a/cli/internal/terraform/terraform/aws/variables.tf +++ b/cli/internal/terraform/terraform/aws/variables.tf @@ -1,6 +1,11 @@ variable "name" { type = string + default = "constell" description = "Name of your Constellation" + validation { + condition = length(var.name) < 10 + error_message = "The name of the Constellation must be shorter than 10 characters" + } } variable "iam_instance_profile_worker_nodes" { @@ -20,11 +25,13 @@ variable "instance_type" { variable "state_disk_type" { type = string + default = "gp2" description = "EBS disk type for the state disk of the nodes" } variable "state_disk_size" { type = number + default = 30 description = "Disk size for the state disk of the nodes [GB]" } @@ -41,6 +48,10 @@ variable "worker_count" { variable "ami" { type = string description = "AMI ID" + validation { + condition = length(var.ami) > 4 && substr(var.ami, 0, 4) == "ami-" + error_message = "The image_id value must be a valid AMI id, starting with \"ami-\"." + } } variable "region" { @@ -55,5 +66,6 @@ variable "zone" { variable "debug" { type = bool + default = false description = "Enable debug mode. This opens up a debugd port that can be used to deploy a custom bootstrapper." } diff --git a/docs/docs/getting-started/first-steps.md b/docs/docs/getting-started/first-steps.md index a4cde8462..4e89bb0f2 100644 --- a/docs/docs/getting-started/first-steps.md +++ b/docs/docs/getting-started/first-steps.md @@ -9,7 +9,7 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step ## Create a cluster -1. Create the configuration file and IAM resources for your selected cloud provider +1. Create the configuration file and IAM resources for your selected cloud provider First, you need to create a [configuration file](../workflows/config.md) and an [IAM configuration](../workflows/config.md#creating-an-iam-configuration). The easiest way to do this is the following CLI command: @@ -76,6 +76,7 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step --> 2. Create the cluster with one control-plane node and two worker nodes. `constellation create` uses options set in `constellation-conf.yaml`. + If you want to use Terraform for managing the cloud resources instead, follow the corresponding instructions in the [Create workflow](../workflows/create.md). :::tip @@ -150,6 +151,8 @@ If you don't have a cloud subscription, check out [MiniConstellation](first-step ## Terminate your cluster +Use the CLI to terminate your cluster. If you used Terraform to manage your cloud resources, follow the corresponding instructions in the [Terminate workflow](../workflows/terminate.md). + ```bash constellation terminate ``` diff --git a/docs/docs/workflows/create.md b/docs/docs/workflows/create.md index b4d60ecc4..8e42eb130 100644 --- a/docs/docs/workflows/create.md +++ b/docs/docs/workflows/create.md @@ -18,6 +18,9 @@ Before you create the cluster, make sure to have a [valid configuration file](./ ### Create + + + Choose the initial size of your cluster. The following command creates a cluster with one control-plane and two worker nodes: @@ -29,6 +32,45 @@ For details on the flags, consult the command help via `constellation create -h` *create* stores your cluster's state into a [`terraform.tfstate`](../architecture/orchestration.md#cluster-creation-process) file in your workspace. + + + +Constellation supports managing the infrastructure via Terraform. This allows for an easier GitOps integration as well as meeting regulatory requirements. +Since the Constellation CLI also uses Terraform under the hood, you can reuse the same Terraform files. +For now, please 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/cli/internal/terraform/terraform). + +Create a `terraform.tfvars` file. +There, define all needed variables found in `variables.tf` using the values from the `constellation-config.yaml`. + +To find the image reference for your CSP and region, execute: + +```bash +CONSTELL_VER=vX.Y.Z +curl -s https://cdn.confidential.cloud/constellation/v1/ref/-/stream/stable/$CONSTELL_VER/image/info.json | jq +``` + +Initialize and apply Terraform to create the configured infrastructure: + +```bash +terraform init +terraform apply +``` + +The Constellation [init step](#the-init-step) requires the already created `constellation-config.yaml` and the `constellation-id.json`. +Create the `constellation-id.json` using the output from the Terraform state and the `constellation-conf.yaml`: + +```bash +CONSTELL_IP=$(terraform output ip) +CONSTELL_INIT_SECRET=$(terraform output initSecret | jq -r | tr -d '\n' | base64) +CONSTELL_CSP=$(cat constellation-conf.yaml | yq ".provider | keys | .[0]") +jq --null-input --arg cloudprovider "$CONSTELL_CSP" --arg ip "$CONSTELL_IP" --arg initsecret "$CONSTELL_INIT_SECRET" '{"cloudprovider":$cloudprovider,"ip":$ip,"initsecret":$initsecret}' > constellation-id.json +``` + + + + ## The *init* step The following command initializes and bootstraps your cluster: diff --git a/docs/docs/workflows/terminate.md b/docs/docs/workflows/terminate.md index 2b2718675..b4d50dbfb 100644 --- a/docs/docs/workflows/terminate.md +++ b/docs/docs/workflows/terminate.md @@ -8,6 +8,8 @@ All ephemeral storage and state of your cluster will be lost. Make sure any data ::: + + Terminate the cluster by running: ```bash @@ -29,3 +31,22 @@ Termination can fail if additional resources have been created that depend on th resources manually. Just run the `terminate` command again afterward to continue the termination process of the cluster. ::: + + + +Terminate the cluster by running: + +```bash +terraform destroy +``` + +Delete all files that are no longer needed: + +```bash +rm constellation-id.json constellation-admin.conf +``` + +Only the `constellation-mastersecret.json` and the configuration file remain. + + +