> **Page index:** https://km.oslo.systems/llms.txt lists every page on this site, with a link to its Markdown version.

# How Terraform templates work

Terraform templates generate the Terraform code in your stacks. This page explains the parts that are specific to Terraform templates. For information about templates in general, see [Infrastructure as Code](<https://km.oslo.systems/infrastructure-as-code/index.md>).

## Stacks

A Terraform template is an abstraction over a Terraform *stack* (also called a [root module](<https://developer.hashicorp.com/terraform/language/modules>)). A stack is a directory with its own Terraform state.

### Data stacks

Some templates create a second stack, the data stack, in a directory next to the main stack, with a name that ends in `-data`. The data stack holds the resources that keep data, such as log groups and S3 buckets. For the `app` template:

|  | Main stack | Data stack |
| --- | --- | --- |
| Template | `app` | `app-data` |
| Directory | `app-hello-world` | `app-hello-world-data` |
| `packages.yml` | Yes | No. `ok pkg install` in the main stack also renders the data stack |
| Boilerplate variables | `package-config.yml` | `package-config.yml` of the main stack, with the template name in front: `app-data.StackName` |
| Terraform state | Its own | Its own |

The main stack depends on the data stack, so during first-time installation, apply the data stack first.

## Layout

The Terraform files that the template generates have names that start with `__gp` or `_gp`:

- `__gp` files hold what the stack takes in: local values (`__gp_config.tf`), variables (`__gp_variables.tf`) and lookups of resources that other stacks create, such as the network and the DNS zones (`__gp_dependencies.tf`).
- `_gp` files hold the resources and modules that the stack creates, typically one file for each resource type, for example `_gp_ecs_service.tf`.

Do not edit these files, because Boilerplate overwrites them each time you run `ok pkg install`. Boilerplate does not change files with the suffix `_override.tf`, so files such as `config_override.tf` or `_gp_ecs_service_override.tf` are left untouched. You can use these prefixes for override files, but not for other files of your own.

## Configuration

A Terraform template has two configuration layers. Together, they are the public interface of the template.

| Layer | Location | Controls | After a change |
| --- | --- | --- | --- |
| Boilerplate variables | `package-config.yml` | The key features and behavior of the stack | Run `ok pkg install`, then apply |
| Terraform local values | `config_override.tf` | The settings in these features | Apply |

The [template reference pages](<https://km.oslo.systems/templates/index.md>) list all Boilerplate variables of each template.

`__gp_config.tf` in your stack holds the configurable Terraform local values and their defaults. To change a value, set the same local in `config_override.tf`.

repo-iac/environments/dev/app-hello-world/config\_override.tf

```
locals {
  main_container_port = 3000
}
```

## Customization

If the public interface is not enough, you can add your own files next to the generated files.

- **Your own Terraform files** add infrastructure that the template does not create, for example `ssm_parameters.tf`.
- **Override files** change parts of the stack that the public interface does not expose. Use them only as an escape hatch. A [Terraform override file](<https://developer.hashicorp.com/terraform/language/files/override>) has the suffix `_override.tf`, and its name is typically the name of the template file that it overrides, for example `_gp_ecs_service_override.tf`. Terraform merges each block in an override file into the block with the same name in the template. An override file can also remove a resource with `count = 0`.

> [!WARNING]
>
> **Internal details can change**
>
> An override file, or your own Terraform file that refers to a resource or module from the template, depends on internal details of the template. These details are not part of the public interface. A new template version can change them without notice. Then your customization can stop working, or it can change your infrastructure in a way that you did not expect.

Team Utviklerflyt periodically looks at how teams configure and customize their Terraform stacks. If many teams need the same change, Team Utviklerflyt considers adding it to the public interface, so that the change is easier and safer to make. [Contact Team Utviklerflyt](<https://km.oslo.systems/help/contact-us/index.md>) if you need something that the templates do not support.
