docs: add Terraform module #2560

elchead · 2023-11-07T14:42:20Z

Still waiting for all TF modules to be merged and not sure yet about the exact release path. Is on hold until then.

Context

This adds user-facing docs on how to use the Terraform module.

Proposed change(s)

make image variable optional in high level CSP modules

Additional info

AB#3522

Checklist

Update docs
Add labels (e.g., for changelog category)
Is PR title adequate for changelog?
Link to Milestone

netlify · 2023-11-07T14:43:57Z

✅ Deploy Preview for constellation-docs ready!

Name	Link
🔨 Latest commit	`9566552`
🔍 Latest deploy log	https://app.netlify.com/sites/constellation-docs/deploys/655636e2647fda000829f98c
😎 Deploy Preview	https://deploy-preview-2560--constellation-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

docs/sidebars.js

docs/docs/workflows/terraform-module.md

m1ghtym0 · 2023-11-10T16:05:17Z

Preview: https://deploy-preview-86--edgeless-docs.netlify.app/constellation/reference/terraform

elchead · 2023-11-10T16:19:45Z

Preview: https://deploy-preview-86--edgeless-docs.netlify.app/constellation/reference/terraform

this is the relevant link
https://deploy-preview-86--edgeless-docs.netlify.app/constellation/next/workflows/terraform-module
and
https://deploy-preview-86--edgeless-docs.netlify.app/constellation/next/workflows/create

m1ghtym0

Just from reading over everything, I'd say we could be a bit more elaborate on the steps. I'll test the module myself. Duo to vacation will only be able to do so in 2 weeks, if there is someone quicker than me @thomasten, please don't see this as a blocker.
Ideally someone with low terraform knowledge (like me) would do this as a rubber duck debugging.

docs/docs/workflows/create.md

docs/docs/workflows/terraform-module.md

thomasten · 2023-11-12T20:23:13Z

docs/docs/workflows/terraform-module.md

+- `infrastructure/iam/{csp}`: contains the resources to set up IAM
+
+## Cluster upgrades
+Using the remote URL of the terraform-module zip as source, the instructions inside your `main.tf` file are as follows:


I don't understand this sentence

tried to make it more clear

docs/docs/workflows/terraform-module.md

thomasten · 2023-11-12T20:35:24Z

docs/docs/workflows/terraform-module.md

+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 supported versions, refer to [Kubernetes support policy](../architecture/versions.md#kubernetes-support-policy).
+
+    #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.
+
+    If `microservice_version` isn't set, the new version of the Constellation release will be used. This is a reasonable default, but you might want to prevent implicit upgrades by explicitly setting the field.


It's hard to understand for users when they should do what. For upgrading with the CLI, we just say that skipping one of these is only for "advanced users." Maybe we should limit this workflow to the default case?

What's a good way to explain this fields then to the user since they are exposed as variables in the module. Should we add "ADVANCED USAGE:" to the description of the terraform variable to advise the user to not touch it?

We could add this hint to microservice_version.
For image, I'd just describe it as a non-optional step.
kubernetes_version might be easy enough to be understandable.

What do you think?
Did I forget something?

Moritz was against adding the hint. I went with limiting the workflow to the default case and removed the config steps.

In my opinion, we should not have such "hints" in the variable descriptions, as we currently don't have these in the config either, which could create uncertainty on what is "correct". We already say that there are defaults in the variable descriptions, which is enough in my opinion.

docs/docs/workflows/terraform-module.md

docs/docs/workflows/create.md

docs/docs/workflows/terraform-module.md

we need to address any other improvements in a future PR to not block the release

.github/workflows/release.yml

msanft · 2023-11-13T16:26:17Z

docs/docs/workflows/create.md

@@ -266,7 +68,7 @@ management tooling of your choice. You need to keep the essential functionality

 Make sure all necessary resources are created, e.g., through checking your CSP's portal and retrieve the necessary values, aligned with the outputs (specified in `outputs.tf`) of the base configuration.

-Fill these outputs into the corresponding fields of the `constellation-state.yaml` file. For example, fill the IP or DNS name your cluster can be reached at into the `.Infrastructure.ClusterEndpoint` field.
+Fill these outputs into the corresponding fields of the `Infrastructure` block inside the `constellation-state.yaml` file. For example, fill the IP or DNS name your cluster can be reached at into the `.Infrastructure.ClusterEndpoint` field.


Idea for making it less "handwavy":

Move the bash snippets from above here and say that they'll work for the default but have to be adjusted accordingly if the outputs are changed by the modifications made by the user. Just as an idea, does not have to be implemented here necessarily. We could keep track of it while linking this PR if we want to do it at some point though.

I tracked it in the docs ticket AB#3532

docs/docs/workflows/terraform-module.md

This reverts commit a983942.

msanft

2 small nits. Other than that, the content looks okay to me, under the premise of the follow-up ticket. Can't say much regarding wording, etc., which should probably be checked by @thomasten

docs/docs/workflows/terraform-module.md

Co-authored-by: Thomas Tendyck <[email protected]>

docs/docs/workflows/terraform-module.md

thomasten · 2023-11-16T12:07:06Z

docs/docs/workflows/terraform-module.md

+
+:::caution
+
+The current module still relies on the Constellation CLI. Consequently, `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.


Do all of these files have to be kept?

No, but most of them. constellation.conf.yaml could be reconstructed, but the rest contains cluster information from the apply command.

docs/docs/workflows/terraform-module.md

Co-authored-by: Thomas Tendyck <[email protected]>

thomasten · 2023-11-16T15:29:50Z

docs/docs/workflows/terraform-module.md

+
+  ```
+  module "azure-constellation" {
+    source = "https://github.com/edgelesssys/constellation/releases/download/<version>/terraform-module.zip//terraform-module/azure-constellation" // insert Constellation version here.


Suggested change

source = "https://github.com/edgelesssys/constellation/releases/download/<version>/terraform-module.zip//terraform-module/azure-constellation" // insert Constellation version here.

// replace <version> with a Constellation version, e.g., v2.13.0

source = "https://github.com/edgelesssys/constellation/releases/download/<version>/terraform-module.zip//terraform-module/azure-constellation"

The comment at the end of the line can easily be overlooked.

We should give a hint on the format of the version number.

elchead requested a review from m1ghtym0 November 7, 2023 14:53

elchead marked this pull request as ready for review November 7, 2023 14:56

elchead requested a review from thomasten as a code owner November 7, 2023 14:56

elchead force-pushed the doc/cli/terraform-module branch from 0d79aa2 to d436d28 Compare November 7, 2023 18:29

thomasten requested changes Nov 9, 2023

View reviewed changes

elchead force-pushed the doc/cli/terraform-module branch 2 times, most recently from 5590366 to b01e13a Compare November 9, 2023 15:42

elchead requested review from thomasten and msanft November 9, 2023 15:45

elchead added the hold This cannot be merged right now label Nov 9, 2023

m1ghtym0 previously requested changes Nov 10, 2023

View reviewed changes

docs/docs/workflows/create.md Show resolved Hide resolved

thomasten reviewed Nov 12, 2023

View reviewed changes

thomasten reviewed Nov 13, 2023

View reviewed changes

docs/docs/workflows/terraform-module.md Outdated Show resolved Hide resolved

msanft requested changes Nov 13, 2023

View reviewed changes

elchead force-pushed the doc/cli/terraform-module branch 2 times, most recently from 3b72eb6 to a9b275c Compare November 13, 2023 15:57

elchead requested a review from malt3 as a code owner November 13, 2023 15:57

elchead changed the base branch from main to feat/terraform/azure-tf-module November 13, 2023 15:58

elchead force-pushed the doc/cli/terraform-module branch 3 times, most recently from 2d79819 to c7228a8 Compare November 13, 2023 16:11

elchead requested review from thomasten and msanft November 13, 2023 16:11

msanft requested changes Nov 13, 2023

View reviewed changes

msanft force-pushed the feat/terraform/azure-tf-module branch from d1debde to b85c11a Compare November 13, 2023 16:37

elchead force-pushed the doc/cli/terraform-module branch from 9aae855 to ddff944 Compare November 13, 2023 17:40

Base automatically changed from feat/terraform/azure-tf-module to main November 13, 2023 17:46

elchead force-pushed the doc/cli/terraform-module branch from c42f11d to 408fa83 Compare November 13, 2023 17:53

elchead added 2 commits November 13, 2023 19:04

add tf module doc

a8bc8ec

make image optional in the high level modules

a983942

elchead force-pushed the doc/cli/terraform-module branch from 408fa83 to a983942 Compare November 13, 2023 18:04

elchead requested a review from msanft November 13, 2023 18:05

elchead removed the hold This cannot be merged right now label Nov 13, 2023

elchead added this to the v2.13.0 milestone Nov 13, 2023

elchead added the no changelog Change won't be listed in release changelog label Nov 13, 2023

elchead added 2 commits November 13, 2023 19:08

fixup! add tf module doc

4fa3694

Revert "make image optional in the high level modules"

b2abb77

This reverts commit a983942.

msanft reviewed Nov 14, 2023

View reviewed changes

docs/docs/workflows/terraform-module.md Outdated Show resolved Hide resolved

docs/docs/workflows/terraform-module.md Outdated Show resolved Hide resolved

thomasten reviewed Nov 14, 2023

View reviewed changes

msanft reviewed Nov 14, 2023

View reviewed changes

docs/docs/workflows/terraform-module.md Outdated Show resolved Hide resolved

elchead and others added 2 commits November 14, 2023 10:32

Apply suggestions from code review

4cb8626

Co-authored-by: Thomas Tendyck <[email protected]>

correct module source

fc9316c

elchead requested review from thomasten and msanft November 14, 2023 09:58

thomasten requested changes Nov 16, 2023

View reviewed changes

add caution about files

257ade0

elchead force-pushed the doc/cli/terraform-module branch from 2e93c2e to 257ade0 Compare November 16, 2023 12:09

elchead and others added 3 commits November 16, 2023 16:20

Update docs/docs/workflows/terraform-module.md

1b0eedb

Co-authored-by: Thomas Tendyck <[email protected]>

Update docs/docs/workflows/terraform-module.md

d47a591

Co-authored-by: Thomas Tendyck <[email protected]>

Update terraform-module.md

e0e7dd8

thomasten reviewed Nov 16, 2023

View reviewed changes

thomas version hint

9566552

thomasten approved these changes Nov 16, 2023

View reviewed changes

msanft approved these changes Nov 16, 2023

View reviewed changes

elchead merged commit a88a731 into main Nov 16, 2023
5 of 6 checks passed

elchead deleted the doc/cli/terraform-module branch November 16, 2023 16:03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add Terraform module #2560

docs: add Terraform module #2560

elchead commented Nov 7, 2023 •

edited

Loading

netlify bot commented Nov 7, 2023 •

edited

Loading

m1ghtym0 commented Nov 10, 2023

elchead commented Nov 10, 2023 •

edited

Loading

m1ghtym0 left a comment

thomasten Nov 12, 2023

elchead Nov 13, 2023

thomasten Nov 12, 2023

elchead Nov 13, 2023

thomasten Nov 13, 2023

elchead Nov 13, 2023

msanft Nov 13, 2023

msanft Nov 13, 2023

elchead Nov 13, 2023

msanft left a comment

thomasten Nov 16, 2023

elchead Nov 16, 2023

thomasten Nov 16, 2023


		:::caution

		The current module still relies on the Constellation CLI. Consequently, `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.

	source = "https://github.com/edgelesssys/constellation/releases/download/<version>/terraform-module.zip//terraform-module/azure-constellation" // insert Constellation version here.
	// replace <version> with a Constellation version, e.g., v2.13.0
	source = "https://github.com/edgelesssys/constellation/releases/download/<version>/terraform-module.zip//terraform-module/azure-constellation"

docs: add Terraform module #2560

docs: add Terraform module #2560

Conversation

elchead commented Nov 7, 2023 • edited Loading

Context

Proposed change(s)

Additional info

Checklist

netlify bot commented Nov 7, 2023 • edited Loading

✅ Deploy Preview for constellation-docs ready!

m1ghtym0 commented Nov 10, 2023

elchead commented Nov 10, 2023 • edited Loading

m1ghtym0 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

msanft left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

elchead commented Nov 7, 2023 •

edited

Loading

netlify bot commented Nov 7, 2023 •

edited

Loading

elchead commented Nov 10, 2023 •

edited

Loading