Skip to main content

HashiCorp Terraform 0.12 Preview

This is the introductory post of the series highlighting new features in Terraform 0.12.

Terraform 0.12 focuses on major Terraform language improvements and will be released in Q1 2019. We are communicating about Terraform 0.12 prior to release to highlight the upcoming improvements and so the community can provide early feedback.

The improvements in HCL include for loops, conditional expression improvements, nullable arguments, an exact 1:1 mapping with JSON, and much more. Unfortunately, introducing these changes resulted in multiple breaking changes. We've analyzed a large corpus of publicly available Terraform configurations and believe these breaking changes will only impact a small percentage of users. We're publishing the upgrade guide and these blog posts early as a way to communicate with the community on these upcoming changes.

»Improving HCL

HCL, the underlying configuration language for Terraform (as well as most of our tools), has gone mostly unchanged in the 4 years since it was originally released. After years of production usage in a wide range of organizational settings, Terraform users have found many areas of the language that could use improvement. Attempting to make up for limitations in HCL over the years has yielded a number of clever but unintuitive workarounds.

About a year ago, we began an effort of developing a major iteration to HCL to address this feedback holistically by building a more robust, feature-rich language to simplify the process of writing, analyzing, and processing Terraform configurations. Earlier this year, we began integrating this new iteration of HCL into what will become Terraform 0.12.

We're introducing over a dozen new improvements in Terraform 0.12 that focus on improving the core language. In addition to the immediate benefits that make it into the Terraform 0.12 changelog, the new HCL engine gives us much more flexibility to introduce new features in the future.

»Notable Improvements

The list below shows the notable improvements in HCL and Terraform that will be present in Terraform 0.12. This list contains a basic description of each and follow-on blog posts will cover each in detail.

  • First-class expressions. Prior to 0.12, expressions had to be wrapped in interpolation sequences with double quotes, such as "${}". With 0.12, expressions are a native part of the language and can be used directly. Example: ami = var.ami[1]

  • For expressions. A for expression is available for iterating and filtering lists and map values. This expression always can be used anywhere a list or map is expected.

  • Dynamic blocks. Child blocks such as rule in aws_security_group can now be dynamically generated based on lists/maps and support iteration.

  • Generalized "Splat" Operator. The special resource.*.field syntax used to only work for resources with count set. This is now a generalized operator that works for any list value.

  • Conditional improvements. The conditional operator ... ? ... : ... now supports any value type and lazily evaluates results, as those familiar with this operator in other languages would expect. Also, the special value null can now be assigned to any field to represent the absence of a value. This causes Terraform to omit the field from upstream API calls, which is important in some cases for triggering certain default behaviors.

  • Rich types in module inputs and outputs. Terraform has supported basic lists and maps as inputs/outputs since Terraform 0.7, but elements were limited to only simple values. Terraform 0.12 allows arbitrarily complex lists and maps for any inputs and outputs, including with modules.

  • Template syntax. Within string values, a new template syntax can be used for looping without complex nested interpolation. Example: %{ for instance in aws_instance.example ~}server ${}%{ endfor }.

  • Reliable JSON syntax. Terraform 0.12 HCL configuration has an exact 1:1 mapping to and from JSON.

  • References as first-class values. References to resources and modules for fields such as depends_on used to be arbitrary strings. In Terraform 0.12, the resource identifier can be used exactly such as aws_kms_grant.example (no quotes!). This improves the validation and error messages we can provide. Similarly, a resource reference can be returned from a module as an output or accepted as a parameter.

Over the coming weeks we will publish blog posts going into more detail on each of the above improvements, plus a few more. Each post will include example snippets so you can more easily understand what has changed as well as any important information for upgrading to Terraform 0.12 related to that specific change.

»Breaking Changes

Introducing these changes has resulted in a number of breaking changes. Most users will be able to upgrade to Terraform 0.12 with no configuration changes. However, a small group of users will need to modify their configurations in some way.

We've published the work-in-progress Terraform 0.12 upgrade guide so that users can begin preparing for Terraform 0.12. Please note that this upgrade guide may continue to change prior to the release of Terraform 0.12. In particular, we're continuing to look for ways to automate or completely obviate some of the breaking changes.

In addition to the upgrade guide, we are working on automated tooling for some of the breaking changes so that the work isn't completely manual. As configurations are being written, we always recommend constraining the Terraform version for safe execution.


We're very excited about the improvements coming in Terraform 0.12. Many of these features have been requested for years, but they have required resetting the foundation of Terraform's configuration handling. With this new foundation in place, Terraform is poised to quickly improve and support new features over upcoming releases.

We apologize in advance for the breaking changes that we've introduced. We've already minimized the number of breaking changes over the past 6 months, and we will continue to evaluate if we can lower the number. Further, we've focused on the configuration changes in this release with the intention that future releases will not require any breaking changes.

If you have any feedback or concerns about the changes proposed, please get in touch with us via the public mailing list. We're happy to discuss any of these changes!

Over the coming weeks we'll publish feature preview blog posts diving into the individual improvements of Terraform 0.12!

Sign up for the latest HashiCorp news

By submitting this form, you acknowledge and agree that HashiCorp will process your personal information in accordance with the Privacy Policy.