github.com/hashicorp/packer@v1.14.3/website/content/docs/commands/hcl2_upgrade.mdx (about)

     1  ---
     2  description: |
     3    The `packer hcl2_upgrade` Packer command transpiles a JSON
     4    configuration template into HCL2 so you can transition to HCL templates.
     5  page_title: packer hcl2_upgrade command reference
     6  ---
     7  
     8  # `packer hcl2_upgrade` command reference
     9  
    10  The `packer hcl2_upgrade` Packer command transpiles a JSON
    11  configuration template to it's formatted HCL2 counterpart. The command
    12  returns a zero exit status on success and a non-zero exit status on failure.
    13  
    14  -> **This command is beta**. We do not recommend using beta functionality in production environments. To report an issue and provide feedback, [open a GitHub
    15  issue](https://github.com/hashicorp/packer/issues/new/choose).
    16  
    17  ## Usage
    18  
    19  ```shell-session
    20  $ packer hcl2_upgrade my-template.json
    21  
    22  Successfully created my-template.json.pkr.hcl
    23  ```
    24  
    25  ## Upgrading variables file
    26  
    27  From **v1.7.1**, the `hcl2_upgrade` command can upgrade a variables file.
    28  
    29  <Tabs>
    30  <Tab heading="Original file (variables.json)">
    31  
    32  ```json
    33  {
    34    "variables": {
    35      "aws_region": null,
    36      "aws_secondary_region": "{{ env `AWS_DEFAULT_REGION` }}",
    37      "aws_secret_key": "",
    38      "aws_access_key": ""
    39    },
    40    "sensitive-variables": ["aws_secret_key", "aws_access_key"]
    41  }
    42  ```
    43  
    44  </Tab>
    45  <Tab heading="Result file (variables.pkr.hcl)">
    46  
    47  ```hcl
    48  variable "aws_access_key" {
    49    type      = string
    50    default   = ""
    51    sensitive = true
    52  }
    53  
    54  variable "aws_region" {
    55    type = string
    56  }
    57  
    58  variable "aws_secondary_region" {
    59    type    = string
    60    default = "${env("AWS_DEFAULT_REGION")}"
    61  }
    62  
    63  variable "aws_secret_key" {
    64    type      = string
    65    default   = ""
    66    sensitive = true
    67  }
    68  ```
    69  
    70  </Tab>
    71  </Tabs>
    72  
    73  ## Go template functions
    74  
    75  `hcl2_upgrade` will do its best to transform your Go _template calls_ to HCL2,
    76  here is the list of calls that should get transformed:
    77  
    78  - `` {{ user `my_var` }} `` becomes `${var.my_var}`.
    79  - `` {{ env `my_var` }} `` becomes `${var.my_var}`. Packer HCL2 supports
    80    environment variables through input variables. See
    81    [docs](/packer/docs/templates/hcl_templates/variables#environment-variables)
    82    for more info.
    83  - `{{ timestamp }}` becomes `${local.timestamp}`, the local variable
    84    will be created for all generated files.
    85  - `` {{ build `ID` }} `` becomes `${build.ID}`.
    86  
    87  The rest of the calls should remain Go template calls for now, this will be
    88  improved over time.
    89  
    90  -> **Note**: The `hcl2_upgrade` command does its best to transform template
    91  calls to their JSON counterpart, but it might fail. In that case the
    92  `hcl2_upgrade` command will simply output the local HCL2 block without
    93  transformation and with the error message in a comment. We are currently
    94  working on improving this part of the transformer.
    95  
    96  ## Options
    97  
    98  - `-output-file` - Filename of the hcl2 generated template. Defaults to
    99    JSON_TEMPLATE.pkr.hcl; for example, if the file is called
   100    "packerparty.json", the default output-file is "packerparty.json.pkr.hcl".
   101  - `-with-annotations` - Adds helpful comments to the HCL template with
   102    information about the generated HCL2 blocks.
   103  
   104  ## User variables using other user variables
   105  
   106  Packer JSON recently started allowing using user variables from variables. In
   107  HCL2, input variables cannot use functions nor other variables and are
   108  virtually static, local variables must be used instead to craft more dynamic
   109  variables.
   110  
   111  For v1.7.0 and lower, `hcl2_upgrade` doesn't upgrade variables to local variables,
   112  and it is up to you to upgrade them manually. Upgrade to **v1.7.1** to let the command do it
   113  automatically for you.
   114  
   115  Here is an example of a local variable using a string input variables:
   116  
   117  ```hcl
   118  variable "foo" {
   119    default = "Hello,"
   120  }
   121  
   122  variable "bar" {
   123    default = "World!"
   124  }
   125  
   126  locals {
   127    baz = "${var.foo} ${var.bar}"
   128  }
   129  ```
   130  
   131  ## Upgrading templates that use third-party community plugins
   132  
   133  If your template references a plugin that is not bundled with the main Packer
   134  binary, you need to make sure that the [plugin is installed](/packer/docs/plugins#installing-plugins)
   135  or you will get an `unknown builder type` error. Packer needs to load the plugin
   136  to transpose the template.