Updated docs and migration script for v5.0.

Author: morgante

CHANGELOG.md

@@ -8,10 +8,15 @@ Extending the adopted spec, each change should have a link to its corresponding
 
 ## [Unreleased]
 
+## [v5.0.0] - 2019-XX-XX
+v5.0.0 is a backwards-incompatible release. Please see the [upgrading guide](./docs/upgrading_to_v5.0.md).
+
+The v5.0.0 module requires using the [2.12 version](https://github.com/terraform-providers/terraform-provider-google/blob/master/CHANGELOG.md#2120-august-01-2019) of the Google provider.
+
 ### Changed
 
-* All Beta functionality removed from non-beta clusters, some properties like node_pool taints available only in beta cluster now [#228]
 * **Breaking**: Enabled metadata-concealment by default [#248]
+* All beta functionality removed from non-beta clusters, moved `node_pool_taints` to beta modules [#228]
 
 ### Added
 * Added support for resource usage export config [#238]
@@ -22,6 +27,10 @@ Extending the adopted spec, each change should have a link to its corresponding
 * Support for Google Groups based RBAC beta feature [#217]
 * Support for disabling node pool autoscaling by setting `autoscaling` to `false` within the node pool variable. [#250]
 
+### Fixed
+
+* Fixed issue with passing a dynamically created Service Account to the module. [#27]
+
 ## [v4.1.0] 2019-07-24
 
 ### Added
@@ -164,7 +173,8 @@ Extending the adopted spec, each change should have a link to its corresponding
 
 * Initial release of module.
 
-[Unreleased]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/compare/v4.1.0...HEAD
+[Unreleased]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/compare/v5.0.0...HEAD
+[v5.0.0]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/compare/v4.1.0...v5.0.0
 [v4.1.0]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/compare/v4.0.0...v4.1.0
 [v4.0.0]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/compare/v3.0.0...v4.0.0
 [v3.0.0]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/compare/v2.1.0...v3.0.0
@@ -186,6 +196,7 @@ Extending the adopted spec, each change should have a link to its corresponding
 [#236]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/pull/236
 [#217]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/pull/217
 [#234]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/pull/234
+[#27]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/issues/27
 [#216]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/pull/216
 [#214]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/pull/214
 [#210]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/pull/210

docs/upgrading_to_v5.0.md

@@ -0,0 +1,71 @@
+# Upgrading to v5.0
+
+The v5.0 release of *kubernetes-engine* is a backwards incompatible
+release.
+
+## Migration Instructions
+
+### Node pool taints
+Previously, node pool taints could be set on all module versions.
+
+Now, to set taints you must use the beta version of the module.
+
+```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 = "~> 4.0"
++  version = "~> 5.0"
+ }
+```
+
+### Resource simplification
+The `google_container_cluster` and `google_container_node_pool` resources previously were different between regional and zonal clusters. They have now been collapsed into a single resource using the `location` variable.
+
+If you are using regional clusters, no migration is needed. If you are using zonal clusters, a state migration is needed. You can use a [script](../helpers/migrate.py) we provided to determine the required state changes:
+
+1. Download the script
+
+    ```
+    curl -O https://raw.githubusercontent.com/terraform-google-modules/terraform-google-kubernetes-engine/v5.0.0/helpers/migrate.py
+    chmod +x migrate.py
+    ```
+
+2. Execute the migration script
+
+    ```
+    ./migrate.py
+    ```
+
+    Output will be similar to the following:
+    ```
+    ---- Migrating the following modules:
+    -- module.gke-cluster-dev.module.gke
+    ---- Commands to run:
+    terraform state mv -state terraform.tfstate "module.gke-cluster-dev.module.gke.google_container_cluster.zonal_primary[0]" "module.gke-cluster-dev.module.gke.google_container_cluster.primary[0]"
+    terraform state mv "module.gke-cluster-dev.module.gke.google_container_node_pool.zonal_pools[0]" "module.gke-cluster-dev.module.gke.google_container_node_pool.pools[0]"
+    ```
+
+3. Execute the provided state migration commands (backups are automatically created).
+
+4. Run `terraform plan` to confirm no changes are expected.
+
+### Service Account creation
+
+Previously, if you explicitly specified a Service Account using the `service_account` variable on the module this was sufficient to force that Service Account to be used.
+
+Now, an additional `create_service_account` has been added with a default value of `true`. If you would like to use an explicitly created Service Account from outside the module, you will need to set `create_service_account` to `false` (in addition to passing in the Service Account email).
+
+No action is needed if you use the module's default service account.
+
+```diff
+ module "kubernetes_engine_private_cluster" {
+   source  = "terraform-google-modules/kubernetes-engine/google"
+-  version = "~> 4.0"
++  version = "~> 5.0"
+
+   service_account        = "[email protected]"
++  create_service_account = true
+   # ...
+ }
+```