Patrick.Sy/website-and-documentation
1
0
Fork 0
forked from DevFW-CICD/website-and-documentation
Code Pull requests Activity

docs(terraform): update terraform docs per feedback

Browse source
This commit is contained in:
Martin McCaffery 2025-12-02 11:30:57 +01:00
parent fb941c6766
commit 3fceb4a5de
Signed by untrusted user: martin.mccaffery
GPG key ID: 7C4D0F375BCEE533
3 changed files with 24 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

BIN
content/en/docs/components/orchestration/infrastructure/deploy-pipeline-success.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 333 KiB

BIN
content/en/docs/components/orchestration/infrastructure/deploy-pipeline.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 188 KiB

46
content/en/docs/components/orchestration/infrastructure/terraform.md
View file

@ -15,7 +15,7 @@ description: >
* **Last Updated**: 2025-11-26
* **TODO**:
* [x] Add detailed component description
* [ ] Include usage examples and code samples
* [x] Include usage examples and code samples
* [ ] Add architecture diagrams
* [ ] Review and finalize content
* **Review**:
@ -67,33 +67,42 @@ Alternatively, manually trigger automated [deployment pipeline](https://edp.buil
- You will be asked for essential information like the deployment name and tenant.
- Any fields marked `INITIAL` only need to be set when first creating an environment
- Thereafter, the cached values are used and the `INITIAL` values provided to the pipeline are ignored.
- Specifically, they are cached in a `terragrunt.values.hcl` file within `infra-deploy/<tenant>/<cluster-name>`, where both variables are set in the pipeline
- e.g. [prod/edp](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/prod/edp/terragrunt.values.hcl) or [nonprod/garm-provider-test](https://edp.buildth.ing/DevFW/infra-deploy/src/commit/189632811944d3d3bc41e26c09262de8f215f82b/non-prod/garm-provider-test/terragrunt.values.hcl)
### Verification
> Stephan: 1. Typo: prod and non prod are the same domain name
> Stephan: 2. Pls provide a link into the config where <cluster-name> is specified
After the deploymenet completes, and a short startup time, you should be able to access your Forgejo instance at `<cluster-name>.buildth.ing` (production tenant) or `<cluster-name>.t09.de` (non-prod tenant). `<cluster-name>` is the name you provided in the deployment pipeline, or the $CLUSTER_ENVIRONMENT variable when running manually.
After the deploymenet completes, and a short startup time, you should be able to access your Forgejo instance at `<cluster-name>.buildth.ing` (production tenant) or `<cluster-name>.buildth.ing` (non-prod tenant). For example, the primary production cluster is called [edp](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/prod/edp) and can be accessed at [edp.buildth.ing](https://edp.buildth.ing).
For example, the primary production cluster is called [edp](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/prod/edp) and can be accessed at [edp.buildth.ing](https://edp.buildth.ing).
#### Screens
> Stephan: Perhaps some significant screenshots here from the CLI, OTC (during deployment), pipeline logs ... otherweise we will forget what it looked like on our machines in 2025 ;-)
Deployment using production pipeline:
![Running the deployment pipeline](../deploy-pipeline.png)
...
![Successful deploy pipeline logs](../deploy-pipeline-success.png)
## Configuration
> Stephan: perhaps another link to the READMEs how config is done?
Configuration of clusters is done in two ways. The first, mentioned above, is to provide `INITIAL` configuration when creating a new cluster. Thereafter, configuration is done within the relevant `infra-deploy/<tenant>` directory (e.g. [prod/edp](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/prod/edp)). Variables may be changed within the [terragrunt.values.hcl](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/prod/edp/terragrunt.values.hcl) file, but equally the [terragrunt.stack.hcl](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/prod/edp/terragrunt.stack.hcl) file contains references to the lower-level code set up in `infra-catalogue`.
[Key configuration options and how to set them]
These are organised in layers, according to Terragrunt's natural structure. First is a [stack](https://edp.buildth.ing/DevFW/infra-catalogue/src/branch/main/stacks), a high-level abstraction for a whole cluster. This in turn [references](https://edp.buildth.ing/DevFW/infra-catalogue/src/branch/main/stacks/forgejo/terragrunt.stack.hcl) terragrunt [units](https://edp.buildth.ing/DevFW/infra-catalogue/src/branch/main/units), which in turn are wrappers around standard _Terraform_ [modules](https://edp.buildth.ing/DevFW/infra-catalogue/src/branch/main/modules).
When deployed, the Terraform modules require a `provider.tf` file which is automatically generated by Terragrunt using [tenant-level](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/prod/tenant.hcl) and [global](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/root.hcl) configuration stored in `infra-deploy`.
When deploying manually (e.g. with [install.sh](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/install.sh)), you can observe these layers as Terragrunt will cache them on your machine, within the `.terragrunt-stack/` directory generated within [/\<tenant\>/\<cluster-name\>/](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/prod/edp).
## Troubleshooting
### [Common Issue 1]
### Version updates
> Stephan: are there problems left with versioning?
**Problem**: Updates to `infra-catalogue` are not immediately reflected in deployed clusters, even after running [deploy](https://edp.buildth.ing/DevFW/infra-deploy/actions?workflow=deploy.yaml).
**Problem**: [Description]
**Solution**: Versions must be updated.
Each cluster deployment specifies a [catalogue version](https://edp.buildth.ing/DevFW/infra-deploy/src/commit/189632811944d3d3bc41e26c09262de8f215f82b/prod/edp/terragrunt.values.hcl#L7) in its `terragrunt.values.hcl`; this refers to a tag in [infra-catalogue](https://edp.buildth.ing/DevFW/infra-catalogue/releases/tag/v2.0.6). Within `infra-catalogue`, stacks reference units and modules from the same tag.
**Solution**: [How to fix]
Thus, to test a new change to `infra-catalogue`, first make a new [tag](https://edp.buildth.ing/DevFW/infra-catalogue/tags), then update the relevant [values file](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/prod/edp/terragrunt.values.hcl) to point to it.
## Status
@ -102,13 +111,6 @@ After the deploymenet completes, and a short startup time, you should be able to
## Additional Resources
> Stephan: perhaps terraform/terragrunt links?
* [Link to external documentation]
* [Link to community resources]
* [Link to related components]
## Documentation Notes
Unsure if remaining sections are useful.
> Stephan: I removed sections which I also don't see useful, and added hints/ideas for content to the rest
- [Terraform](https://developer.hashicorp.com/terraform)
- [OpenTofu](https://opentofu.org/), the community-driven replacement for Terraform
- [Terragrunt](https://terragrunt.gruntwork.io/)