From 8dc4aead294d98abbf9a9a546bd8ecc02a8640ba Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 13 Dec 2024 14:07:19 -0800 Subject: [PATCH] re-added upgrade commands --- website/data/cli-nav-data.json | 16 +++ website/docs/cli/commands/0.12upgrade.mdx | 117 ++++++++++++++++++++++ website/docs/cli/commands/0.13upgrade.mdx | 89 ++++++++++++++++ website/docs/cli/commands/apply.mdx | 3 +- 4 files changed, 223 insertions(+), 2 deletions(-) create mode 100644 website/docs/cli/commands/0.12upgrade.mdx create mode 100644 website/docs/cli/commands/0.13upgrade.mdx diff --git a/website/data/cli-nav-data.json b/website/data/cli-nav-data.json index 6bc6030ed7..2bae97955c 100644 --- a/website/data/cli-nav-data.json +++ b/website/data/cli-nav-data.json @@ -331,6 +331,14 @@ { "title": "workspace show", "href": "/cli/commands/workspace/show" + }, + { + "title": "0.12upgrade", + "href": "/cli/commands/0.12upgrade" + }, + { + "title": "0.13upgrade", + "href": "/cli/commands/0.13upgrade" } ] }, @@ -398,6 +406,14 @@ { "title": "workspace delete", "path": "commands/workspace/delete" }, { "title": "workspace show", "path": "commands/workspace/show" } ] + }, + { + "title": "0.12upgrade", + "path": "commands/0.12upgrade" + }, + { + "title": "0.13upgrade", + "path": "commands/0.13upgrade" } ] }, diff --git a/website/docs/cli/commands/0.12upgrade.mdx b/website/docs/cli/commands/0.12upgrade.mdx new file mode 100644 index 0000000000..ef4cebb75e --- /dev/null +++ b/website/docs/cli/commands/0.12upgrade.mdx @@ -0,0 +1,117 @@ +--- +page_title: terraform 0.12upgrade command reference +description: >- + The `terraform 0.12upgrade` command automatically rewrites existing configurations for + Terraform 0.12 compatibility. +--- + +# `terraform 0.12upgrade` command + +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 is available only in Terraform v0.12 releases.** For more information, see [the Terraform v0.12 upgrade guide](/terraform/language/v1.1.x/upgrade-guides/0-12). + +## 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 easier 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](/terraform/language/modules/syntax#version) +to allow for a gradual upgrade. If the module is published via +[a Terraform registry](/terraform/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](/terraform/language/modules/sources#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. \ No newline at end of file diff --git a/website/docs/cli/commands/0.13upgrade.mdx b/website/docs/cli/commands/0.13upgrade.mdx new file mode 100644 index 0000000000..0cc459b42b --- /dev/null +++ b/website/docs/cli/commands/0.13upgrade.mdx @@ -0,0 +1,89 @@ +--- +page_title: terraform 0.13upgrade command reference +description: >- + The `terraform 0.13upgrade` command updates existing configurations to use the new + provider source features from Terraform 0.13. +--- + +# `terraform 0.13upgrade` command + +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 is available only in Terraform v0.13 releases.** For more information, see [the Terraform v0.13 upgrade guide](/terraform/language/v1.1.x/upgrade-guides/0-13). + +## 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]: /terraform/language/providers/requirements + +~> 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. \ No newline at end of file diff --git a/website/docs/cli/commands/apply.mdx b/website/docs/cli/commands/apply.mdx index 026b8e882a..2eb5a9a8c6 100644 --- a/website/docs/cli/commands/apply.mdx +++ b/website/docs/cli/commands/apply.mdx @@ -1,7 +1,6 @@ --- page_title: terraform apply command reference -description: >- - The terraform apply command executes the actions proposed in a Terraform plan +description: The `terraform apply` command executes the actions proposed in a Terraform plan to create, update, or destroy infrastructure. ---