113 lines
5.1 KiB
Markdown
113 lines
5.1 KiB
Markdown
---
|
||
layout: "downloads"
|
||
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 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](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.
|