diff --git a/docs/docs/architecture/orchestration.md b/docs/docs/architecture/orchestration.md index 098c0b4f4..33840d0e6 100644 --- a/docs/docs/architecture/orchestration.md +++ b/docs/docs/architecture/orchestration.md @@ -23,11 +23,9 @@ Altogether, the following files are generated during the creation of a Constella * a configuration file * an ID file * a Base64-encoded master secret -* Terraform artifacts such as `terraform.tfstate` +* [Terraform artifacts](../reference/terraform.md), stored in the `constellation-terraform` and `constellation-iam-terraform` subdirectories * a Kubernetes `kubeconfig` file. -Constellation uses Terraform for infrastructure management. No setup of Terraform is needed. The CLI automatically fetches a copy of Terraform when required. - After the creation of your cluster, the CLI will provide you with a Kubernetes `kubeconfig` file. This file grants you access to your Kubernetes cluster and configures the [kubectl](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) tool. In addition, the cluster's [identifier](orchestration.md#post-installation-configuration) is returned and stored in a file called `constellation-id.json` @@ -51,7 +49,7 @@ Post-installation the CLI provides a configuration for [accessing the cluster us The `kubeconfig` file provides the credentials and configuration for connecting and authenticating to the API server. Once configured, orchestrate the Kubernetes cluster via `kubectl`. -Make sure to keep the state files such as `terraform.tfstate` in the workspace directory to be able to manage your cluster later on. +Make sure to keep the Terraform subdirectory such as `constellation-terraform` in the workspace directory to be able to manage your cluster later on. Without it, you won't be able to modify or terminate your cluster. After the initialization, the CLI will present you with a couple of tokens: diff --git a/docs/docs/getting-started/first-steps.md b/docs/docs/getting-started/first-steps.md index 01b2964d1..43affcbca 100644 --- a/docs/docs/getting-started/first-steps.md +++ b/docs/docs/getting-started/first-steps.md @@ -76,7 +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). + If you want to manually use [Terraform](../reference/terraform.md) for managing the cloud resources instead, follow the corresponding instructions in the [Create workflow](../workflows/create.md). :::tip @@ -151,7 +151,7 @@ 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). +Use the CLI to terminate your cluster. If you manually used [Terraform](../reference/terraform.md) to manage your cloud resources, follow the corresponding instructions in the [Terminate workflow](../workflows/terminate.md). ```bash constellation terminate diff --git a/docs/docs/reference/terraform.md b/docs/docs/reference/terraform.md new file mode 100644 index 000000000..5284d4caa --- /dev/null +++ b/docs/docs/reference/terraform.md @@ -0,0 +1,22 @@ +# Terraform Usage + +[Terraform](https://www.terraform.io/) is an open-source Infrastructure as Code (IaC) framework which is being used by multiple Constellation components to manage cloud resources. This page describes our policy on using Terraform in Constellation. + +:::info +This page assumes familiarity with Terraform. Refer to the [Terraform documentation](https://developer.hashicorp.com/terraform/docs) for an introduction. +::: + +## Interacting with Terraform manually + +Manual interaction with Terraform state created by Constellation (i.e. via the Terraform CLI) should only be performed by experienced users and only if absolutely necessary, as it may lead to unrecoverable loss of cloud resources. For the vast majority of users and use-cases, the interaction done by the [Constellation CLI](cli.md) is sufficient. + +## Terraform state files + +Constellation keeps Terraform state files in subdirectories together with the corresponding Terraform configuration files and metadata. When first performing an action in the Constellation CLI which uses Terraform internally, the needed subdirectory will be created. + +Currently, these subdirectories are: + +* `constellation-terraform` - Terraform state files for the resources used for the Constellation cluster +* `constellation-iam-terraform` - Terraform state files for IAM configuration + +When working with either of the files, i.e. when running `constellation terminate` to [terminate a cluster](../workflows/terminate.md) (and delete it's cloud resources), the `constellation terraform` subdirectory needs to be in the current working directory. The same applies to the `constellation-iam-terraform` subdirectory when working with IAM configuration. The state directories shouldn't be deleted manually. diff --git a/docs/docs/workflows/config.md b/docs/docs/workflows/config.md index 222242f6f..d8693a874 100644 --- a/docs/docs/workflows/config.md +++ b/docs/docs/workflows/config.md @@ -231,13 +231,13 @@ The following describes the configuration fields and how you obtain the required * **iamProfileControlPlane**: The name of an IAM instance profile attached to all control-plane nodes. - 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`. + The resource can be created 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`. 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. - 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`. + The resource can be created 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`. 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`. @@ -254,7 +254,7 @@ You can keep created IAM configurations and reuse them for new clusters. Alterna **Prerequisites:** * [Terraform](https://developer.hashicorp.com/terraform/downloads) is installed on your machine. -* Access to the `terraform.tfstate` file created by the `constellation iam create` command. +* Access to the [`constellation-iam-terraform`](../reference/terraform.md) directory created by the `constellation iam create` command. You can delete the IAM configuration by executing the following command in the same directory where you executed `constellation iam create`: ```bash diff --git a/docs/docs/workflows/create.md b/docs/docs/workflows/create.md index 8e42eb130..dabf74f41 100644 --- a/docs/docs/workflows/create.md +++ b/docs/docs/workflows/create.md @@ -30,14 +30,18 @@ constellation create --control-plane-nodes 1 --worker-nodes 2 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. +*create* stores your cluster's state in a [`constellation-terraform`](../architecture/orchestration.md#cluster-creation-process) directory in your workspace. -Constellation supports managing the infrastructure via Terraform. This allows for an easier GitOps integration as well as meeting regulatory requirements. +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. -For now, please refrain from changing the Terraform resource definitions, as Constellation is tightly coupled to them. + +:::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/cli/internal/terraform/terraform). diff --git a/docs/docs/workflows/terminate.md b/docs/docs/workflows/terminate.md index a2556fe95..a2409e475 100644 --- a/docs/docs/workflows/terminate.md +++ b/docs/docs/workflows/terminate.md @@ -1,6 +1,6 @@ # Terminate your cluster -You can terminate your cluster using the CLI. For this, you need the Terraform state directory named `constellation-terraform` in the current directory. +You can terminate your cluster using the CLI. For this, you need the Terraform state directory named [`constellation-terraform`](../reference/terraform.md) in the current directory. :::danger diff --git a/docs/sidebars.js b/docs/sidebars.js index 938cb2a93..126832527 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -261,6 +261,11 @@ const sidebars = { label: 'SLSA adoption', id: 'reference/slsa', }, + { + type: 'doc', + label: 'Terraform Usage', + id: 'reference/terraform', + }, ], }, ],