Merge pull request #24915 from hashicorp/alisdair/013upgrade-docs

website: Add docs for 0.13upgrade

website/docs/commands/0.12upgrade.html.markdown

@@ -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.

website/docs/commands/0.13upgrade.html.markdown

@@ -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.

website/layouts/docs.erb

@@ -238,8 +238,8 @@
             <a href="/docs/commands/workspace/index.html">workspace</a>
           </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>
         </ul>
       </li>