terraform/website/upgrade-guides/0-12.html.markdown

layout	page_title	sidebar_current	description
downloads	Upgrading to Terraform 0.12	upgrade-guides-0-12	Upgrading to Terraform v0.12

Upgrading to Terraform v0.12

~> Terraform 0.12 will not be released until later this summer. This guide is proactive to help users understand what the upgrade path to 0.12 will be like. This guide will be updated with more detail up until the release of 0.12.

Terraform v0.12 will be a major release focused on configuration language improvements and thus will include some changes that you'll need to consider when upgrading. The goal of this guide is to cover the most common upgrade concerns and issues. For the majority of users, no steps will need to be taken to upgrade. The sections below explain which users are likely to be in the small group who will need to make manual changes to upgrade to 0.12.

This guide focuses on changes from v0.11 to v0.12. Each previous major release has its own upgrade guide, so please consult the other guides (available in the navigation) if you are upgrading directly from an earlier version.

Upgrading Terraform configuration

The majority of users will not need to make manual changes to their Terraform configurations to upgrade to 0.12. The users who will need to make manual changes are users who use language workarounds in previous Terraform versions. Examples of these workarounds include:

• Treating block types like attributes in an attempt to work around Terraform not supporting generating nested blocks dynamically. (#7034)

• Wrapping redundant list brackets ([ and ]) around splat expressions in order to force them to be interpreted as lists even when there are unknown items in the list.

Note that these workarounds are not "wrong", but rather clever solutions by dedicated community members! These folks have been the inspiration for HCL2 and these solutions have given guidance on how to make the Terraform language more flexible to meet the needs of complex infrastructure.

Terraform 0.12 will be released with a migration tool that will make most of the required updates automatically, and also provide guidance on any changes that require human input.

For users who follow the examples in the Terraform documentation, there should be no required changes. However, we still recommend to run the migration tool to upgrade to the more readable syntax conventions supported in this release, and to draw attention to any potential issues.

Upgrading Terraform providers

We’ve updated the RPC protocol used by Terraform plugins to support typed data and schema transfer.

In Terraform 0.12 Terraform will have an awareness of the schemas used by both provider and provisioner plugins. This V1 for the RPC plugin protocols will still use the old-style passing of map[string]interface{} for config and map[string]string with flatmap for state and diff.

To avoid the need to atomically upgrade both Terraform Core and the providers all at once, new provider versions will be released that are compatible with both v0.12 and prior versions. Users will need to upgrade to the new v0.12-compatible provider releases before upgrading Terraform Core, but can use these newer provider releases with prior Terraform versions to transition gradually and reduce risk.

This compatibility support will be handled automatically by a new version of the plugin SDK so that provider maintainers need only to upgrade to the latest version and rebuild.

The dual-protocol compatibility will be retained at least until the next major release of the plugin SDK, in order to give users time to perform a gradual upgrade of each provider and of Terraform Core itself.

Upgrading modules

Module authors will need to complete several steps to get their modules ready for v0.12.

1. Follow the steps in "Upgrading Terraform configurations" above to get the module code upgraded
2. The migration tool will automatically add a >= 0.12.0 Terraform version constraint to indicate that the module has been upgraded to use v0.12-only features.
3. If the module is published in a module registry, publish a new major version of the module to indicate that the new version is not compatible with older versions of Terraform. If you are not using a registry, be sure that downstream consumers of the module are aware of the update.

Module consumers can then upgrade to the new versions of the module by upgrading their configurations to 0.12 and updating the module version constraint in each configuration to refer to the new major version.

Upgrading Sentinel policies

Terraform Enterprise users of Sentinel will need to complete the below steps to upgrade Sentinel to work with Terraform 0.12.

1. Update Terraform configurations to 0.12
2. Update Sentinel policies

Because Sentinel is applied across all workspaces in Terraform Enterprise, all workspaces must be upgraded to Terraform 0.12 otherwise Sentinel policies will fail on versions below 0.12.

More details on this upgrade process will be added prior to the final release.