In this article, we will dive into Terraform local values (sometimes referred to as locals). We will discuss what Terraform local values are, how they differ from variables, and when to use them with some examples.
What are Terraform local values?
Locals are useful to use when you want to give the result of an expression and then re-use that result throughout your configuration.
They can help simplify the configuration by enabling the values to be set once and then referenced throughout your configuration, rather than calling the same expression multiple times in the configuration.
Terraform locals should be used with caution, as using them too often or unnecessarily can cause the configuration to become harder to follow as instead of displaying the actual value or expression used, this is ‘hidden’ and needs to be tracked through the code by any future contributors. As such they should be used in moderation.
How do locals differ from variables and hard-coded values in Terraform?
Locals values are not set by the user input or values in .tfvars files, instead, they are set ‘locally’ to the configuration (hence the name). Instead of hardcoding values, local values can produce a more meaningful or readable result. The ability to change values that are likely to change in the future is the key benefit of using Terraform locals. Unlike variable values, local values can use dynamic expressions and resource arguments.
These values can be stored centrally and locally to the configuration. If the configuration is well organized, they should be easily found by a contributor. In my experience, if your module contains the use of local values, I recommend putting these in a separate file called locals.tf so they can be easily referenced. This is not a hard requirement however, they can be used anywhere in your Terraform configuration files.
Locals values do not change between Terraform runs or stages in the lifecycle, such as plan, apply or destroy.
Example — Using locals to name resources
Locals can be useful when naming resources. Consider you want to enforce a standard naming convention across your resources, with a defined prefix.
In the below example, we define name_prefix in our locals block, that adds “JacksDemo-” plus the contents of the environment variable, e.g. “JacksDemo-Prod”. This is then used to name an application gateway, in combination with the var.application_gateway_name.
Example — Using locals to set resource tags
Consider we have a mandatory set of tags that need to be set on every resource, as well as a set of tags that apply just to the resource itself. Using locals, we can set the mandatory tags, and then merge them with the resource-specific tags, to give us the final required set of tags. This affords the user the flexibility to add their own tags, whilst also mandating a required set.
In the below example, mandatory tags include the cost_center and environment which will then be merged with those tags defined in the resource_tags variable.
You can use the merge function to combine local values with variable values.
Example — Using locals with Azure Application Gateway
In this example, we will use locals to configure an Azure Application Gateway.
First, we define our locals block, containing gateway_ip_configuration, ssl_certificate and authentication_certificate.
Note these take a combination of values from variables, data sources, and modules, not something we would be able to define in a single variable or hardcode.
The relevant data source blocks are shown for completeness, they are basically pulling the certificate from an Azure Key Vault and applying it to the Application Gateway (you will also need a key vault access policy and managed identity to set this up in practice).
The local values we defined can then be passed into our appgateway module, on lines 59, 62, and 63. Note we are also using the naming prefix and mandatory_tags from the previous examples on lines 55 and 75.
Local values are a useful part of a Terraform configuration. They should be used only when necessary, and are best used when a repeated value is used throughout the configuration.
.webp)
.webp)
