github.com/hashicorp/packer@v1.14.3/website/content/docs/templates/hcl_templates/locals.mdx (about)

     1  ---
     2  page_title: Local variables
     3  description: >-
     4    The `local` and `locals` blocks define local variables that assign a name to an expression. Learn how to configure local variables.
     5  ---
     6  
     7  # Local variables
     8  
     9  This topic provides reference information about the `local` and `locals` blocks, which define local variables that you can use in your Packer templates. To learn about input variables, refer to
    10  [Input variables](/packer/docs/templates/hcl_templates/variables).
    11  
    12  ## Introduction
    13  
    14  Local variables assign a name to an expression, which you can use multiple
    15  times within a folder. The expression is evaluated at run time, and can
    16  reference input variables, other local variables, data sources, and HCL
    17  functions. You cannot overwrite local variables.
    18  
    19  Refer to [Input Variables and local variables](/packer/guides/hcl/variables) for additional information about variables in Packer. 
    20  
    21  ## Examples
    22  
    23  Local variables are defined in a `local` or `locals` block:
    24  
    25  ```hcl
    26  # Using the local block allows you to mark locals as sensitive, which will
    27  # filter their values from logs.
    28  local "mylocal" {
    29    expression = "${var.secret_api_key}"
    30    sensitive  = true
    31  }
    32  
    33  # Using the locals block is more compact and efficient for declaring many locals
    34  # Ids for multiple sets of EC2 instances, merged together
    35  locals {
    36    instance_ids = "${concat(aws_instance.blue.*.id, aws_instance.green.*.id)}"
    37  }
    38  
    39  # A computed default name prefix
    40  locals {
    41    default_name_prefix = "${var.project_name}-web"
    42    name_prefix         = "${var.name_prefix != "" ? var.name_prefix : local.default_name_prefix}"
    43  }
    44  
    45  # Local variables can be referenced using the "local." prefix.
    46  source "virtualbox-iso" "example" {
    47    output = "${local.name_prefix}-files"
    48    # ...
    49  }
    50  ```
    51  
    52  Named local maps can be merged with local maps to implement common or default
    53  values:
    54  
    55  ```hcl
    56  # Define the common tags for all resources
    57  locals {
    58    common_tags = {
    59      Component   = "awesome-app"
    60      Environment = "production"
    61    }
    62  }
    63  
    64  # Create a resource that blends the common tags with instance-specific tags.
    65  source "amazon-ebs" "server" {
    66    source_ami    = "ami-123456"
    67    instance_type = "t2.micro"
    68  
    69    tags = "${merge(
    70      local.common_tags,
    71      {
    72        "Name" = "awesome-app-server",
    73        "Role" = "server"
    74      }
    75    )}"
    76    # ...
    77  }
    78  ```
    79  
    80  ## Single `local` block
    81  
    82  The `local` block defines exactly one local variable within a folder. The block
    83  label is the name of the local, and the "expression" is the expression that
    84  should be evaluated to create the local. Using this block, you can optionally
    85  supply a "sensitive" boolean to mark the variable as sensitive and filter it
    86  from logs.
    87  
    88  ```hcl
    89  local "mylocal" {
    90    expression = "${var.secret_api_key}"
    91    sensitive  = true
    92  }
    93  ```
    94  
    95  This block is also very useful for defining complex locals. Packer might take some time to expand and evaluate `locals`
    96  with complex expressions dependent on other locals. The `locals` block is read as a map.  Maps are not sorted, and therefore
    97  the evaluation time is not deterministic.
    98  
    99  To avoid that, singular `local` blocks should be used instead. These will be
   100  evaluated in the order they are defined, and the evaluation order and time will always be the same.
   101  
   102  ## `locals` block
   103  
   104  The `locals` block defines one or more local variables within a folder.
   105  
   106  The names given for the items in the `locals` block must be unique throughout a
   107  folder. The given value can be any expression that is valid within the current
   108  folder.
   109  
   110  The expression of a local value can refer to other locals, but reference cycles
   111  are not allowed. That is, a local cannot refer to itself or to a variable that
   112  refers (directly or indirectly) back to it.
   113  
   114  It's recommended to group together logically-related local variables into a single
   115  block, particularly if they depend on each other. This will help the reader
   116  understand the relationships between variables. Conversely, prefer to define
   117  _unrelated_ local variables in _separate_ blocks, and consider annotating each
   118  block with a comment describing any context common to all of the enclosed
   119  locals.
   120  
   121  ## Known limitations
   122  `@include 'datasources/local-dependency-limitation.mdx'`
   123  
   124