docs: add docs on general Terraform usage (#1263)

* add docs on general tf usage

* reminder to not delete terraform dir

* fix spelling check

* add to sidebar

* reference terraform page

* embed link into natural language

* mention iam folder

* separate hack tools from official tf docs

* assume familiarity with tf

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:

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

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.

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

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.
 
 </tabItem>
 <tabItem value="terraform" label="Terraform">
 
-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).
 

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
 

docs/sidebars.js

@@ -261,6 +261,11 @@ const sidebars = {
           label: 'SLSA adoption',
           id: 'reference/slsa',
         },
+        {
+          type: 'doc',
+          label: 'Terraform Usage',
+          id: 'reference/terraform',
+        },
       ],
     },
   ],