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

---
layout: "guides"
page_title: "Upgrading to Terraform 0.12"
sidebar_current: "upgrade-guides-0-12"
description: |-
  Upgrading to Terraform v0.12
---

# Upgrading to Terraform v0.12

~> Terraform 0.12 has not yet been released. 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](https://hashicorp.com/blog/terraform-0-1-2-preview)
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](https://github.com/hashicorp/terraform/issues/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
1. 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.
1. 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
1. 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.