github.com/hs0210/hashicorp-terraform@v0.11.12-beta1/website/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 v0.8 is a major release and thus includes some backwards
    12  incompatibilities that you'll need to consider when upgrading. This guide is
    13  meant to help with 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/hashicorp/terraform/blob/master/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  ## Newlines in Strings
    23  
    24  Newlines are no longer allowed in strings unless it is a heredoc or an
    25  interpolation. This improves the performance of IDE syntax highlighting
    26  of Terraform configurations and simplifies parsing.
    27  
    28  **Behavior that no longer works in Terraform 0.8:**
    29  
    30  ```
    31  resource "null_resource" "foo" {
    32    value = "foo
    33  bar"
    34  }
    35  ```
    36  
    37  **Valid Terraform 0.8 configuration:**
    38  
    39  ```
    40  resource "null_resource" "foo" {
    41    value = "foo\nbar"
    42  
    43    value2 = <<EOF
    44  foo
    45  bar
    46  EOF
    47  
    48    # You can still have newlines within interpolations.
    49    value3 = "${lookup(
    50      var.foo, var.bar)}"
    51  }
    52  ```
    53  
    54  **Action:** Use heredocs or escape sequences when you have a string with newlines.
    55  
    56  ## Math Order of Operations
    57  
    58  Math operations now follow standard mathematical order of operations.
    59  Prior to 0.8, math ordering was simply left-to-right. With 0.8, `*`, `/`, and
    60  `%` are done before `+`, `-`.
    61  
    62  Some examples are shown below:
    63  
    64  ```
    65  ${1+5*2}   => 11 (was 12 in 0.7)
    66  ${4/2*5}   => 10 (was 10 in 0.7)
    67  ${(1+5)*2} => 12 (was 12 in 0.7)
    68  ```
    69  
    70  **Action:** Use parantheses where necessary to be explicit about ordering.
    71  
    72  ## Escaped Variables in Templates
    73  
    74  The `template_file` resource now requires that any variables specified
    75  in an inline `template` attribute are now escaped. This _does not affect_
    76  templates read from files either via `file()` or the `filename` attribute.
    77  
    78  Inline variables must be escaped using two dollar signs. `${foo}` turns into
    79  `$${foo}`.
    80  
    81  This is necessary so that Terraform doesn't try to interpolate the values
    82  before executing the template (for example using standard Terraform
    83  interpolations). In Terraform 0.7, we had special case handling to ignore
    84  templates, but this would cause confusion and poor error messages. Terraform
    85  0.8 requires explicitly escaping variables.
    86  
    87  **Behavior that no longer works in Terraform 0.8:**
    88  
    89  ```
    90  data "template_file" "foo" {
    91      template = "${foo}"
    92  
    93      vars { foo = "value" }
    94  }
    95  ```
    96  
    97  **Valid Terraform 0.8 template:**
    98  
    99  ```
   100  data "template_file" "foo" {
   101      template = "$${foo}"
   102  
   103      vars { foo = "value" }
   104  }
   105  ```
   106  
   107  **Action:** Escape variables in inline templates in `template_file` resources.
   108  
   109  ## Escape Sequences Within Interpolations
   110  
   111  Values within interpolations now only need to be escaped once.
   112  
   113  The exact behavior prior to 0.8 was inconsistent. In many cases, users
   114  just added `\` until it happened to work. The behavior is now consistent:
   115  single escape any values that need to be escaped.
   116  
   117  For example:
   118  
   119  ```
   120  ${replace(var.foo, "\\", "\\\\")}
   121  ```
   122  
   123  This will now replace `\` with `\\` throughout `var.foo`. Note that `\` and
   124  `\\` are escaped exactly once. Prior to 0.8, this required double the escape
   125  sequences to function properly.
   126  
   127  A less complicated example:
   128  
   129  ```
   130  ${replace(var.foo, "\n", "")}
   131  
   132  ```
   133  
   134  This does what you expect by replacing newlines with empty strings. Prior
   135  to 0.8, you'd have to specify `\\n`, which could be confusing.
   136  
   137  **Action:** Escape sequences within interpolations only need to be escaped
   138  once.
   139  
   140  ## New Internal Graphs
   141  
   142  The core graphs used to execute Terraform operations have been changed to
   143  support new features. These require no configuration changes and should work
   144  as normal.
   145  
   146  They were tested extensively during 0.7.x behind experimental
   147  flags and using the shadow graph. However, it is possible that there
   148  are still edge cases that aren't properly handled.
   149  
   150  While we believe it will be unlikely, if you find that something is not
   151  working properly, you may use the `-Xlegacy-graph` flag on any Terraform
   152  operation to use the old code path.
   153  
   154  This flag will be removed prior to 0.9 (the next major release after 0.8),
   155  so please report any issues that require this flag so we can make sure
   156  they become fixed.
   157  
   158  ~> **Warning:** Some features (such as `depends_on` referencing modules)
   159  do not work on the legacy graph code path. Specifically, any features
   160  introduced in Terraform 0.8 won't work with the legacy code path. These
   161  features will only work with the new, default graphs introduced with
   162  Terraform 0.8.