»Local Values

There are two kinds of variables in HCL Packer templates: Input variables, sometimes simply called "variables", and Local variables, also known as "locals". Input variables may have defaults, but those defaults can be overridden from the command line or special variable files. Local variables can be thought of as constants, and are not able to be overridden at runtime.

This page is about local variables. To learn about input variables, see the input variables page.

Local values assign a name to an expression, that can then be used multiple times within a folder.

If variables are analogous to function arguments then local values are comparable to a function's local variables.

Input variable and local variable usage are introduced in the Variables Guide.

»Examples

Local values are defined in local or locals blocks:

# Using the local block allows you to mark locals as sensitive, which will
# filter their values from logs.
local "mylocal" {
  expression = "${var.secret_api_key}"
  sensitive  = true
}

# Using the locals block is more compact and efficient for declaring many locals
# Ids for multiple sets of EC2 instances, merged together
locals {
  instance_ids = "${concat(aws_instance.blue.*.id, aws_instance.green.*.id)}"
}

# A computed default name prefix
locals {
  default_name_prefix = "${var.project_name}-web"
  name_prefix         = "${var.name_prefix != "" ? var.name_prefix : local.default_name_prefix}"
}

# Local values can be interpolated elsewhere using the "local." prefix.
source "virtualbox-iso" "example" {
  output = "${local.name_prefix}-files"
  # ...
}

# Using the local block allows you to mark locals as sensitive, which will
# filter their values from logs.
local "mylocal" {
  expression = "${var.secret_api_key}"
  sensitive  = true
}

# Using the locals block is more compact and efficient for declaring many locals
# Ids for multiple sets of EC2 instances, merged together
locals {
  instance_ids = "${concat(aws_instance.blue.*.id, aws_instance.green.*.id)}"
}

# A computed default name prefix
locals {
  default_name_prefix = "${var.project_name}-web"
  name_prefix         = "${var.name_prefix != "" ? var.name_prefix : local.default_name_prefix}"
}

# Local values can be interpolated elsewhere using the "local." prefix.
source "virtualbox-iso" "example" {
  output = "${local.name_prefix}-files"
  # ...
}

Named local maps can be merged with local maps to implement common or default values:

# Define the common tags for all resources
locals {
  common_tags = {
    Component   = "awesome-app"
    Environment = "production"
  }
}

# Create a resource that blends the common tags with instance-specific tags.
source "amazon-ebs" "server" {
  source_ami    = "ami-123456"
  instance_type = "t2.micro"

  tags = "${merge(
    local.common_tags,
    {
      "Name" = "awesome-app-server",
      "Role" = "server"
    }
  )}"
  # ...
}

# Define the common tags for all resources
locals {
  common_tags = {
    Component   = "awesome-app"
    Environment = "production"
  }
}

# Create a resource that blends the common tags with instance-specific tags.
source "amazon-ebs" "server" {
  source_ami    = "ami-123456"
  instance_type = "t2.micro"

  tags = "${merge(
    local.common_tags,
    {
      "Name" = "awesome-app-server",
      "Role" = "server"
    }
  )}"
  # ...
}

»Single local block

The local block defines exactly one local variable within a folder. The block label is the name of the local, and the "expression" is the expression that should be evaluated to create the local. Using this block, you can optionally supply a "sensitive" boolean to mark the variable as sensitive and filter it from logs.

local "mylocal" {
  expression = "${var.secret_api_key}"
  sensitive  = true
}

local "mylocal" {
  expression = "${var.secret_api_key}"
  sensitive  = true
}

This block is also very useful for defining complex locals. Packer might take some time to expand and evaluate locals with complex expressions dependent on other locals. The locals block is read as a map. Maps are not sorted, and therefore the evaluation time is not deterministic.

To avoid that, singular local blocks should be used instead. These will be evaluated in the order they are defined, and the evaluation order and time will always be the same.

»locals block

The locals block defines one or more local variables within a folder.

The names given for the items in the locals block must be unique throughout a folder. The given value can be any expression that is valid within the current folder.

The expression of a local value can refer to other locals, but reference cycles are not allowed. That is, a local cannot refer to itself or to a variable that refers (directly or indirectly) back to it.

It's recommended to group together logically-related local values into a single block, particularly if they depend on each other. This will help the reader understand the relationships between variables. Conversely, prefer to define unrelated local values in separate blocks, and consider annotating each block with a comment describing any context common to all of the enclosed locals.