github.com/bpineau/terraform@v0.8.0-rc1.0.20161126184705-a8886012d185/website/source/upgrade-guides/0-8.html.markdown (about)

     1  ---
     2  layout: "downloads"
     3  page_title: "Upgrading to Terraform 0.8"
     4  sidebar_current: "upgrade-guides-0-8"
     5  description: |-
     6    Upgrading to Terraform v0.8
     7  ---
     8  
     9  # Upgrading to Terraform v0.8
    10  
    11  ~> **Terraform 0.8 is still a release candidate.** The final stable version
    12     has not been released yet. This upgrade guide may still change between now and
    13     the final version.
    14  
    15  Terraform v0.8 is a major release and thus includes some backwards
    16  incompatibilities that you'll need to consider when upgrading. This guide is
    17  meant to help with that process.
    18  
    19  The goal of this guide is to cover the most common upgrade concerns and
    20  issues that would benefit from more explanation and background. The exhaustive
    21  list of changes will always be the
    22  [Terraform Changelog](https://github.com/hashicorp/terraform/blob/master/CHANGELOG.md).
    23  After reviewing this guide, we recommend reviewing the Changelog to check on
    24  specific notes about the resources and providers you use.
    25  
    26  ## Math Order of Operations
    27  
    28  Math operations now follow standard mathematical order of operations.
    29  Prior to 0.8, math ordering was simply left-to-right. With 0.8, `*`, `/`, and
    30  `%` are done before `+`, `-`.
    31  
    32  Some examples are shown below:
    33  
    34  ```
    35  ${1+5*2}   => 11 (was 12 in 0.7)
    36  ${4/2*5}   => 10 (was 10 in 0.7)
    37  ${(1+5)*2} => 12 (was 12 in 0.7)
    38  ```
    39  
    40  **Action:** Use parantheses where necessary to be explicit about ordering.
    41  
    42  ## Escaped Variables in Templates
    43  
    44  The `template_file` resource now requires that any variables specified
    45  in an inline `template` attribute are now escaped. This _does not affect_
    46  templates read from files either via `file()` or the `filename` attribute.
    47  
    48  Inline variables must be escaped using two dollar signs. `${foo}` turns into
    49  `$${foo}`.
    50  
    51  This is necessary so that Terraform doesn't try to interpolate the values
    52  before executing the template (for example using standard Terraform
    53  interpolations). In Terraform 0.7, we had special case handling to ignore
    54  templates, but this would cause confusion and poor error messages. Terraform
    55  0.8 requires explicitly escaping variables.
    56  
    57  **Behavior that no longer works in Terraform 0.8:**
    58  
    59  ```
    60  data "template_file" "foo" {
    61      template = "${foo}"
    62  
    63      vars { foo = "value" }
    64  }
    65  ```
    66  
    67  **Valid Terraform 0.8 template:**
    68  
    69  ```
    70  data "template_file" "foo" {
    71      template = "$${foo}"
    72  
    73      vars { foo = "value" }
    74  }
    75  ```
    76  
    77  **Action:** Escape variables in inline templates in `template_file` resources.
    78  
    79  ## Escape Sequences Within Interpolations
    80  
    81  Values within interpolations now only need to be escaped once.
    82  
    83  The exact behavior prior to 0.8 was inconsistent. In many cases, users
    84  just added `\` until it happened to work. The behavior is now consistent:
    85  single escape any values that need to be escaped.
    86  
    87  For example:
    88  
    89  ```
    90  ${replace(var.foo, "\\", "\\\\")}
    91  ```
    92  
    93  This will now replace `\` with `\\` throughout `var.foo`. Note that `\` and
    94  `\\` are escaped exactly once. Prior to 0.8, this required double the escape
    95  sequences to function properly.
    96  
    97  A less complicated example:
    98  
    99  ```
   100  ${replace(var.foo, "\n", "")}
   101  
   102  ```
   103  
   104  This does what you expect by replacing newlines with empty strings. Prior
   105  to 0.8, you'd have to specify `\\n`, which could be confusing.
   106  
   107  **Action:** Escape sequences within interpolations only need to be escaped
   108  once.
   109  
   110  ## New Internal Graphs
   111  
   112  The core graphs used to execute Terraform operations have been changed to
   113  support new features. These require no configuration changes and should work
   114  as normal.
   115  
   116  They were tested extensively during 0.7.x behind experimental
   117  flags and using the shadow graph. However, it is possible that there
   118  are still edge cases that aren't properly handled.
   119  
   120  While we believe it will be unlikely, if you find that something is not
   121  working properly, you may use the `-Xlegacy-graph` flag on any Terraform
   122  operation to use the old code path.
   123  
   124  This flag will be removed prior to 0.9 (the next major release after 0.8),
   125  so please report any issues that require this flag so we can make sure
   126  they become fixed.
   127  
   128  ~> **Warning:** Some features (such as `depends_on` referencing modules)
   129  do not work on the legacy graph code path. Specifically, any features
   130  introduced in Terraform 0.8 won't work with the legacy code path. These
   131  features will only work with the new, default graphs introduced with
   132  Terraform 0.8.