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.
Stacks
A Terraform template is an abstraction over a Terraform stack (also called a root module). 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:
__gpfiles 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)._gpfiles 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 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.
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 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 withcount = 0.
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 if you need something that the templates do not support.