mirror of
https://github.com/edgelesssys/constellation.git
synced 2025-09-20 21:14:37 -04:00
terraform-provider: cleanup and improve docs (#2685)
Co-authored-by: Moritz Sanft <58110325+msanft@users.noreply.github.com>
This commit is contained in:
Adrian Stobbe
GitHub
parent
9a4e96905f
commit
37580009fe
25 changed files with 262 additions and 592 deletions
|
|
@ -45,7 +45,7 @@ It's recommended to use Terraform for infrastructure management, but you can use
|
|||
|
||||
:::info
|
||||
|
||||
When using Terraform, you can use the [Terraform module](./terraform-module.md) for ease of use to manage the entire Constellation cluster.
|
||||
When using Terraform, you can use the [Terraform provider](./terraform-provider.md) to manage the entire Constellation cluster lifecycle.
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -1,151 +0,0 @@
|
|||
# Use the Terraform module
|
||||
You can manage a Constellation cluster through Terraform.
|
||||
The module package is available as part of the [GitHub release](https://github.com/edgelesssys/constellation/releases/). It consists of a convenience module for each cloud service provider (`{csp}-constellation`) that combines the IAM (`infrastructure/{csp}/iam`), infrastructure (`infrastructure/{csp}`), and constellation (`constellation-cluster`) modules.
|
||||
|
||||
## Prerequisites
|
||||
- a Linux / Mac operating system
|
||||
- a Terraform installation of version `v1.4.4` or above
|
||||
|
||||
## Quick setup
|
||||
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.
|
||||
|
||||
:::caution
|
||||
|
||||
In the current release of the module, `terraform apply` creates files such as `constellation-conf.yaml`, `constellation-state.yaml` , `constellation-admin.conf`, `constellation-mastersecret.json`, and a directory `constellation-terraform"` containing backups. Make sure to check in these files in your version control when using GitOps.
|
||||
The files are deleted on `terraform destroy`.
|
||||
|
||||
:::
|
||||
|
||||
1. Create a directory (workspace) for your Constellation cluster.
|
||||
```bash
|
||||
mkdir constellation-workspace
|
||||
cd constellation-workspace
|
||||
```
|
||||
|
||||
1. Create a `main.tf` file to call the CSP specific Constellation module.
|
||||
|
||||
<tabs groupId="csp">
|
||||
|
||||
<tabItem value="azure" label="Azure">
|
||||
|
||||
```
|
||||
module "azure-constellation" {
|
||||
source = "https://github.com/edgelesssys/constellation/releases/download/<version>/terraform-module.zip//terraform-module/legacy-module/azure-constellation" // replace <version> with a Constellation version, e.g., v2.13.0
|
||||
name = "constell"
|
||||
location = "northeurope"
|
||||
service_principal_name = "az-sp"
|
||||
resource_group_name = "constell-rg"
|
||||
node_groups = {
|
||||
control_plane_default = {
|
||||
role = "control-plane"
|
||||
instance_type = "Standard_DC4as_v5"
|
||||
disk_size = 30
|
||||
disk_type = "Premium_LRS"
|
||||
initial_count = 3
|
||||
},
|
||||
worker_default = {
|
||||
role = "worker"
|
||||
instance_type = "Standard_DC4as_v5"
|
||||
disk_size = 30
|
||||
disk_type = "Premium_LRS"
|
||||
initial_count = 2
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</tabItem>
|
||||
|
||||
<tabItem value="aws" label="AWS">
|
||||
|
||||
```
|
||||
module "aws-constellation" {
|
||||
source = "https://github.com/edgelesssys/constellation/releases/download/<version>/terraform-module.zip//terraform-module/legacy-module/aws-constellation" // replace <version> with a Constellation version, e.g., v2.13.0
|
||||
name = "constell"
|
||||
zone = "us-east-2c"
|
||||
name_prefix = "example"
|
||||
node_groups = {
|
||||
control_plane_default = {
|
||||
role = "control-plane"
|
||||
zone = "us-east-2c"
|
||||
instance_type = "m6a.xlarge"
|
||||
disk_size = 30
|
||||
disk_type = "gp3"
|
||||
initial_count = 3
|
||||
},
|
||||
worker_default = {
|
||||
role = "worker"
|
||||
zone = "us-east-2c"
|
||||
instance_type = "m6a.xlarge"
|
||||
disk_size = 30
|
||||
disk_type = "gp3"
|
||||
initial_count = 2
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</tabItem>
|
||||
|
||||
<tabItem value="gcp" label="GCP">
|
||||
|
||||
```
|
||||
module "gcp-constellation" {
|
||||
source = "https://github.com/edgelesssys/constellation/releases/download/<version>/terraform-module.zip//terraform-module/legacy-module/gcp-constellation" // replace <version> with a Constellation version, e.g., v2.13.0
|
||||
name = "constell"
|
||||
project = "constell-proj" // replace with your project id
|
||||
service_account_id = "constid"
|
||||
zone = "europe-west2-a"
|
||||
node_groups = {
|
||||
control_plane_default = {
|
||||
role = "control-plane"
|
||||
zone = "europe-west2-a"
|
||||
instance_type = "n2d-standard-4"
|
||||
disk_size = 30
|
||||
disk_type = "pd-ssd"
|
||||
initial_count = 3
|
||||
},
|
||||
worker_default = {
|
||||
role = "worker"
|
||||
zone = "europe-west2-a"
|
||||
instance_type = "n2d-standard-4"
|
||||
disk_size = 30
|
||||
disk_type = "pd-ssd"
|
||||
initial_count = 2
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</tabItem>
|
||||
</tabs>
|
||||
|
||||
3. Initialize and apply the module.
|
||||
```bash
|
||||
terraform init
|
||||
terraform apply
|
||||
```
|
||||
|
||||
## Custom setup
|
||||
If you need to separate IAM and cluster management or need custom infrastructure, you can also call the submodules individually.
|
||||
Look at the respective convenience module (`{csp}-constellation`) for how you can structure the module calls.
|
||||
The submodules are:
|
||||
- `constellation-cluster`: manages the Constellation cluster
|
||||
- `fetch-image`: translates the Constellation image version to the image ID of the cloud service provider
|
||||
- `infrastructure/{csp}`: contains the cluster infrastructure resources
|
||||
- `infrastructure/iam/{csp}`: contains the IAM resources used within the cluster
|
||||
|
||||
## Cluster upgrades
|
||||
:::tip
|
||||
For general information on cluster upgrades, see [Upgrade your cluster](./upgrade.md).
|
||||
:::
|
||||
|
||||
Using a [remote address as module source](https://developer.hashicorp.com/terraform/language/modules/sources#fetching-archives-over-http) as shown in [Quick setup](#quick-setup) is recommended because it simplifies the upgrade process. For [local paths as module source](https://developer.hashicorp.com/terraform/language/modules/sources#local-paths), you would need to manually overwrite the Terraform files in the Terraform workspace. The steps for the remote source setup are as follows:
|
||||
|
||||
1. Update the `<version>` variable inside the `source` field of the module.
|
||||
2. Upgrade the Terraform module and provider dependencies and apply the Constellation upgrade.
|
||||
```bash
|
||||
terraform init -upgrade
|
||||
terraform apply
|
||||
```
|
||||
72
docs/docs/workflows/terraform-provider.md
Normal file
72
docs/docs/workflows/terraform-provider.md
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
# Use the Terraform provider
|
||||
|
||||
The Constellation Terraform provider allows to manage the full lifecycle of a Constellation cluster (namely creation, upgrades, and deletion) via Terraform.
|
||||
<!-- TODO(elchead): check link during release -->
|
||||
The provider is available through the [Terraform registry](https://registry.terraform.io/providers/edgelesssys/constellation/latest) and is released in lock-step with Constellation releases.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- a Linux / Mac operating system (ARM64/AMD64)
|
||||
- a Terraform installation of version `v1.4.4` or above
|
||||
|
||||
## Quick setup
|
||||
|
||||
This example shows how to set up a Constellation cluster with the reference IAM and infrastructure setup. This setup is also used when creating a Constellation cluster through the Constellation CLI. You can either consume the IAM / infrastructure modules through a remote source (recommended) or local files. The latter requires downloading the infrastructure and IAM modules for the corresponding CSP from `terraform-modules.zip` on the [Constellation release page](https://github.com/edgelesssys/constellation/releases/latest) and placing them in the Terraform workspace directory.
|
||||
|
||||
1. Create a directory (workspace) for your Constellation cluster.
|
||||
|
||||
```bash
|
||||
mkdir constellation-workspace
|
||||
cd constellation-workspace
|
||||
```
|
||||
|
||||
1. Create a `main.tf` file.
|
||||
<!--TODO(elchead): AB#3607 put correct examples, with follow up PR with #2713 examples
|
||||
<tabs groupId="csp">
|
||||
|
||||
<tabItem value="azure" label="Azure">
|
||||
</tabItem>
|
||||
|
||||
<tabItem value="aws" label="AWS">
|
||||
</tabItem>
|
||||
|
||||
<tabItem value="gcp" label="GCP">
|
||||
</tabItem>
|
||||
</tabs>-->
|
||||
|
||||
1. Initialize and apply the file.
|
||||
|
||||
```bash
|
||||
terraform init
|
||||
terraform apply
|
||||
```
|
||||
|
||||
## Bringing your own infrastructure
|
||||
|
||||
If you need a custom infrastructure setup, you can download the infrastructure / IAM Terraform modules for the respective CSP from the Constellation [GitHub releases](https://github.com/edgelesssys/constellation/releases). You can modify / extend the modules, per your requirements, while keeping the basic functionality intact.
|
||||
The module contains:
|
||||
|
||||
- `{csp}`: cloud resources the cluster runs on
|
||||
- `iam/{csp}`: IAM resources used within the cluster
|
||||
|
||||
When upgrading your cluster, make sure to check the Constellation release notes for potential breaking changes in the reference infrastructure / IAM modules that need to be considered.
|
||||
|
||||
## Cluster upgrades
|
||||
|
||||
:::tip
|
||||
For general information on cluster upgrades, see the [dedicated upgrade page](./upgrade.md).
|
||||
:::
|
||||
|
||||
The steps for applying the upgrade are as follows:
|
||||
|
||||
1. Update the version constraint of the Constellation Terraform provider in the `required_providers` block in your Terraform configuration.
|
||||
2. If you explicitly set any of the version attributes of the provider's resources and data sources (e.g. `image_version` or `constellation_microservice_version`), make sure to update them too. Refer to the [version support policy](https://github.com/edgelesssys/constellation/blob/main/dev-docs/workflows/versions-support.md) for more information on how each Constellation version and its dependencies are supported.
|
||||
3. Update the IAM / infrastructure modules.
|
||||
- For [remote address as module source](https://developer.hashicorp.com/terraform/language/modules/sources#fetching-archives-over-http), update the version number inside the address of the `source` field of the infra / IAM module to the target version.
|
||||
- For [local paths as module source](https://developer.hashicorp.com/terraform/language/modules/sources#local-paths), see the changes made in the reference modules since the upgrade's origin version and adjust your infrastructure configuration accordingly.
|
||||
4. Upgrade the Terraform module and provider dependencies and apply the targeted configuration.
|
||||
|
||||
```bash
|
||||
terraform init -upgrade
|
||||
terraform apply
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue