github.com/hs0210/hashicorp-terraform@v0.11.12-beta1/website/upgrade-guides/0-12.html.markdown (about)

     1  ---
     2  layout: "downloads"
     3  page_title: "Upgrading to Terraform 0.12"
     4  sidebar_current: "upgrade-guides-0-12"
     5  description: |-
     6    Upgrading to Terraform v0.12
     7  ---
     8  
     9  # Upgrading to Terraform v0.12
    10  
    11  ~> Terraform 0.12 will not be released until later this summer. This guide is
    12  proactive to help users understand what the upgrade path to 0.12 will be like.
    13  This guide will be updated with more detail up until the release of 0.12.
    14  
    15  [Terraform v0.12 will be a major release](https://hashicorp.com/blog/terraform-0-1-2-preview)
    16  focused on configuration language improvements and thus will include some
    17  changes that you'll need to consider when upgrading. The goal of this guide is
    18  to cover the most common upgrade concerns and issues. For the majority of users,
    19  no steps will need to be taken to upgrade. The sections below explain which
    20  users are likely to be in the small group who will need to make manual changes
    21  to upgrade to 0.12.
    22  
    23  This guide focuses on changes from v0.11 to v0.12. Each previous major release
    24  has its own upgrade guide, so please consult the other guides (available in the
    25  navigation) if you are upgrading directly from an earlier version.
    26  
    27  ## Upgrading Terraform configuration
    28  
    29  The majority of users will not need to make manual changes to their Terraform
    30  configurations to upgrade to 0.12. The users who will need to make manual
    31  changes are users who use language workarounds in previous Terraform versions.
    32  Examples of these workarounds include:
    33  
    34  - Treating block types like attributes in an attempt to work around Terraform
    35    not supporting generating nested blocks dynamically.
    36    ([#7034](https://github.com/hashicorp/terraform/issues/7034))
    37  
    38  - Wrapping redundant list brackets (`[` and `]`) around splat expressions in
    39    order to force them to be interpreted as lists even when there are unknown
    40    items in the list.
    41  
    42  Note that these workarounds are not "wrong", but rather clever solutions by
    43  dedicated community members! These folks have been the inspiration for HCL2 and
    44  these solutions have given guidance on how to make the Terraform language
    45  more flexible to meet the needs of complex infrastructure.
    46  
    47  Terraform 0.12 will be released with a migration tool that will make most of
    48  the required updates automatically, and also provide guidance on any changes
    49  that require human input.
    50  
    51  For users who follow the examples in the Terraform documentation, there should
    52  be no required changes. However, we still recommend to run the migration tool
    53  to upgrade to the more readable syntax conventions supported in this release,
    54  and to draw attention to any potential issues.
    55  
    56  ## Upgrading Terraform providers
    57  
    58  We’ve updated the RPC protocol used by Terraform plugins to support typed data
    59  and schema transfer.
    60  
    61  In Terraform 0.12 Terraform will have an awareness of the schemas used by both
    62  provider and provisioner plugins. This V1 for the RPC plugin protocols will
    63  still use the old-style passing of `map[string]interface{}` for config and
    64  `map[string]string` with flatmap for state and diff.
    65  
    66  To avoid the need to atomically upgrade both Terraform Core and the providers
    67  all at once, new provider versions will be released that are compatible with
    68  both v0.12 and prior versions. Users will need to upgrade to the new
    69  v0.12-compatible provider releases before upgrading Terraform Core, but can
    70  use these newer provider releases with prior Terraform versions to transition
    71  gradually and reduce risk.
    72  
    73  This compatibility support will be handled automatically by a new version of
    74  the plugin SDK so that provider maintainers need only to upgrade to the
    75  latest version and rebuild.
    76  
    77  The dual-protocol compatibility will be retained at least until the next
    78  major release of the plugin SDK, in order to give users time to perform a
    79  gradual upgrade of each provider and of Terraform Core itself.
    80  
    81  ## Upgrading modules
    82  
    83  Module authors will need to complete several steps to get their modules ready
    84  for v0.12.
    85  
    86  1. Follow the steps in "Upgrading Terraform configurations" above to get the
    87     module code upgraded
    88  1. The migration tool will automatically add a `>= 0.12.0` Terraform version
    89     constraint to indicate that the module has been upgraded to use v0.12-only
    90     features.
    91  1. If the module is published in a module registry, publish a new major version
    92     of the module to indicate that the new version is not compatible with older
    93     versions of Terraform. If you are not using a registry, be sure that
    94     downstream consumers of the module are aware of the update.
    95  
    96  Module consumers can then upgrade to the new versions of the module by upgrading
    97  their configurations to 0.12 and updating the module version constraint in each
    98  configuration to refer to the new major version.
    99  
   100  ## Upgrading Sentinel policies
   101  
   102  Terraform Enterprise users of Sentinel will need to complete the below steps to
   103  upgrade Sentinel to work with Terraform 0.12.
   104  
   105  1. Update Terraform configurations to 0.12
   106  1. Update Sentinel policies
   107  
   108  Because Sentinel is applied across all workspaces in Terraform Enterprise, all
   109  workspaces must be upgraded to Terraform 0.12 otherwise Sentinel policies will
   110  fail on versions below 0.12.
   111  
   112  More details on this upgrade process will be added prior to the final release.