From 56a9b1309a70f3ecc873814f609f48ad762ad121 Mon Sep 17 00:00:00 2001 From: Martin Atkins Date: Mon, 30 Oct 2017 17:34:42 -0700 Subject: [PATCH] website: initial draft of 0.11 upgrade guide This will be revised further as we near the final release. This contains notes on changes that have already been merged. --- website/upgrade-guides/0-11.html.markdown | 180 ++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 website/upgrade-guides/0-11.html.markdown diff --git a/website/upgrade-guides/0-11.html.markdown b/website/upgrade-guides/0-11.html.markdown new file mode 100644 index 000000000..bffbe8a1f --- /dev/null +++ b/website/upgrade-guides/0-11.html.markdown @@ -0,0 +1,180 @@ +--- +layout: "downloads" +page_title: "Upgrading to Terraform 0.11" +sidebar_current: "upgrade-guides-0-11" +description: |- + Upgrading to Terraform v0.11 +--- + +# Upgrading to Terraform v0.11 + +Terraform v0.11 is a major release and thus includes some changes that +you'll need to consider when upgrading. This guide is intended to help with +that process. + +The goal of this guide is to cover the most common upgrade concerns and +issues that would benefit from more explanation and background. The exhaustive +list of changes will always be the +[Terraform Changelog](https://github.com/hashicorp/terraform/blob/master/CHANGELOG.md). +After reviewing this guide, we recommend reviewing the Changelog to check on +specific notes about the resources and providers you use. + +This guide focuses on changes from v0.10 to v0.11. 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. + +## Interactive Approval in `terraform apply` + +Terraform 0.10 introduced a new mode for `terraform apply` (when run without +an explicit plan file) where it would show a plan and prompt for approval +before proceeding, similar to `terraform destroy`. + +Terraform 0.11 adopts this as the default behavior for this command, which +means that for interactive use in a terminal it is not necessary to separately +run `terraform plan -out=...` to safely review and apply a plan. + +The new behavior also has the additional advantage that, when using a backend +that supports locking, the state lock will be held throughout the refresh, +plan, confirmation and apply steps, ensuring that a concurrent execution +of `terraform apply` will not invalidate the execution plan. + +A consequence of this change is that `terraform apply` is now interactive by +default unless a plan file is provided on the command line. When +[running Terraform in automation](/guides/running-terraform-in-automation.html) +it is always recommended to separate plan from apply, but if existing automation +was running `terraform apply` with no arguments it may now be necessary to +update it to either generate an explicit plan using `terraform plan -out=...` +or to run `terraform apply -auto-approve` to bypass the interactive confirmation +step. The latter should be done only in unimportant environments. + +**Action:** For interactive use in a terminal, prefer to use `terraform apply` +with out an explicit plan argument rather than `terraform plan -out=tfplan` +followed by `terraform apply tfplan`. + +**Action:** Update any automation scripts that run Terraform non-interactively +so that they either use separated plan and apply or override the confirmation +behavior using the `-auto-approve` option. + +## Relative Paths in Module `source` + +Terraform 0.11 introduces full support for module installation from +[Terraform Registry](https://registry.terraform.io/) as well as other +private, in-house registries using concise module source strings like +`hashicorp/consul/aws`. + +As a consequence, module source strings like `"child"` are no longer +interpreted as relative paths. Instead, relative paths must be expressed +explicitly by beginning the string with either `./` (for a module in a child +directory) or `../` (for a module in the parent directory). + +**Action:** Update existing module `source` values containing relative paths +to start eith either `./` or `../` to prevent misinterpretation of the source +as a Terraform Registry module. + +## Interactions Between Providers and Modules + +Prior to Terraform 0.11 there were several limitations in deficiencies in +how providers interact with child modules, such as: + +* Ancestor module provider configurations always overrode the associated + settings in descendent modules. + +* There was no well-defined mechanism for passing "aliased" providers from + an ancestor module to a descendent, where the descendent needs access to + multiple provider instances. + +Terraform 0.11 changes some of the details of how each resource block is +associated with a provider configuration, which may change how Terraform +interprets existing configurations. This is notably true in the following +situations: + +* If the same provider is configured in both an ancestor and a descendent + module, the ancestor configuration no longer overrides attributes from + the descendent and the descendent no longer inherits attributes from + its ancestor. Instead, each configuration is entirely distinct. + +* Only unaliased provider configurations can be automatically inherited from + ancestor modules. Aliased providers must be passed explicitly using + [the new `providers` attribute](/docs/modules/usage.html#providers-within-modules). + +* When a module containing its own `provider` blocks is removed from its + parent module, Terraform will no longer attempt to associate it with + another provider of the same name in a parent module, since that would + often cause undesirable effects such as attempting to refresh resources + in the wrong region. Instead, the resources in the module resources must be + explicitly destroyed _before_ removing the module, so that the provider + configuration is still available: `terraform destroy -target=module.example`. + +The recommended design pattern moving forward is to place all explicit +`provider` blocks in the root module of the configuration, and to pass +providers explicitly to child modules so that the associations are obvious +from configuration: + +```hcl +provider "aws" { + region = "us-east-1" + alias = "use1" +} + +provider "aws" { + region = "us-west-1" + alias = "usw1" +} + +module "example-use1" { + source = "./example" + + providers = { + "aws": "aws.use1", + } +} + +module "example-usw1" { + source = "./example" + + providers = { + "aws": "aws.usw1", + } +} +``` + +With the above configuration, any `aws` provider resources in the module +`./example` will use the us-east-1 provider configuration for +`module.example-use1` and the us-west-1 provider configuration for +`module.example-usw1`. + +When only default (non-aliased) providers are in use, automatic inheritance +to child modules is still supported. + +**Action**: In existing configurations where both a descendent module and +one of its ancestor modules both configure the same provider, copy any +settings from the ancestor into the descendent because provider configurations +now inherit only as a whole, rather than on a per-argument basis. + +**Action**: In existing configurations where a descendent module inherits +_aliased_ providers from an ancestor module, use +[the new `providers` attribute](/docs/modules/usage.html#providers-within-modules) +to explicitly pass those aliased providers. + +**Action**: Consider refactoring existing configurations so that all provider +configurations are set in the root module and passed explicitly to child +modules. + +## Error Checking for Output Values + +Prior to Terraform 0.11, if an error occured when evaluating the `value` +expression within an `output` block then it would be silently ignored and +the empty string used as the result. This was inconvenient because it made it +very hard to debug errors within output expressions. + +To give better feedback, Terraform now halts and displays an error message +when such errors occur, similar to the behavior for expressions elsewhere +in the configuration. + +Unfortunately, this means that existing configurations may have erroneous +outputs lurking that will become fatal errors after upgrading to Terraform 0.11. +The prior behavior is no longer available; to apply such a configuration with +Terraform 0.11 will require adjusting the configuration to avoid the error. + +**Action:** If any existing output value expressions contain errors, change these +expressions to fix the error.