Skip to content

Latest commit

 

History

History
139 lines (107 loc) · 3.98 KB

hcl2_upgrade.mdx

File metadata and controls

139 lines (107 loc) · 3.98 KB
Raw
description page_title
The `packer hcl2_upgrade` Packer command is used to transpile a JSON configuration template to its formatted HCL2 counterpart. The command will return a zero exit status on success, and a non-zero exit status on failure.
packer hcl2_upgrade - Commands

-> Note: This command is Beta, and currently being improved upon; do not hesitate opening a new issue if you find something wrong.

hcl2_upgrade Command

The packer hcl2_upgrade Packer command is used to transpile a JSON configuration template to it's formatted HCL2 counterpart. The command will return a zero exit status on success, and a non-zero exit status on failure.

Example usage:

$ packer hcl2_upgrade my-template.json

Successfully created my-template.json.pkr.hcl

Upgrading variables file

From v1.7.1, the hcl2_upgrade command can upgrade a variables file.

{
  "variables": {
    "aws_region": null,
    "aws_secondary_region": "{{ env `AWS_DEFAULT_REGION` }}",
    "aws_secret_key": "",
    "aws_access_key": ""
  },
  "sensitive-variables": ["aws_secret_key", "aws_access_key"]
}
variable "aws_access_key" {
  type      = string
  default   = ""
  sensitive = true
}

variable "aws_region" {
  type = string
}

variable "aws_secondary_region" {
  type    = string
  default = "${env("AWS_DEFAULT_REGION")}"
}

variable "aws_secret_key" {
  type      = string
  default   = ""
  sensitive = true
}

Go template functions

hcl2_upgrade will do its best to transform your Go template calls to HCL2, here is the list of calls that should get transformed:

  • {{ user `my_var` }} becomes ${var.my_var}.
  • {{ env `my_var` }} becomes ${var.my_var}. Packer HCL2 supports environment variables through input variables. See docs for more info.
  • {{ timestamp }} becomes ${local.timestamp}, the local variable will be created for all generated files.
  • {{ build `ID` }} becomes ${build.ID}.

The rest of the calls should remain Go template calls for now, this will be improved over time.

-> Note: The hcl2_upgrade command does its best to transform template calls to their JSON counterpart, but it might fail. In that case the hcl2_upgrade command will simply output the local HCL2 block without transformation and with the error message in a comment. We are currently working on improving this part of the transformer.

Options

  • -output-file - Filename of the hcl2 generated template. Defaults to JSON_TEMPLATE.pkr.hcl; for example, if the file is called "packerparty.json", the default output-file is "packerparty.json.pkr.hcl".
  • -with-annotations - Adds helpful comments to the HCL template with information about the generated HCL2 blocks.

User variables using other user variables

Packer JSON recently started allowing using user variables from variables. In HCL2, input variables cannot use functions nor other variables and are virtually static, local variables must be used instead to craft more dynamic variables.

For v1.7.0 and lower, hcl2_upgrade doesn't upgrade variables to local variables, and it is up to you to upgrade them manually. Upgrade to v1.7.1 to let the command do it automatically for you.

Here is an example of a local variable using a string input variables:

variable "foo" {
  default = "Hello,"
}

variable "bar" {
  default = "World!"
}

locals {
  baz = "${var.foo} ${var.bar}"
}

Upgrading templates that use third-party community plugins

If your template references a plugin that is not bundled with the main Packer binary, you need to make sure that the plugin is installed or you will get an unknown builder type error. Packer needs to load the plugin to transpose the template.