github.com/rstandt/terraform@v0.12.32-0.20230710220336-b1063613405c/website/docs/commands/0.12upgrade.html.markdown (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Command: 0.12upgrade"
     4  sidebar_current: "docs-commands-012upgrade"
     5  description: |-
     6    The 0.12upgrade subcommand automatically rewrites existing configurations for Terraform 0.12 compatibility.
     7  ---
     8  
     9  # Command: 0.12upgrade
    10  
    11  The `terraform 0.12upgrade` command applies several automatic upgrade rules to
    12  help prepare a module that was written for Terraform v0.11 to be used
    13  with Terraform v0.12.
    14  
    15  -> This command requires **Terraform v0.12 or later**.
    16  
    17  ## Usage
    18  
    19  Usage: `terraform 0.12upgrade [options] [dir]`
    20  
    21  By default, `0.12upgrade` changes configuration files in the current working
    22  directory. However, you can provide an explicit path to another directory if
    23  desired, which may be useful for automating migrations of several modules in
    24  the same repository.
    25  
    26  When run with no other options, the command will first explain what it is
    27  going to do and prompt for confirmation:
    28  
    29  ```
    30  $ terraform 0.12upgrade
    31  
    32  This command will rewrite the configuration files in the given directory so
    33  that they use the new syntax features from Terraform v0.12, and will identify
    34  any constructs that may need to be adjusted for correct operation with
    35  Terraform v0.12.
    36  
    37  We recommend using this command in a clean version control work tree, so that
    38  you can easily see the proposed changes as a diff against the latest commit.
    39  If you have uncommitted changes already present, we recommend aborting this
    40  command and dealing with them before running this command again.
    41  
    42  Would you like to upgrade the module in the current directory?
    43    Only 'yes' will be accepted to confirm.
    44  
    45    Enter a value: yes
    46  ```
    47  
    48  The `0.12upgrade` subcommand requires access to providers used in the
    49  configuration in order to analyze their resource types, so it's important to
    50  run `terraform init` first to install these. In some rare cases, a configuration
    51  that worked in v0.11 may have syntax errors in v0.12, in which case
    52  `terraform init` will run in a special mode where it installs only enough to
    53  run the upgrade command, after which you can run `terraform init` again to
    54  complete initialization.
    55  
    56  Many of the rewrite rules are completely automatic, but in some cases the
    57  tool cannot determine enough information from the configuration alone to make
    58  a decision, and so it will instead add a comment to the configuration for
    59  user review. All such comments contain the string `TF-UPGRADE-TODO` to make
    60  them easy to find.
    61  
    62  After upgrading, the configuration will also be reformatted into the standard
    63  Terraform style and expressions rewritten to use the more-readable v0.12 syntax
    64  features.
    65  
    66  We recommend running this command with a clean version control work tree so
    67  that you can use VCS tools to review the proposed changes, including any
    68  `TF-UPGRADE-TODO` comments, and make any revisions required before committing
    69  the change.
    70  
    71  Once upgraded the configuration will no longer be compatible with Terraform
    72  v0.11 and earlier. When upgrading a shared module that is called from multiple
    73  configurations, you may need to
    74  [fix existing configurations to a previous version](/docs/configuration/modules.html#module-versions)
    75  to allow for a gradual upgrade. If the module is published via
    76  [a Terraform registry](/docs/registry/), assign a new _major_ version number
    77  to the upgraded module source to represent the fact that this is a breaking
    78  change for v0.11 callers. If a module is installed directly from a version
    79  control system such as Git,
    80  [use specific revisions](https://www.terraform.io/docs/modules/sources.html#selecting-a-revision)
    81  to control which version is used by which caller.
    82  
    83  The command-line options are all optional. The available options are:
    84  
    85  * `-yes` - Skip the initial introduction messages and interactive confirmation.
    86    Use this when running the command in batch from a script.
    87  
    88  * `-force` - Override the heuristic that attempts to detect if a configuration
    89    is already written for v0.12 or later. Some of the transformations made by
    90    this command are not idempotent, so re-running against the same module may
    91    change the meanings of some expressions in the module.
    92  
    93  ## Batch Usage
    94  
    95  After you've experimented with the `0.12upgrade` command in some confined
    96  situations, if you have a repository containing multiple modules you may
    97  wish to batch-upgrade them all and review them together. Recursive upgrades
    98  are not supported by the tool itself, but if you are on a Unix-style system
    99  you can achieve this using the `find` command as follows:
   100  
   101  ```
   102  find . -name '*.tf' -printf "%h\n" | uniq | xargs -n1 terraform 0.12upgrade -yes
   103  ```
   104  
   105  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:
   106  
   107  ```
   108  brew install findutils
   109  ```
   110  Once installed, run the above command line using `gfind` instead of `find`.
   111  
   112  
   113  Note that the above includes the `-yes` option to override the interactive
   114  prompt, so be sure you have a clean work tree before running it.
   115  
   116  Because upgrading requires access to the configuration's provider plugins,
   117  all of the directories must be initialized with `terraform init` prior to
   118  running the above.