Skip to content

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:

  • __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 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 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.

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.