website: Add docs for 0.13upgrade
This commit is contained in:
parent
1d834fb1d0
commit
20483da548
|
@ -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.
|
|
|
@ -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.
|
|
@ -238,8 +238,8 @@
|
||||||
<a href="/docs/commands/workspace/index.html">workspace</a>
|
<a href="/docs/commands/workspace/index.html">workspace</a>
|
||||||
</li>
|
</li>
|
||||||
|
|
||||||
<li<%= sidebar_current("docs-commands-012upgrade") %>>
|
<li<%= sidebar_current("docs-commands-013upgrade") %>>
|
||||||
<a href="/docs/commands/0.12upgrade.html">0.12upgrade</a>
|
<a href="/docs/commands/0.13upgrade.html">0.13upgrade</a>
|
||||||
</li>
|
</li>
|
||||||
</ul>
|
</ul>
|
||||||
</li>
|
</li>
|
||||||
|
|
Loading…
Reference in New Issue