AUG 23 2018 MARTIN ATKINS
As part of the lead up to the release of Terraform 0.12, we are publishing a series of feature preview blog posts. The post this week is on bringing a clear 1:1 mapping between JSON and HCL.
Terraform has accepted JSON as configuration in addition to HCL since version 0.1. However, the implementation of this prior to version 0.12 had many shortcomings. The HCL improvements in Terraform 0.12 include a clear 1:1 mapping between HCL and JSON, including much clearer error messages and support for comments!
These improvements make it easy to work with Terraform using HCL, JSON, or both.
HCL and JSON
Terraform has supported JSON as an alternate configuration format since its initial release in Terraform 0.1. Further, Terraform has supported
The JSON mapping in prior versions of Terraform had many shortcomings. In some cases, it felt as though JSON didn't feel like a first class solution in the tool. We have always considered JSON a first class input to Terraform and continue to do so, so a big part of Terraform 0.12 was having a clean 1:1 mapping between HCL and JSON, and ensuring every feature of HCL is supported in JSON.
Terraform 0.12 achieves these goals. In future versions of Terraform, we will also support native tooling to convert HCL to JSON
Error Message Improvements
In versions prior to 0.12, the configuration mapping to JSON was only weakly specified in documentation, there were many counter-intuitive mapping behaviors, and there was a tendency to silently ignore misshapen constructs that made debugging difficult.
Terraform 0.12 includes a new JSON configuration implementation that is more robust than prior versions to address these limitations. In particular, the JSON-based configuration decoder produces errors in any cases where the input cannot be mapped exactly onto the expected configuration structure.
The example below shows an invalid configuration the error produced in Terraform 0.12:
{
"variable": {
"example": "foo"
}
}
复制代码
Error: Incorrect JSON value type
on example.tf.json line 3, in variable:
3: "example": "foo"
Either a JSON object or JSON array is required, representing the contents of
one or more "variable" blocks.
复制代码
Terraform now knows that the top-level name "variable"
represents a set of variable
blocks in the native syntax, and so it can see that the value of the property "example"
should be an object representing the contents of a variable "example"
block in HCL. The above example can therefore be corrected by replacing the string value with an object:
{
"variable": {
"example": {
"default": "foo"
}
}
}
复制代码
To properly produce error messages like these, the new JSON decoder is necessarily more strict than in prior versions. As a result, JSON-based configuration generated for prior versions may need to be adjusted slightly to fit within the new constraints.
Comments in JSON
A big limitation of JSON is the lack of comment support. Terraform 0.12 includes a simplistic form of "comments" in the form of a special key "//"
within JSON objects.
The example below shows a comment in a Terraform 0.12 JSON configuration:
{
"variable": {
"example": {
"//": "This property is ignored",
"default": "foo"
}
}
}
复制代码
In nested block objects, any property named "//"
is ignored. While we recommend using the native syntax for hand-written configuration, a JSON comment feature may be useful to include commentary in generated configuration, such as identifying which program generated the file.
Upgrade Guide
The new JSON parser in Terraform 0.12 is necessarilly more strict than prior versions. Therefore, existing JSON configurations may require changes to work with Terraform 0.12. If you use JSON with Terraform, please run a terraform validate
or terraform plan
and correct any error messages.
Next
This was part 8 of the blog post series previewing Terraform 0.12.
The clear 1:1 mapping with JSON will be released in Terraform 0.12, coming later this summer. To learn more about how to upgrade to Terraform 0.12, read the upgrade instructions which will be continuously updated as we get closer to releasing Terraform 0.12. If you have any feedback or concerns about these changes, please communicate with the Terraform team via the public mailing list.