mirror of
https://github.com/opentofu/opentofu.git
synced 2025-02-25 18:45:20 -06:00
website: initial v0.10 upgrade guide
Further iteration of this will undoubtedly be needed before the final release, but this is a start.
This commit is contained in:
parent
98ef947ed1
commit
55d5e8a689
@ -8,6 +8,9 @@
|
||||
<li<%= sidebar_current("upgrade-guides") %>>
|
||||
<a href="/upgrade-guides/index.html">Upgrade Guides</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("upgrade-guides-0-10") %>>
|
||||
<a href="/upgrade-guides/0-10.html">Upgrading to v0.10</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("upgrade-guides-0-9") %>>
|
||||
<a href="/upgrade-guides/0-9.html">Upgrading to v0.9</a>
|
||||
</li>
|
||||
|
146
website/source/upgrade-guides/0-10.html.markdown
Normal file
146
website/source/upgrade-guides/0-10.html.markdown
Normal file
@ -0,0 +1,146 @@
|
||||
---
|
||||
layout: "downloads"
|
||||
page_title: "Upgrading to Terraform 0.10"
|
||||
sidebar_current: "upgrade-guides-0-10"
|
||||
description: |-
|
||||
Upgrading to Terraform v0.10
|
||||
---
|
||||
|
||||
# Upgrading to Terraform v0.10
|
||||
|
||||
Terraform v0.10 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.9 to v0.10. 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.
|
||||
|
||||
## Separated Provider Plugins
|
||||
|
||||
As of v0.10, provider plugins are no longer included in the main Terraform
|
||||
distribution. Instead, they are distributed separately and installed
|
||||
automatically by
|
||||
[the `terraform init` command](/docs/commands/init.html).
|
||||
|
||||
In the long run, this new approach should be beneficial to anyone who wishes
|
||||
to upgrade a specific provider to get new functionality without also
|
||||
upgrading another provider that may have introduced incompatible changes.
|
||||
In the short term, it just means a smaller distribution package and thus
|
||||
avoiding the need to download tens of providers that may never be used.
|
||||
|
||||
Provider plugins are now also versioned separately from Terraform itself.
|
||||
[Version constraints](/docs/configuration/providers.html#provider-versions)
|
||||
can be specified in configuration to ensure that new major releases
|
||||
(which may have breaking changes) are not automatically installed.
|
||||
|
||||
**Action:** After upgrading, run `terraform init` in each Terraform
|
||||
configuration working directory to install the necessary provider plugins.
|
||||
If running Terraform in automation, this command should be run as the first
|
||||
step after a Terraform configuration is cloned from version control, and
|
||||
will also install any necessary modules and configure any remote backend.
|
||||
|
||||
**Action:** For "production" configurations, consider adding
|
||||
[provider version constraints](/docs/configuration/providers.html#provider-versions),
|
||||
as suggested by the `terraform init` output, to prevent new major versions
|
||||
of plugins from being automatically installed in future.
|
||||
|
||||
### Third-party Provider Plugins
|
||||
|
||||
This initial release of separated provider plugins applies only to the
|
||||
providers that are packaged and released by Hashicorp. The goal is to
|
||||
eventually support a similar approach for third-party plugins, but we wish
|
||||
to ensure the robustness of the installation and versioning mechanisms before
|
||||
generalizing this feature.
|
||||
|
||||
In the mean time,
|
||||
[the prior mechanisms for installing third-party providers](/docs/plugins/basics.html#installing-a-plugin)
|
||||
are still supported. Maintainers of third-party providers may optionally
|
||||
make use of the new versioning mechanism by naming provider binaries
|
||||
using the scheme `terraform-provider-NAME-V0.0.1`, where "0.0.1" is an
|
||||
example version. Terraform expects providers to follow
|
||||
[semantic versioning](http://semver.org/) methodology.
|
||||
|
||||
Although third-party providers with versions cannot currently be automatically
|
||||
installed, Terraform 0.10 _will_ verify that the installed version matches the
|
||||
constraints in configuration and produce an error if an acceptable version
|
||||
is unavailable.
|
||||
|
||||
**Action:** No immediate action required, but third-party plugin maintainers
|
||||
may optionally begin using version numbers in their binary distributions to
|
||||
help users deal with changes over time.
|
||||
|
||||
## Recursive Module Targeting with `-target`
|
||||
|
||||
It is possible to target all of the resources in a particular module by passing
|
||||
a module address to the `-target` argument:
|
||||
|
||||
```
|
||||
$ terraform plan -out=tfplan -target=module.example
|
||||
```
|
||||
|
||||
Prior to 0.10, this command would target only the resources _directly_ in
|
||||
the given module. As of 0.10, this behavior has changed such that the above
|
||||
command also targets resources in _descendent_ modules.
|
||||
|
||||
For example, if `module.example` contains a module itself, called
|
||||
`module.examplechild`, the above command will target resources in both
|
||||
`module.example` _and_ `module.example.module.examplechild`.
|
||||
|
||||
This also applies to other Terraform features that use
|
||||
[resource addressing](/docs/internals/resource-addressing.html) syntax.
|
||||
This includes some of the subcommands of
|
||||
[`terraform state`](http://127.0.0.1:4567/docs/commands/state/index.html).
|
||||
|
||||
**Action:** If running Terraform with `-target` in automation, review usage
|
||||
to ensure that selecting additional resources in child modules will not have
|
||||
ill effects. Be sure to review plan output when `-target` is used to verify
|
||||
that only the desired resources have been targeted for operations. Please
|
||||
note that it is not recommended to routinely use `-target`; it is provided for
|
||||
exceptional uses and manual intervention.
|
||||
|
||||
## Interactive Approval in `terraform apply`
|
||||
|
||||
Starting with Terraform 0.10 `terraform apply` has a new mode where it will
|
||||
present the plan, pause for interactive confirmation, and then apply the
|
||||
plan only if confirmed. This is intended to get similar benefits to separately
|
||||
running `terraform plan`, but to streamline the workflow for interactive
|
||||
command-line use.
|
||||
|
||||
For 0.10 this feature is disabled by default, to avoid breaking any wrapper
|
||||
scripts that are expecting the old behavior. To opt-in to this behavior,
|
||||
pass `-auto-approve=false` when running `terraform apply` without an explicit
|
||||
plan file.
|
||||
|
||||
It is planned that a future version of Terraform will make this behavior the
|
||||
default. Although no immediate action is required, we strongly recommend
|
||||
adjusting any Terraform automation or wrapper scripts to prepare for this
|
||||
upcoming change in behavior, in the following ways:
|
||||
|
||||
* Non-interative automation around production systems should _always_
|
||||
separately run `terraform plan -out=tfplan` and then (after approval)
|
||||
`terraform apply tfplan`, to ensure operators have a chance to review
|
||||
the plan before applying it.
|
||||
|
||||
* If running `terraform apply` _without_ a plan file in automation for
|
||||
a _non-production_ system, add `-auto-approve=true` to the command line
|
||||
soon, to preserve the current 0.10 behavior once auto-approval is no longer
|
||||
enabled by default.
|
||||
|
||||
We are using a staged deprecation for this change because we are aware that
|
||||
many teams use Terraform in wrapper scripts and automation, and we wish to
|
||||
ensure that such teams have an opportunity to update those tools in preparation
|
||||
for the future change in behavior.
|
||||
|
||||
**Action:** 0.10 preserves the previous behavior as the default, so no
|
||||
immediate action is required. However, maintainers of tools that wrap
|
||||
Terraform, either in automation or in alternative command-line UI, should
|
||||
consider which behavior is appropriate for their use-case and explicitly
|
||||
set the `-auto-approve=...` flag to ensure that behavior in future versions.
|
Loading…
Reference in New Issue
Block a user