ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

website: v0.12 preview upgrade guide tweaks 

Based on some feedback on the initial draft, make some minor updates to
how information is presented in the preview upgrade guide for v0.12.

This also includes some minor copy-editing work to try to make the "voice"
more consistent between different sections of the guide.
This commit is contained in:
Martin Atkins 2018-06-29 10:27:35 -07:00
parent 9ba33e1958
commit 9441e78fb9
1 changed files with 46 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
website/upgrade-guides/0-12.html.markdown
View File

@ -25,6 +25,7 @@ has its own upgrade guide, so please consult the other guides (available in the
navigation) if you are upgrading directly from an earlier version. navigation) if you are upgrading directly from an earlier version.
## Upgrading Terraform configuration ## Upgrading Terraform configuration
The majority of users will not need to make manual changes to their Terraform 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 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. changes are users who use language workarounds in previous Terraform versions.
@ -32,17 +33,25 @@ Examples of these workarounds include:
- Treating block types like attributes in an attempt to work around Terraform - Treating block types like attributes in an attempt to work around Terraform
not supporting generating nested blocks dynamically. 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 Note that these workarounds are not "wrong", but rather clever solutions by
dedicated community members! These folks have been the inspiration for HCL2 and dedicated community members! These folks have been the inspiration for HCL2 and
their clever solutions have given guidance on how to make the Terraform language these solutions have given guidance on how to make the Terraform language
more flexible to meet the needs of complex infrastructure. 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 For users who follow the examples in the Terraform documentation, there should
be no required changes. While no manual changes are needed, users can still run be no required changes. However, we still recommend to run the migration tool
the migration tool to convert to the more readable syntax supported in this to upgrade to the more readable syntax conventions supported in this release,
release. For those users, Terraform 0.12 will be released with a migration tool and to draw attention to any potential issues.
to guide users through upgrading their configurations.
## Upgrading Terraform providers ## Upgrading Terraform providers
@ -51,45 +60,45 @@ and schema transfer.
In Terraform 0.12 Terraform will have an awareness of the schemas used by both 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 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 still use the old-style passing of `map[string]interface{}` for config and
map[string]string with flatmap for state/diff. `map[string]string` with flatmap for state and diff.
In order to ease the transition to the new version of terraform, backwards To avoid the need to atomically upgrade both Terraform Core and the providers
compatible providers will be built allowing them to be used with previous all at once, new provider versions will be released that are compatible with
versions of terraform. Backwards compatibility through this mechanism is not a both v0.12 and prior versions. Users will need to upgrade to the new
long term strategy for maintaining providers in the event of further protocol v0.12-compatible provider releases before upgrading Terraform Core, but can
changes, and is only a stepping stone. use these newer provider releases with prior Terraform versions to transition
gradually and reduce risk.
Having new providers be backwards compatible with older versions of Terraform This compatibility support will be handled automatically by a new version of
alleviates provider developers from the responsibility of maintaining a branch the plugin SDK so that provider maintainers need only to upgrade to the
for backports, allows any major version changes to be available to older latest version and rebuild.
clients, and reduces the urgency for users to upgrade everything at once.
To upgrade a provider to use the new RPC plugin protocol in 0.12 and remain The dual-protocol compatibility will be retained at least until the next
backwards compatible with previous releases, providers will need to update their major release of the plugin SDK, in order to give users time to perform a
Terraform dependencies to a 0.12 release. The changes to the helper packages are gradual upgrade of each provider and of Terraform Core itself.
being designed so that updating the packages will allow the provider to work
with the new plugin protocol, while remaining compatible with previous Terraform
releases.
## Upgrading modules ## Upgrading modules
Module authors will need to complete several steps to get their modules 0.12
ready.
1. Follow the steps in "Upgrading Terraform configurations" to get the module Module authors will need to complete several steps to get their modules ready
code upgraded for v0.12.
1. The migration tool will automatically add a >= 0.12.0 Terraform version pin.
No action is needed, just awareness. 1. Follow the steps in "Upgrading Terraform configurations" above to get the
1. Update provider version requirements if there are version pins in the module module code upgraded
1. If you are using the Terraform Registry, publish a new major version of the 1. The migration tool will automatically add a `>= 0.12.0` Terraform version
module. If you are not using the registry, make sure downstream consumers of the constraint to indicate that the module has been upgraded to use v0.12-only
module are aware of the update. 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 Module consumers can then upgrade to the new versions of the module by upgrading
their configurations to 0.12 and updating the module version in that their configurations to 0.12 and updating the module version constraint in each
configuration. configuration to refer to the new major version.
## Upgrading Sentinel policies ## Upgrading Sentinel policies
Terraform Enterprise users of Sentinel will need to complete the below steps to Terraform Enterprise users of Sentinel will need to complete the below steps to
upgrade Sentinel to work with Terraform 0.12. upgrade Sentinel to work with Terraform 0.12.
@ -99,3 +108,5 @@ upgrade Sentinel to work with Terraform 0.12.
Because Sentinel is applied across all workspaces in Terraform Enterprise, all Because Sentinel is applied across all workspaces in Terraform Enterprise, all
workspaces must be upgraded to Terraform 0.12 otherwise Sentinel policies will workspaces must be upgraded to Terraform 0.12 otherwise Sentinel policies will
fail on versions below 0.12. fail on versions below 0.12.
More details on this upgrade process will be added prior to the final release.