github.com/hugorut/terraform@v1.1.3/website/docs/cli/commands/0.12upgrade.mdx (about)

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