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. 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
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 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 with 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.
If a
provider
block is present in a child module, it must either contain a complete configuration for its associated provider or a configuration must be passed from the parent module using the newproviders
attribute. In the latter case, an empty provider block is a placeholder that declares that the child module requires a configuration to be passed from its parent.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:
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 a default (non-aliased) provider is used, and not explicitly declared in a child module, automatic inheritance of that provider 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
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, as described in the following section.
Moving Provider Configurations to the Root Module
With the new provider inheritance model, it is strongly recommended to refactor
any configuration where child modules define their own provider
blocks so
that all explicit configuration is defined in the root module. This approach
will ensure that removing a module from the configuration will not cause
any provider configurations to be removed along with it, and thus ensure that
all of the module's resources can be successfully refreshed and destroyed.
A common configuration is where two child modules have different configurations for the same provider, like this:
The above example is problematic because removing either module.network-use1
or module.network-usw2
from the root module will make the corresponding
provider configuration no longer available, as described in
issue #15762, which
prevents Terraform from refreshing or destroying that module's aws_vpc.example
resource.
This can be addressed by moving the provider
blocks into the root module
as additional configurations, and then passing them down to the child
modules as default configurations via the explicit providers
map:
After the above refactoring, run terraform apply
to re-synchoronize
Terraform's record (in the Terraform state) of the
location of each resource's provider configuration. This should make no changes
to actual infrastructure, since no resource configurations were changed.
For more details on the explicit providers
map, and discussion of more
complex possibilities such as child modules with additional (aliased) provider
configurations, see Providers Within Modules.
Error Checking for Output Values
Prior to Terraform 0.11, if an error occurred 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.
Referencing Attributes from Resources with count = 0
A common pattern for conditional resources is to conditionally set count
to either 0
or 1
depending on the result of a boolean expression:
When using this pattern, it's required to use a special idiom to access attributes of this resource to account for the case where no resource is created at all:
Accessing aws_instance.example.id
directly is an error when count = 0
.
This is true for all situations where interpolation expressions are allowed,
but previously appeared to work for outputs due to the suppression of the
error. Existing outputs that access non-existent resources must be updated to
use the idiom above after upgrading to 0.11.0.