IntenseWebs/opentofu
3
0
Fork 0
mirror of https://github.com/opentofu/opentofu.git synced 2024-12-26 00:41:27 -06:00
Code Issues Packages Projects Releases Wiki Activity

website: Add docs for 0.13upgrade

Browse Source
This commit is contained in:
Alisdair McDiarmid 2020-05-11 09:09:41 -04:00
parent 1d834fb1d0
commit 20483da548
3 changed files with 92 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
website/docs/commands/0.12upgrade.html.markdown
View File

@ -1,118 +0,0 @@
---
layout: "docs"
page_title: "Command: 0.12upgrade"
sidebar_current: "docs-commands-012upgrade"
description: |-
The 0.12upgrade subcommand automatically rewrites existing configurations for Terraform 0.12 compatibility.
---
# Command: 0.12upgrade
The `terraform 0.12upgrade` command applies several automatic upgrade rules to
help prepare a module that was written for Terraform v0.11 to be used
with Terraform v0.12.
-> This command requires **Terraform v0.12 or later**.
## Usage
Usage: `terraform 0.12upgrade [options] [dir]`
By default, `0.12upgrade` changes configuration files in the current working
directory. However, you can provide an explicit path to another directory if
desired, which may be useful for automating migrations of several modules in
the same repository.
When run with no other options, the command will first explain what it is
going to do and prompt for confirmation:
```
$ terraform 0.12upgrade
This command will rewrite the configuration files in the given directory so
that they use the new syntax features from Terraform v0.12, and will identify
any constructs that may need to be adjusted for correct operation with
Terraform v0.12.
We recommend using this command in a clean version control work tree, so that
you can easily see the proposed changes as a diff against the latest commit.
If you have uncommitted changes already present, we recommend aborting this
command and dealing with them before running this command again.
Would you like to upgrade the module in the current directory?
Only 'yes' will be accepted to confirm.
Enter a value: yes
```
The `0.12upgrade` subcommand requires access to providers used in the
configuration in order to analyze their resource types, so it's important to
run `terraform init` first to install these. In some rare cases, a configuration
that worked in v0.11 may have syntax errors in v0.12, in which case
`terraform init` will run in a special mode where it installs only enough to
run the upgrade command, after which you can run `terraform init` again to
complete initialization.
Many of the rewrite rules are completely automatic, but in some cases the
tool cannot determine enough information from the configuration alone to make
a decision, and so it will instead add a comment to the configuration for
user review. All such comments contain the string `TF-UPGRADE-TODO` to make
them easy to find.
After upgrading, the configuration will also be reformatted into the standard
Terraform style and expressions rewritten to use the more-readable v0.12 syntax
features.
We recommend running this command with a clean version control work tree so
that you can use VCS tools to review the proposed changes, including any
`TF-UPGRADE-TODO` comments, and make any revisions required before committing
the change.
Once upgraded the configuration will no longer be compatible with Terraform
v0.11 and earlier. When upgrading a shared module that is called from multiple
configurations, you may need to
[fix existing configurations to a previous version](/docs/configuration/modules.html#module-versions)
to allow for a gradual upgrade. If the module is published via
[a Terraform registry](/docs/registry/), assign a new _major_ version number
to the upgraded module source to represent the fact that this is a breaking
change for v0.11 callers. If a module is installed directly from a version
control system such as Git,
[use specific revisions](https://www.terraform.io/docs/modules/sources.html#selecting-a-revision)
to control which version is used by which caller.
The command-line options are all optional. The available options are:
* `-yes` - Skip the initial introduction messages and interactive confirmation.
Use this when running the command in batch from a script.
* `-force` - Override the heuristic that attempts to detect if a configuration
is already written for v0.12 or later. Some of the transformations made by
this command are not idempotent, so re-running against the same module may
change the meanings of some expressions in the module.
## Batch Usage
After you've experimented with the `0.12upgrade` command in some confined
situations, if you have a repository containing multiple modules you may
wish to batch-upgrade them all and review them together. Recursive upgrades
are not supported by the tool itself, but if you are on a Unix-style system
you can achieve this using the `find` command as follows:
```
find . -name '*.tf' -printf "%h\n" | uniq | xargs -n1 terraform 0.12upgrade -yes
```
On Mac OS X, the `find` included with the system does not support the `-printf` argument. You can install GNU find using Homebrew in order to use that argument:
```
brew install findutils
```
Once installed, run the above command line using `gfind` instead of `find`.
Note that the above includes the `-yes` option to override the interactive
prompt, so be sure you have a clean work tree before running it.
Because upgrading requires access to the configuration's provider plugins,
all of the directories must be initialized with `terraform init` prior to
running the above.

90
website/docs/commands/0.13upgrade.html.markdown Normal file
View File

@ -0,0 +1,90 @@
---
layout: "docs"
page_title: "Command: 0.13upgrade"
sidebar_current: "docs-commands-013upgrade"
description: |-
The 0.13upgrade subcommand updates existing configurations to use the new provider source features from Terraform 0.13.
---
# Command: 0.13upgrade
The `terraform 0.13upgrade` command updates existing configuration to add an
explicit `source` attribute for each provider used in a given module. The
provider source settings are stored in a `required_providers` block.
-> This command requires **Terraform v0.13 or later**.
## Usage
Usage: `terraform 0.13upgrade [options] [dir]`
The primary purpose of the `0.13upgrade` command is to determine which
providers are in use for a module, detect the source address for those
providers where possible, and record this information in a
[`required_providers` block][required-providers].
[required-providers]: /docs/configuration/terraform.html#specifying-required-provider-versions
~> Note: the command ignores `.tf.json` files and override files in the module.
If the module already has a `required_providers` block, the command updates it
in-place. Otherwise, a new block is added to the `versions.tf` file.
By default, `0.13upgrade` changes configuration files in the current working
directory. However, you can provide an explicit path to another directory if
desired, which may be useful for automating migrations of several modules in
the same repository.
When run with no other options, the command will first explain what it is
going to do and prompt for confirmation:
```
$ terraform 0.13upgrade
This command will update the configuration files in the given directory to use
the new provider source features from Terraform v0.13. It will also highlight
any providers for which the source cannot be detected, and advise how to
proceed.
We recommend using this command in a clean version control work tree, so that
you can easily see the proposed changes as a diff against the latest commit.
If you have uncommited changes already present, we recommend aborting this
command and dealing with them before running this command again.
Would you like to upgrade the module in the current directory?
Only 'yes' will be accepted to confirm.
Enter a value: yes
```
We recommend running this command with a clean version control work tree so
that you can use VCS tools to review the proposed changes, including any
`TF-UPGRADE-TODO` comments, and make any revisions required before committing
the change.
There is one command-line option:
* `-yes` - Skip the initial introduction messages and interactive confirmation.
Use this when running the command in batch from a script.
## Batch Usage
After you've experimented with the `0.13upgrade` command in some confined
situations, if you have a repository containing multiple modules you may
wish to batch-upgrade them all and review them together. Recursive upgrades
are not supported by the tool itself, but if you are on a Unix-style system
you can achieve this using the `find` command as follows:
```
$ find . -name '*.tf' | xargs -n1 dirname | uniq | xargs -n1 terraform 0.13upgrade -yes
```
On a Windows system with PowerShell, you can use this command:
```
Get-Childitem -Recurse -Include *.tf | Split-Path | `
Select-Object -Unique | ForEach-Object { terraform 0.13upgrade -yes $_.FullName }
```
Note that the above commands include the `-yes` option to override the
interactive prompt, so be sure you have a clean work tree before running it.

4
website/layouts/docs.erb
View File

@ -238,8 +238,8 @@
<a href="/docs/commands/workspace/index.html">workspace</a>
</li>
<li<%= sidebar_current("docs-commands-012upgrade") %>>
<a href="/docs/commands/0.12upgrade.html">0.12upgrade</a>
<li<%= sidebar_current("docs-commands-013upgrade") %>>
<a href="/docs/commands/0.13upgrade.html">0.13upgrade</a>
</li>
</ul>
</li>