packer/website/content/docs/templates/hcl_templates/contextual-variables.mdx

---
page_title: Contextual Variables - HCL Configuration Language
description: >-
  Special variables provide connection information and basic instance state
  information.

  This page covers all existing special variables.
---

`@include 'from-1.5/beta-hcl2-note.mdx'`

`@include 'from-1.5/contextual-source-variables.mdx'`

# Build Variables

Build variables will allow you to access connection information and basic instance state information for a builder.
All special build variables are stored in the `build` variable:

```hcl
source "null" "first-example" {
  communicator = "none"
}

build {
  name = "my-build-name"
  sources = ["null.first-example"]

  provisioner "shell-local" {
    environment_vars = ["TESTVAR=${build.PackerRunUUID}"]
    inline = ["echo source.name is ${source.name}.",
              "echo build.name is ${build.name}.",
              "echo build.PackerRunUUID is $TESTVAR"]
  }
}
```

Here is the list of available build variables:

- **name** Represents the name of the build block being run. This is different
  than the name of the source block being run.

- **ID**: Represents the VM being provisioned. For example, in Amazon it is the instance ID; in DigitalOcean,
  it is the Droplet ID; in VMware, it is the VM name.

- **Host**, **Port**, **User** and **Password**: The host, port, user, and password that Packer uses to access the machine.
  Useful for using the shell local provisioner to run Ansible or Inspec against the provisioned instance.

- **ConnType**: Type of communicator being used. For example, for SSH communicator this will be "ssh".

- **PackerRunUUID**: Current build's unique ID. Can be used to specify build artifacts.
  An example of that, is when multiple builds runs at the same time producing the same artifact.
  It's possible to differentiate these artifacts by naming them with the builds' unique IDs.

- **PackerHTTPIP**, **PackerHTTPPort**, and **PackerHTTPAddr**: HTTP IP, port, and address of the file server Packer creates to serve items in the "http" dir to the VM. The HTTP address is displayed in the format `IP:PORT`.

- **SSHPublicKey** and **SSHPrivateKey**: The public and private key that Packer uses to connect to the instance.
  These are unique to the SSH communicator and are unset when using other communicators.
  **SSHPublicKey** and **SSHPrivateKey** can have escape sequences and special characters so their output should be single quoted to avoid surprises. For example:

  ```hcl
    provisioner "shell" {
        inline = ["echo '${build.SSHPrivateKey}' > /tmp/packer-session.pem"]
    }
  ```

For backwards compatibility, `WinRMPassword` is also available through this
engine, though it is no different than using the more general `Password`.

All build variables are valid to use with any of the [HCL2 functions](/packer/docs/templates/hcl_templates/functions).
Example of using [upper](/packer/docs/templates/hcl_templates/functions/string/upper) to upper case the build ID:

```hcl
  post-processor "shell-local" {
      inline = ["echo ${upper(build.ID)}"]
  }
```

For builder-specific builder variables, please also refer to the builder docs:

- Amazon EC2: [chroot](/packer/plugins/builders/amazon/chroot#build-shared-information-variables),
  [EBS Volume](/packer/plugins/builders/amazon/ebsvolume#build-shared-information-variables),
  [EBS](/packer/plugins/builders/amazon/ebs#build-shared-information-variables),
  [EBS Surrogate](/packer/plugins/builders/amazon/ebssurrogate#build-shared-information-variables),
  [Instance](/packer/plugins/builders/amazon/instance#build-shared-information-variables).

The HCL2 Special Build Variables is in beta; please report any issues or requests on the Packer
issue tracker on GitHub.

# Packer Version

This variable is set to the Packer version currently running.

```hcl
source "null" "first-example" {
  communicator = "none"
}

build {
  sources = ["null.first-example"]

  provisioner "shell-local" {
    inline = ["echo packer_version is '${packer.version}'"]
  }
}
```

If you are running a development version of Packer, the version variable will
contain the released version number, dev flag, and current commit.

```shell-session
PACKER_LOG=0 packer build packer_version_demo.pkr.hcl
null.first-example: output will be in this color.

==> null.first-example: Running local shell script: /var/folders/8t/0yb5q0_x6mb2jldqq_vjn3lr0000gn/T/packer-shell083160352
    null.first-example: packer_version is 1.6.5-dev (a69392129+CHANGES)
```

If you are running a released version of Packer, the version variable will
contain the released version number only:

```shell-session
PACKER_LOG=0 packer build packer_version_demo.pkr.hcl
null.first-example: output will be in this color.

==> null.first-example: Running local shell script: /var/folders/8t/0yb5q0_x6mb2jldqq_vjn3lr0000gn/T/packer-shell718995312
    null.first-example: packer_version is 1.6.5
```

Make sure to wrap your variable in single quotes in order to escape the
string that is returned; if you are running a dev version of packer the
parenthesis may through off your shell escaping otherwise.

# HCP Packer Iteration ID

~> **Note**: Deprecation: Contextual Variable `iterationID` has been deprecated packer context. Please use `versionFingerprint` variable instead.

If your build is pushing metadata to the HCP Packer registry, this variable is
set to the value of the Iteration ID associated with this run.

```hcl
source "amazon-ebs" "cannonical-ubuntu-server" {
  ami_name         = "packer-example"
  // ...
  run_volume_tags = {
    hcp_iteration_id = packer.iterationID
  }
}
```

# HCP Packer Version Fingerprint

If your build is pushing metadata to the HCP Packer registry, this variable is
set to the value of the Version Fingerprint associated with this run.

```hcl
source "amazon-ebs" "cannonical-ubuntu-server" {
  ami_name         = "packer-example"
  // ...
  run_volume_tags = {
    hcp_version_fingerprint = packer.versionFingerprint
  }
}
```


```shell-session
==> vanilla.amazon-ebs.cannonical-ubuntu-server: Adding tags to source instance
    vanilla.amazon-ebs.cannonical-ubuntu-server: Adding tag: "Name": "Packer Builder"
    vanilla.amazon-ebs.cannonical-ubuntu-server: Adding tag: "hcp_iteration_id": "01FHGF3M2AK4TS6PCZES4VX5E7"
```

You can also add this value to post-processors, for example to add to a manifest file:

```hcl
  post-processor "manifest" {
    output     = "manifest.json"
    strip_path = true
    custom_data = {
      version_fingerprint = "${packer.versionFingerprint}"
      // `packer.iterationID` has been deprecated.
      iteration = "${packer.iterationID}"
    }
  }

```