diff --git a/content/en/docs/components/orchestration/infrastructure/deploy-pipeline-success.png b/content/en/docs/components/orchestration/infrastructure/deploy-pipeline-success.png new file mode 100644 index 0000000..82d1e64 Binary files /dev/null and b/content/en/docs/components/orchestration/infrastructure/deploy-pipeline-success.png differ diff --git a/content/en/docs/components/orchestration/infrastructure/deploy-pipeline.png b/content/en/docs/components/orchestration/infrastructure/deploy-pipeline.png new file mode 100644 index 0000000..07e6956 Binary files /dev/null and b/content/en/docs/components/orchestration/infrastructure/deploy-pipeline.png differ diff --git a/content/en/docs/components/orchestration/infrastructure/terraform.md b/content/en/docs/components/orchestration/infrastructure/terraform.md index bfb835e..ac08fb7 100644 --- a/content/en/docs/components/orchestration/infrastructure/terraform.md +++ b/content/en/docs/components/orchestration/infrastructure/terraform.md @@ -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//`, 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 is specified +After the deploymenet completes, and a short startup time, you should be able to access your Forgejo instance at `.buildth.ing` (production tenant) or `.t09.de` (non-prod tenant). `` 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 `.buildth.ing` (production tenant) or `.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/` 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 [/\/\/](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/)