From 855b8da9716c52800fdda1d937af001474bad53f Mon Sep 17 00:00:00 2001
From: Aaron Lane <aarondrewlane@gmail.com>
Date: Tue, 2 Jul 2019 18:04:50 -0400
Subject: [PATCH] Add upgrading to v3.0 guide

---
 docs/upgrading_to_v3.0.md | 58 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 docs/upgrading_to_v3.0.md

diff --git a/docs/upgrading_to_v3.0.md b/docs/upgrading_to_v3.0.md
new file mode 100644
index 0000000000..6874f9c780
--- /dev/null
+++ b/docs/upgrading_to_v3.0.md
@@ -0,0 +1,58 @@
+# Upgrading to v3.0
+
+The v3.0 release of *kubernetes-engine* is a backwards incompatible
+release.
+
+## Migration Instructions
+
+### Beta Features
+
+Beta features are enabled on the `beta-public-cluster`
+submodule and the `beta-private-cluster` submodule.
+
+To migrate from the root module to the `beta-public-cluster` submodule,
+update a Terraform configuration like the following example:
+
+```diff
+module "kubernetes_engine_private_cluster" {
+-  source  = "terraform-google-modules/kubernetes-engine/google"
++  source  = "terraform-google-modules/kubernetes-engine/google//modules/beta-public-cluster"
+-  version = "~> 2.0"
++  version = "~> 3.0"
+
+  # ...
+```
+
+To migrate from the old `private-cluster` submodule to the new
+`beta-private-cluster` submodule, update a Terraform configuration
+like the following example:
+
+```diff
+module "kubernetes_engine_private_cluster" {
+-  source  = "terraform-google-modules/kubernetes-engine/google//modules/private-cluster"
++  source  = "terraform-google-modules/kubernetes-engine/google//modules/beta-private-cluster"
+-  version = "~> 2.0"
++  version = "~> 3.0"
+
+  # ...
+}
+```
+
+### IP Masqeurade
+
+In previous versions of this module, IP Masquerade was enabled if the
+network policy addon was enabled. IP Masquerade is now managed by an
+explicit toggle. To continue using IP Masquerade, update a Terraform
+configuration like the following example:
+
+```diff
+module "kubernetes_engine_private_cluster" {
+  source  = "terraform-google-modules/kubernetes-engine/google"
+-  version = "~> 2.0"
++  version = "~> 3.0"
+
++  configure_ip_masq = "true"
+  # ...
+}
+```
+