From 5fcfaffb9b080d22d2bb9c82db3946dffc41749b Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <mitchell.hashimoto@gmail.com>
Date: Tue, 14 Feb 2017 14:00:09 -0800
Subject: [PATCH] website: 0.9 upgrade guide

---
 website/source/layouts/downloads.erb          |  3 +
 .../source/upgrade-guides/0-9.html.markdown   | 74 +++++++++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 website/source/upgrade-guides/0-9.html.markdown

diff --git a/website/source/layouts/downloads.erb b/website/source/layouts/downloads.erb
index b1217b701..9e4eb2b36 100644
--- a/website/source/layouts/downloads.erb
+++ b/website/source/layouts/downloads.erb
@@ -9,6 +9,9 @@
 				<li<%= sidebar_current(/^upgrade-guides/) %>>
 				<a href="/upgrade-guides/index.html">Upgrade Guides</a>
 				<ul class="nav">
+					<li<%= sidebar_current("upgrade-guides-0-9") %>>
+					<a href="/upgrade-guides/0-9.html">Upgrading to v0.9</a>
+					</li>
 					<li<%= sidebar_current("upgrade-guides-0-8") %>>
 					<a href="/upgrade-guides/0-8.html">Upgrading to v0.8</a>
 					</li>
diff --git a/website/source/upgrade-guides/0-9.html.markdown b/website/source/upgrade-guides/0-9.html.markdown
new file mode 100644
index 000000000..8c5c53d4d
--- /dev/null
+++ b/website/source/upgrade-guides/0-9.html.markdown
@@ -0,0 +1,74 @@
+---
+layout: "downloads"
+page_title: "Upgrading to Terraform 0.9"
+sidebar_current: "upgrade-guides-0-9"
+description: |-
+  Upgrading to Terraform v0.9
+---
+
+# Upgrading to Terraform v0.9
+
+Terraform v0.9 is a major release and thus includes some changes 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.
+
+## Remote State
+
+Remote state has been overhauled to be easier and safer to configure and use.
+**The new changes are backwards compatible** with existing remote state and
+you'll be prompted to migrate to the new remote backend system.
+
+For extra safety when upgrading, you may backup your existing remote state
+by running `terraform remote pull` with 0.8.x and saving your
+`.terraform/terraform.tfstate` file somewhere safe. You must do this prior
+to upgrading to Terraform 0.9.
+
+The only non-backwards compatible change is in the CLI: the existing
+`terraform remote config` command is now gone. Remote state is now configured
+via the "backend" section within the Terraform configuration itself.
+
+**Example configuring a Consul remote backend:**
+
+```
+terraform {
+  backend "consul" {
+    address    = "demo.consul.io"
+    datacenter = "nyc3"
+    path       = "tfdemo"
+  }
+}
+```
+
+**Action:** Run `terraform init` to migrate your existing remote state.
+Update any scripts or guides that may have used `terraform remote config`
+to use the new file-based configuration.
+
+## State Locking
+
+Terraform 0.9 now will acquire a lock for your state if your backend
+supports it. **This change is backwards compatible**, but may require
+enhanced permissions for the authentication used with your backend.
+
+Backends that support locking as of the 0.9.0 release are: local files,
+Amazon S3, HashiCorp Consul, and Terraform Enterprise (atlas). If you don't
+use these backends, you can ignore this section.
+
+Specific notes for each affected backend:
+
+  * **Amazon S3**: DynamoDB is used for locking. The AWS access keys
+    must have access to Dynamo. You may disable locking by specifying
+	`lock = false` in your backend configuration.
+
+  * **HashiCorp Consul**: Sessions are used for locking. If an auth token
+    is used it must have permissions to create and destroy sessions. You
+	may disable locking by specifying `lock = false` in your backend
+	configuration.
+
+**Action:** Update your credentials or configuration if necessary.