website: v0.7 Upgrade Guide

website/source/layouts/downloads.erb

@@ -5,6 +5,14 @@
 				<li<%= sidebar_current("downloads-terraform") %>>
 				<a href="/downloads.html">Download Terraform</a>
 				</li>
+
+				<li<%= sidebar_current(/^upgrade-guides/) %>>
+				<a href="/upgrade-guides/index.html">Upgrade Guides</a>
+				<ul class="nav">
+					<li<%= sidebar_current("upgrade-guides-0-7") %>>
+					<a href="/upgrade-guides/0-7.html">Upgrading to v0.7</a>
+					</li>
+        </ul>
 			</ul>
 		</div>
 	<% end %>

website/source/upgrade-guides/0-7.html.markdown

@@ -0,0 +1,135 @@
+---
+layout: "downloads"
+page_title: "Upgrading to Terraform 0.7"
+sidebar_current: "upgrade-guides-0-7"
+description: |-
+  Upgrading to Terraform v0.7
+---
+
+# Upgrading to Terraform v0.7
+
+Terraform v0.7 is a major release, and thus includes some backwards incompatibilities that you'll need to consider when upgrading. This guide is meant to help with that process.
+
+The goal of this guide is to cover the most common upgrade concerns and issues that would benefit from more explanation and background. The exhaustive list of changes will always be the [Terraform Changelog](https://github.com/hashicorp/terraform/blob/master/CHANGELOG.md). After reviewing this guide, review the Changelog to check on specific notes about the resources and providers you use.
+
+## Plugin Binaries
+
+Before v0.7, Terraform's built-in plugins for providers and provisioners were each distributed as separate binaries.
+
+```
+terraform               # core binary
+terraform-provider-*    # provider plugins
+terraform-provisioner-* # provisioner plugins
+```
+
+These binaries needed to all be extracted to somewhere on your `$PATH` for Terraform to work.
+
+As of v0.7, these plugins all ship embedded in a single binary. This means that if you just extract the v0.7 archive into a path, you may still have the old separate binaries in your `$PATH`. You'll need to remove them manually.
+
+For example, if you keep Terraform binaries in `/usr/local/bin` you can clear out the old external binaries like this:
+
+```
+rm /usr/local/bin/terraform-*
+```
+
+External plugin binaries continue to work using the same pattern, but due to updates to the RPC protocol, they will need to be recompiled to be compatible with Terraform v0.7.
+
+## Maps in Displayed Plans
+
+When displaying a plan, Terraform now distinguishes attributes of type map by using a `%` character for the "length field".
+
+Here is an example showing a diff that includes both a list and a map:
+
+```
+somelist.#:  "0" => "1"
+somelist.0:  "" => "someitem"
+somemap.%:   "0" => "1"
+somemap.foo: "" => "bar"
+```
+
+## Interpolation Changes
+
+There are a few changes to Terraform's interpolation language that may require updates to your configs.
+
+### String Concatenation
+
+The `concat()` interpolation function used to work for both lists and strings. It now only works for lists.
+
+```
+"${concat(var.foo, "-suffix")}"     # => Error! No longer supported.
+```
+
+Instead, you can use nested interpolation braces for string concatenation.
+
+```
+"${"${var.foo}-suffix"}"
+```
+
+### Nested Quotes and Escaping
+
+Escaped quotes inside of interpolations were supported to retain backwards compatibility with older versions of Terraform that allowed them.
+
+Now, escaped quotes will no longer work in the interpolation context:
+
+```
+"${lookup(var.somemap, \"somekey\")}"      # => Syntax Error!
+```
+
+Instead, treat each set of interpolation braces (`${}`) as a new quoting context:
+
+```
+"${lookup(var.somemap, "somekey")}"
+```
+
+This allows double quote characters to be expressed properly within strings inside of interpolation expressions:
+
+```
+"${upper("\"quoted\"")}"    # => "QUOTED"
+```
+
+## Safer `terraform plan` Behavior
+
+Prior to v0.7, the `terraform plan` command had the potential to write updates to the state if changes were detected during the Refresh step (which happens by default during `plan`). Some configurations have metadata that changes which every read, so Refresh would always result in changes to the state, and therefore a write.
+
+In collaborative enviroments with shared remote state, this potential side effect of `plan` would cause unnecessary contention over the state, and potentially even interfere with active `apply` operations if they were happening simultaneously elsewhere.
+
+Terraform v0.7 addresses this by changing the Refresh process that is run during `terraform plan` to always be an in-memory only refresh. New state information detected during this step will not be persisted to permanent state storage.
+
+If the `-out` flag is used to produce a Plan File, the updated state information _will_ be encoded into that file, so that the resulting `terraform apply` operation can detect if any changes occurred that might invalidate the plan.
+
+For most users, this change will not affect your day-to-day usage of Terraform. For users with automation that relies on the old side effect of `plan`, you can use the `terraform refresh` command, which will still persist any changes it discovers.
+
+## Migrating to Data Sources
+
+With the addition of [Data Sources](/docs/configuration/data-sources.html), there are several resources that were acting as Data Sources that are now deprecated.
+
+ * `atlas_artifact`
+ * `template_file`
+ * `template_cloudinit_config`
+ * `tls_cert_request`
+
+Migrating to the equivalent Data Source is as simple as changing the `resource` keyword to `data` in your declaration and prepending `data.` to attribute references elsewhere in your config.
+
+For example, given a config like:
+
+```
+resource "template_file" "example" {
+  template = "someconfig"
+}
+resource "aws_instance" "example" {
+  user_data = "${template_file.example.rendered}"
+  # ...
+}
+```
+
+A config using the equivalent Data Source would look like this:
+
+```
+data "template_file" "example" {
+  template = "someconfig"
+}
+resource "aws_instance" "example" {
+  user_data = "${data.template_file.example.rendered}"
+  # ...
+}
+```

website/source/upgrade-guides/index.html.markdown

@@ -0,0 +1,13 @@
+---
+layout: "downloads"
+page_title: "Upgrade Guides"
+sidebar_current: "upgrade-guides"
+description: |-
+  Upgrade Guides
+---
+
+# Upgrade Guides
+
+Terraform's major releases can include an upgrade guide to help upgrading users
+walk through backwards compatibility issues and changes to expect. See the
+navigation for the available upgrade guides.