github.com/muratcelep/terraform@v1.1.0-beta2-not-internal-4/website/upgrade-guides/0-10.html.markdown (about)

     1  ---
     2  layout: "language"
     3  page_title: "Upgrading to Terraform 0.10"
     4  sidebar_current: "upgrade-guides-0-10"
     5  description: |-
     6    Upgrading to Terraform v0.10
     7  ---
     8  
     9  # Upgrading to Terraform v0.10
    10  
    11  Terraform v0.10 is a major release and thus includes some changes that
    12  you'll need to consider when upgrading. This guide is intended to help with
    13  that process.
    14  
    15  The goal of this guide is to cover the most common upgrade concerns and
    16  issues that would benefit from more explanation and background. The exhaustive
    17  list of changes will always be the
    18  [Terraform Changelog](https://github.com/muratcelep/terraform/blob/main/CHANGELOG.md).
    19  After reviewing this guide, we recommend reviewing the Changelog to check on
    20  specific notes about the resources and providers you use.
    21  
    22  This guide focuses on changes from v0.9 to v0.10. Each previous major release
    23  has its own upgrade guide, so please consult the other guides (available
    24  in the navigation) if you are upgrading directly from an earlier version.
    25  
    26  ## Separated Provider Plugins
    27  
    28  As of v0.10, provider plugins are no longer included in the main Terraform
    29  distribution. Instead, they are distributed separately and installed
    30  automatically by
    31  [the `terraform init` command](/docs/cli/commands/init.html).
    32  
    33  In the long run, this new approach should be beneficial to anyone who wishes
    34  to upgrade a specific provider to get new functionality without also
    35  upgrading another provider that may have introduced incompatible changes.
    36  In the short term, it just means a smaller distribution package and thus
    37  avoiding the need to download tens of providers that may never be used.
    38  
    39  Provider plugins are now also versioned separately from Terraform itself.
    40  [Version constraints](/docs/language/providers/configuration.html#provider-versions)
    41  can be specified in configuration to ensure that new major releases
    42  (which may have breaking changes) are not automatically installed.
    43  
    44  **Action:** After upgrading, run `terraform init` in each Terraform
    45  configuration working directory to install the necessary provider plugins.
    46  If running Terraform in automation, this command should be run as the first
    47  step after a Terraform configuration is cloned from version control, and
    48  will also install any necessary modules and configure any remote backend.
    49  
    50  **Action:** For "production" configurations, consider adding
    51  [provider version constraints](/docs/language/providers/configuration.html#provider-versions),
    52  as suggested by the `terraform init` output, to prevent new major versions
    53  of plugins from being automatically installed in future.
    54  
    55  ### Third-party Provider Plugins
    56  
    57  This initial release of separated provider plugins applies only to the
    58  providers that are packaged and released by Hashicorp. The goal is to
    59  eventually support a similar approach for third-party plugins, but we wish
    60  to ensure the robustness of the installation and versioning mechanisms before
    61  generalizing this feature.
    62  
    63  -> **Note:** As of Terraform 0.13, Terraform can automatically install
    64  third-party providers released on the Terraform Registry.
    65  
    66  In the mean time, third-party providers can be installed by placing them in the
    67  user plugins directory:
    68  
    69  Operating system  | User plugins directory
    70  ------------------|-----------------------
    71  Windows           | `%APPDATA%\terraform.d\plugins`
    72  All other systems | `~/.terraform.d/plugins`
    73  
    74  Maintainers of third-party providers may optionally
    75  make use of the new versioning mechanism by naming provider binaries
    76  using the scheme `terraform-provider-NAME_v0.0.1`, where "0.0.1" is an
    77  example version. Terraform expects providers to follow the
    78  [semantic versioning](http://semver.org/) methodology.
    79  
    80  Although third-party providers with versions cannot currently be automatically
    81  installed, Terraform 0.10 _will_ verify that the installed version matches the
    82  constraints in configuration and produce an error if an acceptable version
    83  is unavailable.
    84  
    85  **Action:** No immediate action required, but third-party plugin maintainers
    86  may optionally begin using version numbers in their binary distributions to
    87  help users deal with changes over time.
    88  
    89  ## Recursive Module Targeting with `-target`
    90  
    91  It is possible to target all of the resources in a particular module by passing
    92  a module address to the `-target` argument:
    93  
    94  ```
    95  $ terraform plan -out=tfplan -target=module.example
    96  ```
    97  
    98  Prior to 0.10, this command would target only the resources _directly_ in
    99  the given module. As of 0.10, this behavior has changed such that the above
   100  command also targets resources in _descendent_ modules.
   101  
   102  For example, if `module.example` contains a module itself, called
   103  `module.examplechild`, the above command will target resources in both
   104  `module.example` _and_ `module.example.module.examplechild`.
   105  
   106  This also applies to other Terraform features that use
   107  [resource addressing](/docs/cli/state/resource-addressing.html) syntax.
   108  This includes some of the subcommands of
   109  [`terraform state`](/docs/cli/commands/state/index.html).
   110  
   111  **Action:** If running Terraform with `-target` in automation, review usage
   112  to ensure that selecting additional resources in child modules will not have
   113  ill effects. Be sure to review plan output when `-target` is used to verify
   114  that only the desired resources have been targeted for operations. Please
   115  note that it is not recommended to routinely use `-target`; it is provided for
   116  exceptional uses and manual intervention.
   117  
   118  ## Interactive Approval in `terraform apply`
   119  
   120  Starting with Terraform 0.10 `terraform apply` has a new mode where it will
   121  present the plan, pause for interactive confirmation, and then apply the
   122  plan only if confirmed. This is intended to get similar benefits to separately
   123  running `terraform plan`, but to streamline the workflow for interactive
   124  command-line use.
   125  
   126  For 0.10 this feature is disabled by default, to avoid breaking any wrapper
   127  scripts that are expecting the old behavior. To opt-in to this behavior,
   128  pass `-auto-approve=false` when running `terraform apply` without an explicit
   129  plan file.
   130  
   131  It is planned that a future version of Terraform will make this behavior the
   132  default. Although no immediate action is required, we strongly recommend
   133  adjusting any Terraform automation or wrapper scripts to prepare for this
   134  upcoming change in behavior, in the following ways:
   135  
   136  * Non-interative automation around production systems should _always_
   137    separately run `terraform plan -out=tfplan` and then (after approval)
   138    `terraform apply tfplan`, to ensure operators have a chance to review
   139    the plan before applying it.
   140  
   141  * If running `terraform apply` _without_ a plan file in automation for
   142    a _non-production_ system, add `-auto-approve=true` to the command line
   143    soon, to preserve the current 0.10 behavior once auto-approval is no longer
   144    enabled by default.
   145  
   146  We are using a staged deprecation for this change because we are aware that
   147  many teams use Terraform in wrapper scripts and automation, and we wish to
   148  ensure that such teams have an opportunity to update those tools in preparation
   149  for the future change in behavior.
   150  
   151  **Action:** 0.10 preserves the previous behavior as the default, so no
   152  immediate action is required. However, maintainers of tools that wrap
   153  Terraform, either in automation or in alternative command-line UI, should
   154  consider which behavior is appropriate for their use-case and explicitly
   155  set the `-auto-approve=...` flag to ensure that behavior in future versions.