diff --git a/website/source/layouts/downloads.erb b/website/source/layouts/downloads.erb
index 27b73b0fa..b1217b701 100644
--- a/website/source/layouts/downloads.erb
+++ b/website/source/layouts/downloads.erb
@@ -9,6 +9,9 @@
>
Upgrade Guides
+ - >
+ Upgrading to v0.8
+
- >
Upgrading to v0.7
diff --git a/website/source/upgrade-guides/0-8.html.markdown b/website/source/upgrade-guides/0-8.html.markdown
new file mode 100644
index 000000000..1292e803d
--- /dev/null
+++ b/website/source/upgrade-guides/0-8.html.markdown
@@ -0,0 +1,132 @@
+---
+layout: "downloads"
+page_title: "Upgrading to Terraform 0.8"
+sidebar_current: "upgrade-guides-0-8"
+description: |-
+ Upgrading to Terraform v0.8
+---
+
+# Upgrading to Terraform v0.8
+
+~> **Terraform 0.8 is still a release candidate.** The final stable version
+ has not been released yet. This upgrade guide may still change between now and
+ the final version.
+
+Terraform v0.8 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, we recommend reviewing the Changelog to check on
+specific notes about the resources and providers you use.
+
+## Math Order of Operations
+
+Math operations now follow standard mathematical order of operations.
+Prior to 0.8, math ordering was simply left-to-right. With 0.8, `*`, `/`, and
+`%` are done before `+`, `-`.
+
+Some examples are shown below:
+
+```
+${1+5*2} => 11 (was 12 in 0.7)
+${4/2*5} => 10 (was 10 in 0.7)
+${(1+5)*2} => 12 (was 12 in 0.7)
+```
+
+**Action:** Use parantheses where necessary to be explicit about ordering.
+
+## Escaped Variables in Templates
+
+The `template_file` resource now requires that any variables specified
+in an inline `template` attribute are now escaped. This _does not affect_
+templates read from files either via `file()` or the `filename` attribute.
+
+Inline variables must be escaped using two dollar signs. `${foo}` turns into
+`$${foo}`.
+
+This is necessary so that Terraform doesn't try to interpolate the values
+before executing the template (for example using standard Terraform
+interpolations). In Terraform 0.7, we had special case handling to ignore
+templates, but this would cause confusion and poor error messages. Terraform
+0.8 requires explicitly escaping variables.
+
+**Behavior that no longer works in Terraform 0.8:**
+
+```
+data "template_file" "foo" {
+ template = "${foo}"
+
+ vars { foo = "value" }
+}
+```
+
+**Valid Terraform 0.8 template:**
+
+```
+data "template_file" "foo" {
+ template = "$${foo}"
+
+ vars { foo = "value" }
+}
+```
+
+**Action:** Escape variables in inline templates in `template_file` resources.
+
+## Escape Sequences Within Interpolations
+
+Values within interpolations now only need to be escaped once.
+
+The exact behavior prior to 0.8 was inconsistent. In many cases, users
+just added `\` until it happened to work. The behavior is now consistent:
+single escape any values that need to be escaped.
+
+For example:
+
+```
+${replace(var.foo, "\\", "\\\\")}
+```
+
+This will now replace `\` with `\\` throughout `var.foo`. Note that `\` and
+`\\` are escaped exactly once. Prior to 0.8, this required double the escape
+sequences to function properly.
+
+A less complicated example:
+
+```
+${replace(var.foo, "\n", "")}
+
+```
+
+This does what you expect by replacing newlines with empty strings. Prior
+to 0.8, you'd have to specify `\\n`, which could be confusing.
+
+**Action:** Escape sequences within interpolations only need to be escaped
+once.
+
+## New Internal Graphs
+
+The core graphs used to execute Terraform operations have been changed to
+support new features. These require no configuration changes and should work
+as normal.
+
+They were tested extensively during 0.7.x behind experimental
+flags and using the shadow graph. However, it is possible that there
+are still edge cases that aren't properly handled.
+
+While we believe it will be unlikely, if you find that something is not
+working properly, you may use the `-Xlegacy-graph` flag on any Terraform
+operation to use the old code path.
+
+This flag will be removed prior to 0.9 (the next major release after 0.8),
+so please report any issues that require this flag so we can make sure
+they become fixed.
+
+~> **Warning:** Some features (such as `depends_on` referencing modules)
+do not work on the legacy graph code path. Specifically, any features
+introduced in Terraform 0.8 won't work with the legacy code path. These
+features will only work with the new, default graphs introduced with
+Terraform 0.8.