Add deprecation messages, upgrade guide for GKE subnetwork creation d…

…eprecation

third_party/terraform/resources/resource_container_cluster.go.erb

@@ -658,22 +658,25 @@ func resourceContainerCluster() *schema.Resource {
 				Elem: &schema.Resource{
 					Schema: map[string]*schema.Schema{
 						"use_ip_aliases": {
-							Type:     schema.TypeBool,
-							Optional: true,
-							Default:  true,
-							ForceNew: true,
+							Type:       schema.TypeBool,
+							Deprecated: "This field is being removed in 3.0.0. If set to true, remove it from your config. If false, remove ip_allocation_policy as a whole.",
+							Optional:   true,
+							Default:    true,
+							ForceNew:   true,
 						},
 
 						// GKE creates subnetwork automatically
 						"create_subnetwork": {
 							Type:          schema.TypeBool,
+							Deprecated:    "This field is being removed in 3.0.0. Define an explicit google_compute_subnetwork and use subnetwork instead.",
 							Optional:      true,
 							ForceNew:      true,
 							ConflictsWith: ipAllocationRangeFields,
 						},
 
    					"subnetwork_name": {
 							Type:          schema.TypeString,
+							Deprecated:    "This field is being removed in 3.0.0. Define an explicit google_compute_subnetwork and use subnetwork instead.",
 							Optional:      true,
 							ForceNew:      true,
 							ConflictsWith: ipAllocationRangeFields,
@@ -698,6 +701,7 @@ func resourceContainerCluster() *schema.Resource {
 						},
 						"node_ipv4_cidr_block": {
 							Type:          schema.TypeString,
+							Deprecated:    "This field is being removed in 3.0.0. Define an explicit google_compute_subnetwork and use subnetwork instead.",
 							Optional:      true,
 							Computed:      true,
 							ForceNew:      true,

third_party/terraform/website/docs/version_3_upgrade.html.markdown

@@ -93,6 +93,95 @@ provider "google" {
 
 ## Resource: `google_container_cluster`
 
+### Automatic subnetwork creation for VPC-native clusters removed
+
+Automatic creation of subnetworks in GKE has been removed. Now, users of
+VPC-native clusters will always need to provide a `google_compute_subnetwork`
+resource to use `ip_allocation_policy`. Routes-based clusters are unaffected.
+
+Representing resources managed by another source in Terraform is painful, and
+leads to confusing patterns that often involve unnecessarily recreating user
+resources. A number of fields in GKE are dedicated to a feature that allows
+users to create a GKE-managed subnetwork.
+
+This is a great fit for an imperative tool like `gcloud`, but with Terraform
+it's relatively easy to specify a subnetwork in config alongside the cluster.
+Not only is it more explicit, it allows the subnetwork to be repurposed or
+persist through cluster deletion.
+
+Particularly, Shared VPC was incompatible with `create_subnetwork`, and
+`node_ipv4_cidr` was easy to confuse with
+`ip_allocation_policy.node_ipv4_cidr_block`.
+
+#### Detailed changes:
+
+* `ip_allocation_policy.node_ipv4_cidr_block` removed (This controls the primary range of the created subnetwork)
+* `ip_allocation_policy.create_subnetwork`, `ip_allocation_policy.subnetwork_name` removed
+* `ip_allocation_policy.use_ip_aliases` removed
+  * Enablement is now based on `ip_allocation_policy` being defined instead
+* Conflict added between `node_ipv4_cidr`, `ip_allocation_policy`
+
+#### Upgrade instructions
+
+1. Remove the removed fields from `google_container_cluster`
+1. Add a `google_compute_subnetwork` to your config, import it using `terraform import`
+1. Reference the subnetwork using the `subnetwork` field on your `google_container_cluster`
+
+#### Old Config
+
+```hcl
+resource "google_compute_network" "container_network" {
+  name                    = "container-network"
+  auto_create_subnetworks = false
+}
+
+resource "google_container_cluster" "primary" {
+  name       = "my-cluster"
+  location   = "us-central1"
+  network    = "${google_compute_network.container_network.name}"
+
+  initial_node_count = 1
+
+  ip_allocation_policy {
+    use_ip_aliases           = true
+    create_subnetwork        = true
+    cluster_ipv4_cidr_block  = "10.0.0.0/16"
+    services_ipv4_cidr_block = "10.1.0.0/16"
+    node_ipv4_cidr_block     = "10.2.0.0/16"
+  }
+}
+```
+
+#### New Config
+
+```hcl
+resource "google_compute_network" "container_network" {
+  name                    = "container-network"
+  auto_create_subnetworks = false
+}
+
+resource "google_compute_subnetwork" "container_subnetwork" {
+  name          = "container-subnetwork"
+  ip_cidr_range = "10.2.0.0/16"
+  region        = "us-central1"
+  network       = "${google_compute_network.container_network.self_link}"
+}
+
+resource "google_container_cluster" "primary" {
+  name       = "my-cluster"
+  location   = "us-central1"
+  network    = "${google_compute_network.container_network.name}"
+  subnetwork = "${google_compute_subnetwork.container_subnetwork.name}"
+
+  initial_node_count = 1
+
+   ip_allocation_policy {
+     cluster_ipv4_cidr_block  = "10.0.0.0/16"
+     services_ipv4_cidr_block = "10.1.0.0/16"
+   }
+}
+```
+
 ### `logging_service` and `monitoring_service` defaults changed
 
 GKE Stackdriver Monitoring (the GKE-specific Stackdriver experience) is now