From 5ac384ee93d35515f4200d927632537a95fd7986 Mon Sep 17 00:00:00 2001
From: Aaron Lane <aarondrewlane@gmail.com>
Date: Tue, 2 Jul 2019 18:04:50 -0400
Subject: [PATCH 01/14] 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"
+  # ...
+}
+```
+

From fffd21c440b49290889b9d9473301b7663e91729 Mon Sep 17 00:00:00 2001
From: Aaron Lane <aarondrewlane@gmail.com>
Date: Tue, 2 Jul 2019 18:07:34 -0400
Subject: [PATCH 02/14] [skip ci] Add CHANGELOG entry for 3.0.0

---
 CHANGELOG.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4f8b1fd3b0..8a62d3ebc5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,8 @@ Extending the adopted spec, each change should have a link to its corresponding
 
 ## [Unreleased]
 
+## [v3.0.0] - 2019-07-ZZ
+
 ### Added
 
 * Add configuration flag for enable BinAuthZ Admission controller [#160] [#188]
@@ -131,7 +133,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/v2.1.0...HEAD
+[Unreleased]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/compare/v3.0.0...HEAD
+[v3.0.0]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/compare/v2.1.0...v3.0.0
 [v2.1.0]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/compare/v2.0.1...v2.1.0
 [v2.0.1]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/compare/v2.0.0...v2.0.1
 [v2.0.0]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/compare/v1.0.1...v2.0.0

From 5e2b268516699b0f809ce8bb8be191816fd9e020 Mon Sep 17 00:00:00 2001
From: Aaron Lane <aarondrewlane@gmail.com>
Date: Tue, 2 Jul 2019 18:11:11 -0400
Subject: [PATCH 03/14] [skip ci] Adjust spacing in diff examples

---
 docs/upgrading_to_v3.0.md | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/docs/upgrading_to_v3.0.md b/docs/upgrading_to_v3.0.md
index 6874f9c780..8e19003f05 100644
--- a/docs/upgrading_to_v3.0.md
+++ b/docs/upgrading_to_v3.0.md
@@ -14,13 +14,14 @@ 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" {
+ 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
@@ -28,14 +29,14 @@ To migrate from the old `private-cluster` submodule to the new
 like the following example:
 
 ```diff
-module "kubernetes_engine_private_cluster" {
+ 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
@@ -46,13 +47,13 @@ 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"
+ module "kubernetes_engine_private_cluster" {
+   source  = "terraform-google-modules/kubernetes-engine/google"
 -  version = "~> 2.0"
 +  version = "~> 3.0"
 
 +  configure_ip_masq = "true"
-  # ...
-}
+   # ...
+ }
 ```
 

From c4245031032e151f5de2e5f0d5687c7dbb597679 Mon Sep 17 00:00:00 2001
From: Aaron Lane <aarondrewlane@gmail.com>
Date: Thu, 4 Jul 2019 11:39:41 -0400
Subject: [PATCH 04/14] Add CHANGELOG entry for #203

---
 CHANGELOG.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8a62d3ebc5..892087843a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,7 +18,7 @@ Extending the adopted spec, each change should have a link to its corresponding
 * Support to scale the default node cluster. [#149]
 * Support for configuring the network policy provider. [#159]
 * Support for database encryption. [#165]
-* Submodules for public and private clusters with beta features. [#124] [#188]
+* Submodules for public and private clusters with beta features. [#124] [#188] [#203]
 * Support for configuring cluster IPv4 CIDRs. [#193]
 * Support for configuring IP Masquerade. [#187]
 * Support for v2.9 of the Google providers. [#198]
@@ -145,6 +145,7 @@ Extending the adopted spec, each change should have a link to its corresponding
 [v0.3.0]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/compare/v0.2.0...v0.3.0
 [v0.2.0]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/compare/v0.1.0...v0.2.0
 
+[#203]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/pull/203
 [#198]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/pull/198
 [#197]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/pull/197
 [#193]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/pull/193

From b0d96536a7337eddacec215cbe08b1e49f0cfd3b Mon Sep 17 00:00:00 2001
From: Marko Vlahovic <vlahovic@google.com>
Date: Fri, 5 Jul 2019 16:03:13 -0700
Subject: [PATCH 05/14] Adding support for upstream_nameservers

---
 .kitchen.yml                                  | 14 +++
 README.md                                     |  1 +
 autogen/dns.tf                                | 49 +++++++++-
 autogen/main.tf                               |  1 +
 autogen/variables.tf                          |  6 ++
 dns.tf                                        | 49 +++++++++-
 examples/stub_domains_private/main.tf         |  2 +-
 .../README.md                                 | 50 ++++++++++
 .../stub_domains_upstream_nameservers/main.tf | 60 ++++++++++++
 .../outputs.tf                                | 34 +++++++
 .../test_outputs.tf                           | 63 +++++++++++++
 .../variables.tf                              | 48 ++++++++++
 examples/upstream_nameservers/README.md       | 50 ++++++++++
 examples/upstream_nameservers/main.tf         | 47 ++++++++++
 examples/upstream_nameservers/outputs.tf      | 34 +++++++
 examples/upstream_nameservers/test_outputs.tf | 63 +++++++++++++
 examples/upstream_nameservers/variables.tf    | 48 ++++++++++
 main.tf                                       |  1 +
 modules/beta-private-cluster/README.md        |  1 +
 modules/beta-private-cluster/dns.tf           | 49 +++++++++-
 modules/beta-private-cluster/main.tf          |  1 +
 modules/beta-private-cluster/variables.tf     |  6 ++
 modules/beta-public-cluster/README.md         |  1 +
 modules/beta-public-cluster/dns.tf            | 49 +++++++++-
 modules/beta-public-cluster/main.tf           |  1 +
 modules/beta-public-cluster/variables.tf      |  6 ++
 modules/private-cluster/README.md             |  1 +
 modules/private-cluster/dns.tf                | 49 +++++++++-
 modules/private-cluster/main.tf               |  1 +
 modules/private-cluster/variables.tf          |  6 ++
 .../stub_domains_private/terraform.tfvars     |  1 +
 .../example.tf                                | 28 ++++++
 .../network.tf                                | 47 ++++++++++
 .../outputs.tf                                |  1 +
 .../terraform.tfvars                          |  1 +
 .../variables.tf                              |  1 +
 test/fixtures/upstream_nameservers/example.tf | 28 ++++++
 test/fixtures/upstream_nameservers/network.tf | 47 ++++++++++
 test/fixtures/upstream_nameservers/outputs.tf |  1 +
 .../upstream_nameservers/terraform.tfvars     |  1 +
 .../upstream_nameservers/variables.tf         |  1 +
 .../controls/gcloud.rb                        | 50 ++++++++++
 .../controls/kubectl.rb                       | 92 +++++++++++++++++++
 .../inspec.yml                                | 20 ++++
 .../upstream_nameservers/controls/gcloud.rb   | 50 ++++++++++
 .../upstream_nameservers/controls/kubectl.rb  | 79 ++++++++++++++++
 .../upstream_nameservers/inspec.yml           | 20 ++++
 variables.tf                                  |  6 ++
 48 files changed, 1254 insertions(+), 11 deletions(-)
 create mode 100644 examples/stub_domains_upstream_nameservers/README.md
 create mode 100644 examples/stub_domains_upstream_nameservers/main.tf
 create mode 100644 examples/stub_domains_upstream_nameservers/outputs.tf
 create mode 100644 examples/stub_domains_upstream_nameservers/test_outputs.tf
 create mode 100644 examples/stub_domains_upstream_nameservers/variables.tf
 create mode 100644 examples/upstream_nameservers/README.md
 create mode 100644 examples/upstream_nameservers/main.tf
 create mode 100644 examples/upstream_nameservers/outputs.tf
 create mode 100644 examples/upstream_nameservers/test_outputs.tf
 create mode 100644 examples/upstream_nameservers/variables.tf
 create mode 120000 test/fixtures/stub_domains_private/terraform.tfvars
 create mode 100644 test/fixtures/stub_domains_upstream_nameservers/example.tf
 create mode 100644 test/fixtures/stub_domains_upstream_nameservers/network.tf
 create mode 120000 test/fixtures/stub_domains_upstream_nameservers/outputs.tf
 create mode 120000 test/fixtures/stub_domains_upstream_nameservers/terraform.tfvars
 create mode 120000 test/fixtures/stub_domains_upstream_nameservers/variables.tf
 create mode 100644 test/fixtures/upstream_nameservers/example.tf
 create mode 100644 test/fixtures/upstream_nameservers/network.tf
 create mode 120000 test/fixtures/upstream_nameservers/outputs.tf
 create mode 120000 test/fixtures/upstream_nameservers/terraform.tfvars
 create mode 120000 test/fixtures/upstream_nameservers/variables.tf
 create mode 100644 test/integration/stub_domains_upstream_nameservers/controls/gcloud.rb
 create mode 100644 test/integration/stub_domains_upstream_nameservers/controls/kubectl.rb
 create mode 100644 test/integration/stub_domains_upstream_nameservers/inspec.yml
 create mode 100644 test/integration/upstream_nameservers/controls/gcloud.rb
 create mode 100644 test/integration/upstream_nameservers/controls/kubectl.rb
 create mode 100644 test/integration/upstream_nameservers/inspec.yml

diff --git a/.kitchen.yml b/.kitchen.yml
index da159806dc..6bf414c21f 100644
--- a/.kitchen.yml
+++ b/.kitchen.yml
@@ -104,6 +104,20 @@ suites:
       systems:
         - name: stub_domains_private
           backend: local
+  - name: "upstream_nameservers"
+    driver:
+      root_module_directory: test/fixtures/upstream_nameservers
+    verifier:
+        systems:
+          - name: upstream_nameservers
+            backend: local
+  - name: "stub_domains_upstream_nameservers"
+    driver:
+      root_module_directory: test/fixtures/stub_domains_upstream_nameservers
+    verifier:
+        systems:
+          - name: stub_domains_upstream_nameservers
+            backend: local
   - name: "workload_metadata_config"
     driver:
       root_module_directory: test/fixtures/workload_metadata_config
diff --git a/README.md b/README.md
index 1d068e03ab..c3ec7bc284 100644
--- a/README.md
+++ b/README.md
@@ -154,6 +154,7 @@ In either case, upgrading to module version `v1.0.0` will trigger a recreation o
 | service\_account | The service account to run nodes as if not overridden in `node_pools`. The default value will cause a cluster-specific service account to be created. | string | `"create"` | no |
 | stub\_domains | Map of stub domains and their resolvers to forward DNS queries for a certain domain to an external DNS server | map | `<map>` | no |
 | subnetwork | The subnetwork to host the cluster in (required) | string | n/a | yes |
+| upstream\_nameservers | If specified, the values replace the nameservers taken by default from the node’s /etc/resolv.conf | list | `<list>` | no |
 | zones | The zones to host the cluster in (optional if regional cluster / required if zonal) | list | `<list>` | no |
 
 ## Outputs
diff --git a/autogen/dns.tf b/autogen/dns.tf
index 1b0d83eb23..43f1a24a2e 100644
--- a/autogen/dns.tf
+++ b/autogen/dns.tf
@@ -20,7 +20,7 @@
   Delete default kube-dns configmap
  *****************************************/
 resource "null_resource" "delete_default_kube_dns_configmap" {
-  count = "${local.custom_kube_dns_config ? 1 : 0}"
+  count = "${local.custom_kube_dns_config || local.upstream_nameservers_config ? 1 : 0}"
 
   provisioner "local-exec" {
     command = "${path.module}/scripts/kubectl_wrapper.sh https://${local.cluster_endpoint} ${data.google_client_config.default.access_token} ${local.cluster_ca_certificate} ${path.module}/scripts/delete-default-resource.sh kube-system configmap kube-dns"
@@ -33,7 +33,7 @@ resource "null_resource" "delete_default_kube_dns_configmap" {
   Create kube-dns confimap
  *****************************************/
 resource "kubernetes_config_map" "kube-dns" {
-  count = "${local.custom_kube_dns_config ? 1 : 0}"
+  count = "${local.custom_kube_dns_config && !local.upstream_nameservers_config ? 1 : 0}"
 
   metadata {
     name      = "kube-dns"
@@ -52,3 +52,48 @@ EOF
 
   depends_on = ["null_resource.delete_default_kube_dns_configmap", "data.google_client_config.default", "google_container_cluster.primary", "google_container_node_pool.pools", "google_container_cluster.zonal_primary", "google_container_node_pool.zonal_pools"]
 }
+
+resource "kubernetes_config_map" "kube-dns-upstream-namservers" {
+  count = "${!local.custom_kube_dns_config && local.upstream_nameservers_config ? 1 : 0}"
+
+  metadata {
+    name      = "kube-dns"
+    namespace = "kube-system"
+
+    labels {
+      maintained_by = "terraform"
+    }
+  }
+
+  data {
+    upstreamNameservers = <<EOF
+${jsonencode(var.upstream_nameservers)}
+EOF
+  }
+
+  depends_on = ["null_resource.delete_default_kube_dns_configmap", "data.google_client_config.default", "google_container_cluster.primary", "google_container_node_pool.pools", "google_container_cluster.zonal_primary", "google_container_node_pool.zonal_pools"]
+}
+
+resource "kubernetes_config_map" "kube-dns-upstream-nameservers-and-stub-domains" {
+  count = "${local.custom_kube_dns_config && local.upstream_nameservers_config ? 1 : 0}"
+
+  metadata {
+    name      = "kube-dns"
+    namespace = "kube-system"
+
+    labels {
+      maintained_by = "terraform"
+    }
+  }
+
+  data {
+    upstreamNameservers = <<EOF
+${jsonencode(var.upstream_nameservers)}
+EOF
+    stubDomains = <<EOF
+${jsonencode(var.stub_domains)}
+EOF
+  }
+
+  depends_on = ["null_resource.delete_default_kube_dns_configmap", "data.google_client_config.default", "google_container_cluster.primary", "google_container_node_pool.pools", "google_container_cluster.zonal_primary", "google_container_node_pool.zonal_pools"]
+}
diff --git a/autogen/main.tf b/autogen/main.tf
index 690658f3b4..9a6c4229a4 100644
--- a/autogen/main.tf
+++ b/autogen/main.tf
@@ -36,6 +36,7 @@ locals {
   node_version_regional       = "${var.node_version != "" && var.regional ? var.node_version : local.kubernetes_version_regional}"
   node_version_zonal          = "${var.node_version != "" && !var.regional ? var.node_version : local.kubernetes_version_zonal}"
   custom_kube_dns_config      = "${length(keys(var.stub_domains)) > 0 ? true : false}"
+  upstream_nameservers_config = "${length(var.upstream_nameservers) > 0 ? true : false}"
   network_project_id          = "${var.network_project_id != "" ? var.network_project_id : var.project_id}"
 
   cluster_type = "${var.regional ? "regional" : "zonal"}"
diff --git a/autogen/variables.tf b/autogen/variables.tf
index 98264daf9e..42d2c82312 100644
--- a/autogen/variables.tf
+++ b/autogen/variables.tf
@@ -206,6 +206,12 @@ variable "stub_domains" {
   default     = {}
 }
 
+variable "upstream_nameservers" {
+  type        = "list"
+  description = "If specified, the values replace the nameservers taken by default from the node’s /etc/resolv.conf"
+  default     = []
+}
+
 variable "non_masquerade_cidrs" {
   type        = "list"
   description = "List of strings in CIDR notation that specify the IP address ranges that do not use IP masquerading."
diff --git a/dns.tf b/dns.tf
index 25effe580a..1cd73830bc 100644
--- a/dns.tf
+++ b/dns.tf
@@ -20,7 +20,7 @@
   Delete default kube-dns configmap
  *****************************************/
 resource "null_resource" "delete_default_kube_dns_configmap" {
-  count = "${local.custom_kube_dns_config ? 1 : 0}"
+  count = "${local.custom_kube_dns_config || local.upstream_nameservers_config ? 1 : 0}"
 
   provisioner "local-exec" {
     command = "${path.module}/scripts/kubectl_wrapper.sh https://${local.cluster_endpoint} ${data.google_client_config.default.access_token} ${local.cluster_ca_certificate} ${path.module}/scripts/delete-default-resource.sh kube-system configmap kube-dns"
@@ -33,7 +33,7 @@ resource "null_resource" "delete_default_kube_dns_configmap" {
   Create kube-dns confimap
  *****************************************/
 resource "kubernetes_config_map" "kube-dns" {
-  count = "${local.custom_kube_dns_config ? 1 : 0}"
+  count = "${local.custom_kube_dns_config && !local.upstream_nameservers_config ? 1 : 0}"
 
   metadata {
     name      = "kube-dns"
@@ -52,3 +52,48 @@ EOF
 
   depends_on = ["null_resource.delete_default_kube_dns_configmap", "data.google_client_config.default", "google_container_cluster.primary", "google_container_node_pool.pools", "google_container_cluster.zonal_primary", "google_container_node_pool.zonal_pools"]
 }
+
+resource "kubernetes_config_map" "kube-dns-upstream-namservers" {
+  count = "${!local.custom_kube_dns_config && local.upstream_nameservers_config ? 1 : 0}"
+
+  metadata {
+    name      = "kube-dns"
+    namespace = "kube-system"
+
+    labels {
+      maintained_by = "terraform"
+    }
+  }
+
+  data {
+    upstreamNameservers = <<EOF
+${jsonencode(var.upstream_nameservers)}
+EOF
+  }
+
+  depends_on = ["null_resource.delete_default_kube_dns_configmap", "data.google_client_config.default", "google_container_cluster.primary", "google_container_node_pool.pools", "google_container_cluster.zonal_primary", "google_container_node_pool.zonal_pools"]
+}
+
+resource "kubernetes_config_map" "kube-dns-upstream-nameservers-and-stub-domains" {
+  count = "${local.custom_kube_dns_config && local.upstream_nameservers_config ? 1 : 0}"
+
+  metadata {
+    name      = "kube-dns"
+    namespace = "kube-system"
+
+    labels {
+      maintained_by = "terraform"
+    }
+  }
+
+  data {
+    upstreamNameservers = <<EOF
+${jsonencode(var.upstream_nameservers)}
+EOF
+    stubDomains = <<EOF
+${jsonencode(var.stub_domains)}
+EOF
+  }
+
+  depends_on = ["null_resource.delete_default_kube_dns_configmap", "data.google_client_config.default", "google_container_cluster.primary", "google_container_node_pool.pools", "google_container_cluster.zonal_primary", "google_container_node_pool.zonal_pools"]
+}
diff --git a/examples/stub_domains_private/main.tf b/examples/stub_domains_private/main.tf
index 9369a572d4..54fe5b35ca 100644
--- a/examples/stub_domains_private/main.tf
+++ b/examples/stub_domains_private/main.tf
@@ -15,7 +15,7 @@
  */
 
 provider "google-beta" {
-  version = "~> 2.2"
+  version = "~> 2.9.0"
   region  = "${var.region}"
 }
 
diff --git a/examples/stub_domains_upstream_nameservers/README.md b/examples/stub_domains_upstream_nameservers/README.md
new file mode 100644
index 0000000000..5448cc812b
--- /dev/null
+++ b/examples/stub_domains_upstream_nameservers/README.md
@@ -0,0 +1,50 @@
+# Stub Domains and Upstream Nameservers Cluster
+
+This example illustrates how to create a cluster that adds custom stub domains and custom upstream nameservers to kube-dns.
+
+It will:
+- Create a cluster
+- Remove the default kube-dns configmap
+- Add a new kube-dns configmap with custom stub domains and upstream nameservers
+
+[^]: (autogen_docs_start)
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-----:|:-----:|
+| cluster\_name\_suffix | A suffix to append to the default cluster name | string | `""` | no |
+| compute\_engine\_service\_account | Service account to associate to the nodes in the cluster | string | n/a | yes |
+| ip\_range\_pods | The secondary ip range to use for pods | string | n/a | yes |
+| ip\_range\_services | The secondary ip range to use for pods | string | n/a | yes |
+| network | The VPC network to host the cluster in | string | n/a | yes |
+| project\_id | The project ID to host the cluster in | string | n/a | yes |
+| region | The region to host the cluster in | string | n/a | yes |
+| subnetwork | The subnetwork to host the cluster in | string | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| ca\_certificate |  |
+| client\_token |  |
+| cluster\_name | Cluster name |
+| ip\_range\_pods | The secondary IP range used for pods |
+| ip\_range\_services | The secondary IP range used for services |
+| kubernetes\_endpoint |  |
+| location |  |
+| master\_kubernetes\_version | The master Kubernetes version |
+| network |  |
+| project\_id |  |
+| region |  |
+| service\_account | The service account to default running nodes as if not overridden in `node_pools`. |
+| subnetwork |  |
+| zones | List of zones in which the cluster resides |
+
+[^]: (autogen_docs_end)
+
+To provision this example, run the following from within this directory:
+- `terraform init` to get the plugins
+- `terraform plan` to see the infrastructure plan
+- `terraform apply` to apply the infrastructure build
+- `terraform destroy` to destroy the built infrastructure
diff --git a/examples/stub_domains_upstream_nameservers/main.tf b/examples/stub_domains_upstream_nameservers/main.tf
new file mode 100644
index 0000000000..3915ee45e7
--- /dev/null
+++ b/examples/stub_domains_upstream_nameservers/main.tf
@@ -0,0 +1,60 @@
+/**
+ * Copyright 2018 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+locals {
+  cluster_type = "domains-nameservers"
+}
+
+provider "google" {
+  version = "~> 2.9.0"
+  region  = "${var.region}"
+}
+
+provider "google-beta" {
+  version = "~> 2.9.0"
+  region  = "${var.region}"
+}
+
+module "gke" {
+  source            = "../../"
+  project_id        = "${var.project_id}"
+  name              = "${local.cluster_type}-cluster${var.cluster_name_suffix}"
+  region            = "${var.region}"
+  network           = "${var.network}"
+  subnetwork        = "${var.subnetwork}"
+  ip_range_pods     = "${var.ip_range_pods}"
+  ip_range_services = "${var.ip_range_services}"
+  network_policy    = true
+  service_account   = "${var.compute_engine_service_account}"
+
+  configure_ip_masq = true
+
+  stub_domains {
+    "example.com" = [
+      "10.254.154.11",
+      "10.254.154.12",
+    ]
+
+    "example.net" = [
+      "10.254.154.11",
+      "10.254.154.12",
+    ]
+  }
+
+  upstream_nameservers = ["8.8.8.8", "8.8.4.4"]
+}
+
+data "google_client_config" "default" {}
diff --git a/examples/stub_domains_upstream_nameservers/outputs.tf b/examples/stub_domains_upstream_nameservers/outputs.tf
new file mode 100644
index 0000000000..9881585a48
--- /dev/null
+++ b/examples/stub_domains_upstream_nameservers/outputs.tf
@@ -0,0 +1,34 @@
+/**
+ * Copyright 2018 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+output "kubernetes_endpoint" {
+  sensitive = true
+  value     = "${module.gke.endpoint}"
+}
+
+output "client_token" {
+  sensitive = true
+  value     = "${base64encode(data.google_client_config.default.access_token)}"
+}
+
+output "ca_certificate" {
+  value = "${module.gke.ca_certificate}"
+}
+
+output "service_account" {
+  description = "The service account to default running nodes as if not overridden in `node_pools`."
+  value       = "${module.gke.service_account}"
+}
diff --git a/examples/stub_domains_upstream_nameservers/test_outputs.tf b/examples/stub_domains_upstream_nameservers/test_outputs.tf
new file mode 100644
index 0000000000..c1d4352219
--- /dev/null
+++ b/examples/stub_domains_upstream_nameservers/test_outputs.tf
@@ -0,0 +1,63 @@
+/**
+ * Copyright 2018 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// These outputs are used to test the module with kitchen-terraform
+// They do not need to be included in real-world uses of this module
+
+output "project_id" {
+  value = "${var.project_id}"
+}
+
+output "region" {
+  value = "${module.gke.region}"
+}
+
+output "cluster_name" {
+  description = "Cluster name"
+  value       = "${module.gke.name}"
+}
+
+output "network" {
+  value = "${var.network}"
+}
+
+output "subnetwork" {
+  value = "${var.subnetwork}"
+}
+
+output "location" {
+  value = "${module.gke.location}"
+}
+
+output "ip_range_pods" {
+  description = "The secondary IP range used for pods"
+  value       = "${var.ip_range_pods}"
+}
+
+output "ip_range_services" {
+  description = "The secondary IP range used for services"
+  value       = "${var.ip_range_services}"
+}
+
+output "zones" {
+  description = "List of zones in which the cluster resides"
+  value       = "${module.gke.zones}"
+}
+
+output "master_kubernetes_version" {
+  description = "The master Kubernetes version"
+  value       = "${module.gke.master_version}"
+}
diff --git a/examples/stub_domains_upstream_nameservers/variables.tf b/examples/stub_domains_upstream_nameservers/variables.tf
new file mode 100644
index 0000000000..a4409795b7
--- /dev/null
+++ b/examples/stub_domains_upstream_nameservers/variables.tf
@@ -0,0 +1,48 @@
+/**
+ * Copyright 2018 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+variable "project_id" {
+  description = "The project ID to host the cluster in"
+}
+
+variable "cluster_name_suffix" {
+  description = "A suffix to append to the default cluster name"
+  default     = ""
+}
+
+variable "region" {
+  description = "The region to host the cluster in"
+}
+
+variable "network" {
+  description = "The VPC network to host the cluster in"
+}
+
+variable "subnetwork" {
+  description = "The subnetwork to host the cluster in"
+}
+
+variable "ip_range_pods" {
+  description = "The secondary ip range to use for pods"
+}
+
+variable "ip_range_services" {
+  description = "The secondary ip range to use for pods"
+}
+
+variable "compute_engine_service_account" {
+  description = "Service account to associate to the nodes in the cluster"
+}
diff --git a/examples/upstream_nameservers/README.md b/examples/upstream_nameservers/README.md
new file mode 100644
index 0000000000..f980e64f12
--- /dev/null
+++ b/examples/upstream_nameservers/README.md
@@ -0,0 +1,50 @@
+# Upstream Nameservers Cluster
+
+This example illustrates how to create a cluster that adds custom upstream nameservers to kube-dns.
+
+It will:
+- Create a cluster
+- Remove the default kube-dns configmap
+- Add a new kube-dns configmap with custom upstream nameservers
+
+[^]: (autogen_docs_start)
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-----:|:-----:|
+| cluster\_name\_suffix | A suffix to append to the default cluster name | string | `""` | no |
+| compute\_engine\_service\_account | Service account to associate to the nodes in the cluster | string | n/a | yes |
+| ip\_range\_pods | The secondary ip range to use for pods | string | n/a | yes |
+| ip\_range\_services | The secondary ip range to use for pods | string | n/a | yes |
+| network | The VPC network to host the cluster in | string | n/a | yes |
+| project\_id | The project ID to host the cluster in | string | n/a | yes |
+| region | The region to host the cluster in | string | n/a | yes |
+| subnetwork | The subnetwork to host the cluster in | string | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| ca\_certificate |  |
+| client\_token |  |
+| cluster\_name | Cluster name |
+| ip\_range\_pods | The secondary IP range used for pods |
+| ip\_range\_services | The secondary IP range used for services |
+| kubernetes\_endpoint |  |
+| location |  |
+| master\_kubernetes\_version | The master Kubernetes version |
+| network |  |
+| project\_id |  |
+| region |  |
+| service\_account | The service account to default running nodes as if not overridden in `node_pools`. |
+| subnetwork |  |
+| zones | List of zones in which the cluster resides |
+
+[^]: (autogen_docs_end)
+
+To provision this example, run the following from within this directory:
+- `terraform init` to get the plugins
+- `terraform plan` to see the infrastructure plan
+- `terraform apply` to apply the infrastructure build
+- `terraform destroy` to destroy the built infrastructure
diff --git a/examples/upstream_nameservers/main.tf b/examples/upstream_nameservers/main.tf
new file mode 100644
index 0000000000..1956ec0497
--- /dev/null
+++ b/examples/upstream_nameservers/main.tf
@@ -0,0 +1,47 @@
+/**
+ * Copyright 2018 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+locals {
+  cluster_type = "upstream-nameservers"
+}
+
+provider "google" {
+  version = "~> 2.9.0"
+  region  = "${var.region}"
+}
+
+provider "google-beta" {
+  version = "~> 2.9.0"
+  region  = "${var.region}"
+}
+
+module "gke" {
+  source            = "../../"
+  project_id        = "${var.project_id}"
+  name              = "${local.cluster_type}-cluster${var.cluster_name_suffix}"
+  region            = "${var.region}"
+  network           = "${var.network}"
+  subnetwork        = "${var.subnetwork}"
+  ip_range_pods     = "${var.ip_range_pods}"
+  ip_range_services = "${var.ip_range_services}"
+  network_policy    = true
+  service_account   = "${var.compute_engine_service_account}"
+
+  configure_ip_masq = true
+  upstream_nameservers = ["8.8.8.8", "8.8.4.4"]
+}
+
+data "google_client_config" "default" {}
diff --git a/examples/upstream_nameservers/outputs.tf b/examples/upstream_nameservers/outputs.tf
new file mode 100644
index 0000000000..9881585a48
--- /dev/null
+++ b/examples/upstream_nameservers/outputs.tf
@@ -0,0 +1,34 @@
+/**
+ * Copyright 2018 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+output "kubernetes_endpoint" {
+  sensitive = true
+  value     = "${module.gke.endpoint}"
+}
+
+output "client_token" {
+  sensitive = true
+  value     = "${base64encode(data.google_client_config.default.access_token)}"
+}
+
+output "ca_certificate" {
+  value = "${module.gke.ca_certificate}"
+}
+
+output "service_account" {
+  description = "The service account to default running nodes as if not overridden in `node_pools`."
+  value       = "${module.gke.service_account}"
+}
diff --git a/examples/upstream_nameservers/test_outputs.tf b/examples/upstream_nameservers/test_outputs.tf
new file mode 100644
index 0000000000..c1d4352219
--- /dev/null
+++ b/examples/upstream_nameservers/test_outputs.tf
@@ -0,0 +1,63 @@
+/**
+ * Copyright 2018 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// These outputs are used to test the module with kitchen-terraform
+// They do not need to be included in real-world uses of this module
+
+output "project_id" {
+  value = "${var.project_id}"
+}
+
+output "region" {
+  value = "${module.gke.region}"
+}
+
+output "cluster_name" {
+  description = "Cluster name"
+  value       = "${module.gke.name}"
+}
+
+output "network" {
+  value = "${var.network}"
+}
+
+output "subnetwork" {
+  value = "${var.subnetwork}"
+}
+
+output "location" {
+  value = "${module.gke.location}"
+}
+
+output "ip_range_pods" {
+  description = "The secondary IP range used for pods"
+  value       = "${var.ip_range_pods}"
+}
+
+output "ip_range_services" {
+  description = "The secondary IP range used for services"
+  value       = "${var.ip_range_services}"
+}
+
+output "zones" {
+  description = "List of zones in which the cluster resides"
+  value       = "${module.gke.zones}"
+}
+
+output "master_kubernetes_version" {
+  description = "The master Kubernetes version"
+  value       = "${module.gke.master_version}"
+}
diff --git a/examples/upstream_nameservers/variables.tf b/examples/upstream_nameservers/variables.tf
new file mode 100644
index 0000000000..a4409795b7
--- /dev/null
+++ b/examples/upstream_nameservers/variables.tf
@@ -0,0 +1,48 @@
+/**
+ * Copyright 2018 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+variable "project_id" {
+  description = "The project ID to host the cluster in"
+}
+
+variable "cluster_name_suffix" {
+  description = "A suffix to append to the default cluster name"
+  default     = ""
+}
+
+variable "region" {
+  description = "The region to host the cluster in"
+}
+
+variable "network" {
+  description = "The VPC network to host the cluster in"
+}
+
+variable "subnetwork" {
+  description = "The subnetwork to host the cluster in"
+}
+
+variable "ip_range_pods" {
+  description = "The secondary ip range to use for pods"
+}
+
+variable "ip_range_services" {
+  description = "The secondary ip range to use for pods"
+}
+
+variable "compute_engine_service_account" {
+  description = "Service account to associate to the nodes in the cluster"
+}
diff --git a/main.tf b/main.tf
index 0537749534..15d5650cbf 100644
--- a/main.tf
+++ b/main.tf
@@ -36,6 +36,7 @@ locals {
   node_version_regional       = "${var.node_version != "" && var.regional ? var.node_version : local.kubernetes_version_regional}"
   node_version_zonal          = "${var.node_version != "" && !var.regional ? var.node_version : local.kubernetes_version_zonal}"
   custom_kube_dns_config      = "${length(keys(var.stub_domains)) > 0 ? true : false}"
+  upstream_nameservers_config = "${length(var.upstream_nameservers) > 0 ? true : false}"
   network_project_id          = "${var.network_project_id != "" ? var.network_project_id : var.project_id}"
 
   cluster_type = "${var.regional ? "regional" : "zonal"}"
diff --git a/modules/beta-private-cluster/README.md b/modules/beta-private-cluster/README.md
index 0ceca593e4..4cfe31ffb0 100644
--- a/modules/beta-private-cluster/README.md
+++ b/modules/beta-private-cluster/README.md
@@ -171,6 +171,7 @@ In either case, upgrading to module version `v1.0.0` will trigger a recreation o
 | service\_account | The service account to run nodes as if not overridden in `node_pools`. The default value will cause a cluster-specific service account to be created. | string | `"create"` | no |
 | stub\_domains | Map of stub domains and their resolvers to forward DNS queries for a certain domain to an external DNS server | map | `<map>` | no |
 | subnetwork | The subnetwork to host the cluster in (required) | string | n/a | yes |
+| upstream\_nameservers | If specified, the values replace the nameservers taken by default from the node’s /etc/resolv.conf | list | `<list>` | no |
 | zones | The zones to host the cluster in (optional if regional cluster / required if zonal) | list | `<list>` | no |
 
 ## Outputs
diff --git a/modules/beta-private-cluster/dns.tf b/modules/beta-private-cluster/dns.tf
index 25effe580a..1cd73830bc 100644
--- a/modules/beta-private-cluster/dns.tf
+++ b/modules/beta-private-cluster/dns.tf
@@ -20,7 +20,7 @@
   Delete default kube-dns configmap
  *****************************************/
 resource "null_resource" "delete_default_kube_dns_configmap" {
-  count = "${local.custom_kube_dns_config ? 1 : 0}"
+  count = "${local.custom_kube_dns_config || local.upstream_nameservers_config ? 1 : 0}"
 
   provisioner "local-exec" {
     command = "${path.module}/scripts/kubectl_wrapper.sh https://${local.cluster_endpoint} ${data.google_client_config.default.access_token} ${local.cluster_ca_certificate} ${path.module}/scripts/delete-default-resource.sh kube-system configmap kube-dns"
@@ -33,7 +33,7 @@ resource "null_resource" "delete_default_kube_dns_configmap" {
   Create kube-dns confimap
  *****************************************/
 resource "kubernetes_config_map" "kube-dns" {
-  count = "${local.custom_kube_dns_config ? 1 : 0}"
+  count = "${local.custom_kube_dns_config && !local.upstream_nameservers_config ? 1 : 0}"
 
   metadata {
     name      = "kube-dns"
@@ -52,3 +52,48 @@ EOF
 
   depends_on = ["null_resource.delete_default_kube_dns_configmap", "data.google_client_config.default", "google_container_cluster.primary", "google_container_node_pool.pools", "google_container_cluster.zonal_primary", "google_container_node_pool.zonal_pools"]
 }
+
+resource "kubernetes_config_map" "kube-dns-upstream-namservers" {
+  count = "${!local.custom_kube_dns_config && local.upstream_nameservers_config ? 1 : 0}"
+
+  metadata {
+    name      = "kube-dns"
+    namespace = "kube-system"
+
+    labels {
+      maintained_by = "terraform"
+    }
+  }
+
+  data {
+    upstreamNameservers = <<EOF
+${jsonencode(var.upstream_nameservers)}
+EOF
+  }
+
+  depends_on = ["null_resource.delete_default_kube_dns_configmap", "data.google_client_config.default", "google_container_cluster.primary", "google_container_node_pool.pools", "google_container_cluster.zonal_primary", "google_container_node_pool.zonal_pools"]
+}
+
+resource "kubernetes_config_map" "kube-dns-upstream-nameservers-and-stub-domains" {
+  count = "${local.custom_kube_dns_config && local.upstream_nameservers_config ? 1 : 0}"
+
+  metadata {
+    name      = "kube-dns"
+    namespace = "kube-system"
+
+    labels {
+      maintained_by = "terraform"
+    }
+  }
+
+  data {
+    upstreamNameservers = <<EOF
+${jsonencode(var.upstream_nameservers)}
+EOF
+    stubDomains = <<EOF
+${jsonencode(var.stub_domains)}
+EOF
+  }
+
+  depends_on = ["null_resource.delete_default_kube_dns_configmap", "data.google_client_config.default", "google_container_cluster.primary", "google_container_node_pool.pools", "google_container_cluster.zonal_primary", "google_container_node_pool.zonal_pools"]
+}
diff --git a/modules/beta-private-cluster/main.tf b/modules/beta-private-cluster/main.tf
index 761aab9a5b..15444cba2a 100644
--- a/modules/beta-private-cluster/main.tf
+++ b/modules/beta-private-cluster/main.tf
@@ -36,6 +36,7 @@ locals {
   node_version_regional       = "${var.node_version != "" && var.regional ? var.node_version : local.kubernetes_version_regional}"
   node_version_zonal          = "${var.node_version != "" && !var.regional ? var.node_version : local.kubernetes_version_zonal}"
   custom_kube_dns_config      = "${length(keys(var.stub_domains)) > 0 ? true : false}"
+  upstream_nameservers_config = "${length(var.upstream_nameservers) > 0 ? true : false}"
   network_project_id          = "${var.network_project_id != "" ? var.network_project_id : var.project_id}"
 
   cluster_type = "${var.regional ? "regional" : "zonal"}"
diff --git a/modules/beta-private-cluster/variables.tf b/modules/beta-private-cluster/variables.tf
index 44762bd81c..a917f9301c 100644
--- a/modules/beta-private-cluster/variables.tf
+++ b/modules/beta-private-cluster/variables.tf
@@ -206,6 +206,12 @@ variable "stub_domains" {
   default     = {}
 }
 
+variable "upstream_nameservers" {
+  type        = "list"
+  description = "If specified, the values replace the nameservers taken by default from the node’s /etc/resolv.conf"
+  default     = []
+}
+
 variable "non_masquerade_cidrs" {
   type        = "list"
   description = "List of strings in CIDR notation that specify the IP address ranges that do not use IP masquerading."
diff --git a/modules/beta-public-cluster/README.md b/modules/beta-public-cluster/README.md
index af91bd12f8..8ad09e8d5a 100644
--- a/modules/beta-public-cluster/README.md
+++ b/modules/beta-public-cluster/README.md
@@ -162,6 +162,7 @@ In either case, upgrading to module version `v1.0.0` will trigger a recreation o
 | service\_account | The service account to run nodes as if not overridden in `node_pools`. The default value will cause a cluster-specific service account to be created. | string | `"create"` | no |
 | stub\_domains | Map of stub domains and their resolvers to forward DNS queries for a certain domain to an external DNS server | map | `<map>` | no |
 | subnetwork | The subnetwork to host the cluster in (required) | string | n/a | yes |
+| upstream\_nameservers | If specified, the values replace the nameservers taken by default from the node’s /etc/resolv.conf | list | `<list>` | no |
 | zones | The zones to host the cluster in (optional if regional cluster / required if zonal) | list | `<list>` | no |
 
 ## Outputs
diff --git a/modules/beta-public-cluster/dns.tf b/modules/beta-public-cluster/dns.tf
index 25effe580a..1cd73830bc 100644
--- a/modules/beta-public-cluster/dns.tf
+++ b/modules/beta-public-cluster/dns.tf
@@ -20,7 +20,7 @@
   Delete default kube-dns configmap
  *****************************************/
 resource "null_resource" "delete_default_kube_dns_configmap" {
-  count = "${local.custom_kube_dns_config ? 1 : 0}"
+  count = "${local.custom_kube_dns_config || local.upstream_nameservers_config ? 1 : 0}"
 
   provisioner "local-exec" {
     command = "${path.module}/scripts/kubectl_wrapper.sh https://${local.cluster_endpoint} ${data.google_client_config.default.access_token} ${local.cluster_ca_certificate} ${path.module}/scripts/delete-default-resource.sh kube-system configmap kube-dns"
@@ -33,7 +33,7 @@ resource "null_resource" "delete_default_kube_dns_configmap" {
   Create kube-dns confimap
  *****************************************/
 resource "kubernetes_config_map" "kube-dns" {
-  count = "${local.custom_kube_dns_config ? 1 : 0}"
+  count = "${local.custom_kube_dns_config && !local.upstream_nameservers_config ? 1 : 0}"
 
   metadata {
     name      = "kube-dns"
@@ -52,3 +52,48 @@ EOF
 
   depends_on = ["null_resource.delete_default_kube_dns_configmap", "data.google_client_config.default", "google_container_cluster.primary", "google_container_node_pool.pools", "google_container_cluster.zonal_primary", "google_container_node_pool.zonal_pools"]
 }
+
+resource "kubernetes_config_map" "kube-dns-upstream-namservers" {
+  count = "${!local.custom_kube_dns_config && local.upstream_nameservers_config ? 1 : 0}"
+
+  metadata {
+    name      = "kube-dns"
+    namespace = "kube-system"
+
+    labels {
+      maintained_by = "terraform"
+    }
+  }
+
+  data {
+    upstreamNameservers = <<EOF
+${jsonencode(var.upstream_nameservers)}
+EOF
+  }
+
+  depends_on = ["null_resource.delete_default_kube_dns_configmap", "data.google_client_config.default", "google_container_cluster.primary", "google_container_node_pool.pools", "google_container_cluster.zonal_primary", "google_container_node_pool.zonal_pools"]
+}
+
+resource "kubernetes_config_map" "kube-dns-upstream-nameservers-and-stub-domains" {
+  count = "${local.custom_kube_dns_config && local.upstream_nameservers_config ? 1 : 0}"
+
+  metadata {
+    name      = "kube-dns"
+    namespace = "kube-system"
+
+    labels {
+      maintained_by = "terraform"
+    }
+  }
+
+  data {
+    upstreamNameservers = <<EOF
+${jsonencode(var.upstream_nameservers)}
+EOF
+    stubDomains = <<EOF
+${jsonencode(var.stub_domains)}
+EOF
+  }
+
+  depends_on = ["null_resource.delete_default_kube_dns_configmap", "data.google_client_config.default", "google_container_cluster.primary", "google_container_node_pool.pools", "google_container_cluster.zonal_primary", "google_container_node_pool.zonal_pools"]
+}
diff --git a/modules/beta-public-cluster/main.tf b/modules/beta-public-cluster/main.tf
index 30f48438dc..b68bd3cf96 100644
--- a/modules/beta-public-cluster/main.tf
+++ b/modules/beta-public-cluster/main.tf
@@ -36,6 +36,7 @@ locals {
   node_version_regional       = "${var.node_version != "" && var.regional ? var.node_version : local.kubernetes_version_regional}"
   node_version_zonal          = "${var.node_version != "" && !var.regional ? var.node_version : local.kubernetes_version_zonal}"
   custom_kube_dns_config      = "${length(keys(var.stub_domains)) > 0 ? true : false}"
+  upstream_nameservers_config = "${length(var.upstream_nameservers) > 0 ? true : false}"
   network_project_id          = "${var.network_project_id != "" ? var.network_project_id : var.project_id}"
 
   cluster_type = "${var.regional ? "regional" : "zonal"}"
diff --git a/modules/beta-public-cluster/variables.tf b/modules/beta-public-cluster/variables.tf
index fb9c5225fe..a7831d89cf 100644
--- a/modules/beta-public-cluster/variables.tf
+++ b/modules/beta-public-cluster/variables.tf
@@ -206,6 +206,12 @@ variable "stub_domains" {
   default     = {}
 }
 
+variable "upstream_nameservers" {
+  type        = "list"
+  description = "If specified, the values replace the nameservers taken by default from the node’s /etc/resolv.conf"
+  default     = []
+}
+
 variable "non_masquerade_cidrs" {
   type        = "list"
   description = "List of strings in CIDR notation that specify the IP address ranges that do not use IP masquerading."
diff --git a/modules/private-cluster/README.md b/modules/private-cluster/README.md
index 914ca81837..a14a253276 100644
--- a/modules/private-cluster/README.md
+++ b/modules/private-cluster/README.md
@@ -163,6 +163,7 @@ In either case, upgrading to module version `v1.0.0` will trigger a recreation o
 | service\_account | The service account to run nodes as if not overridden in `node_pools`. The default value will cause a cluster-specific service account to be created. | string | `"create"` | no |
 | stub\_domains | Map of stub domains and their resolvers to forward DNS queries for a certain domain to an external DNS server | map | `<map>` | no |
 | subnetwork | The subnetwork to host the cluster in (required) | string | n/a | yes |
+| upstream\_nameservers | If specified, the values replace the nameservers taken by default from the node’s /etc/resolv.conf | list | `<list>` | no |
 | zones | The zones to host the cluster in (optional if regional cluster / required if zonal) | list | `<list>` | no |
 
 ## Outputs
diff --git a/modules/private-cluster/dns.tf b/modules/private-cluster/dns.tf
index 25effe580a..1cd73830bc 100644
--- a/modules/private-cluster/dns.tf
+++ b/modules/private-cluster/dns.tf
@@ -20,7 +20,7 @@
   Delete default kube-dns configmap
  *****************************************/
 resource "null_resource" "delete_default_kube_dns_configmap" {
-  count = "${local.custom_kube_dns_config ? 1 : 0}"
+  count = "${local.custom_kube_dns_config || local.upstream_nameservers_config ? 1 : 0}"
 
   provisioner "local-exec" {
     command = "${path.module}/scripts/kubectl_wrapper.sh https://${local.cluster_endpoint} ${data.google_client_config.default.access_token} ${local.cluster_ca_certificate} ${path.module}/scripts/delete-default-resource.sh kube-system configmap kube-dns"
@@ -33,7 +33,7 @@ resource "null_resource" "delete_default_kube_dns_configmap" {
   Create kube-dns confimap
  *****************************************/
 resource "kubernetes_config_map" "kube-dns" {
-  count = "${local.custom_kube_dns_config ? 1 : 0}"
+  count = "${local.custom_kube_dns_config && !local.upstream_nameservers_config ? 1 : 0}"
 
   metadata {
     name      = "kube-dns"
@@ -52,3 +52,48 @@ EOF
 
   depends_on = ["null_resource.delete_default_kube_dns_configmap", "data.google_client_config.default", "google_container_cluster.primary", "google_container_node_pool.pools", "google_container_cluster.zonal_primary", "google_container_node_pool.zonal_pools"]
 }
+
+resource "kubernetes_config_map" "kube-dns-upstream-namservers" {
+  count = "${!local.custom_kube_dns_config && local.upstream_nameservers_config ? 1 : 0}"
+
+  metadata {
+    name      = "kube-dns"
+    namespace = "kube-system"
+
+    labels {
+      maintained_by = "terraform"
+    }
+  }
+
+  data {
+    upstreamNameservers = <<EOF
+${jsonencode(var.upstream_nameservers)}
+EOF
+  }
+
+  depends_on = ["null_resource.delete_default_kube_dns_configmap", "data.google_client_config.default", "google_container_cluster.primary", "google_container_node_pool.pools", "google_container_cluster.zonal_primary", "google_container_node_pool.zonal_pools"]
+}
+
+resource "kubernetes_config_map" "kube-dns-upstream-nameservers-and-stub-domains" {
+  count = "${local.custom_kube_dns_config && local.upstream_nameservers_config ? 1 : 0}"
+
+  metadata {
+    name      = "kube-dns"
+    namespace = "kube-system"
+
+    labels {
+      maintained_by = "terraform"
+    }
+  }
+
+  data {
+    upstreamNameservers = <<EOF
+${jsonencode(var.upstream_nameservers)}
+EOF
+    stubDomains = <<EOF
+${jsonencode(var.stub_domains)}
+EOF
+  }
+
+  depends_on = ["null_resource.delete_default_kube_dns_configmap", "data.google_client_config.default", "google_container_cluster.primary", "google_container_node_pool.pools", "google_container_cluster.zonal_primary", "google_container_node_pool.zonal_pools"]
+}
diff --git a/modules/private-cluster/main.tf b/modules/private-cluster/main.tf
index 826d5a2a0c..68280084b0 100644
--- a/modules/private-cluster/main.tf
+++ b/modules/private-cluster/main.tf
@@ -36,6 +36,7 @@ locals {
   node_version_regional       = "${var.node_version != "" && var.regional ? var.node_version : local.kubernetes_version_regional}"
   node_version_zonal          = "${var.node_version != "" && !var.regional ? var.node_version : local.kubernetes_version_zonal}"
   custom_kube_dns_config      = "${length(keys(var.stub_domains)) > 0 ? true : false}"
+  upstream_nameservers_config = "${length(var.upstream_nameservers) > 0 ? true : false}"
   network_project_id          = "${var.network_project_id != "" ? var.network_project_id : var.project_id}"
 
   cluster_type = "${var.regional ? "regional" : "zonal"}"
diff --git a/modules/private-cluster/variables.tf b/modules/private-cluster/variables.tf
index f40aedc99a..69d6956a5c 100644
--- a/modules/private-cluster/variables.tf
+++ b/modules/private-cluster/variables.tf
@@ -206,6 +206,12 @@ variable "stub_domains" {
   default     = {}
 }
 
+variable "upstream_nameservers" {
+  type        = "list"
+  description = "If specified, the values replace the nameservers taken by default from the node’s /etc/resolv.conf"
+  default     = []
+}
+
 variable "non_masquerade_cidrs" {
   type        = "list"
   description = "List of strings in CIDR notation that specify the IP address ranges that do not use IP masquerading."
diff --git a/test/fixtures/stub_domains_private/terraform.tfvars b/test/fixtures/stub_domains_private/terraform.tfvars
new file mode 120000
index 0000000000..08ac6f4724
--- /dev/null
+++ b/test/fixtures/stub_domains_private/terraform.tfvars
@@ -0,0 +1 @@
+../shared/terraform.tfvars
\ No newline at end of file
diff --git a/test/fixtures/stub_domains_upstream_nameservers/example.tf b/test/fixtures/stub_domains_upstream_nameservers/example.tf
new file mode 100644
index 0000000000..77af226437
--- /dev/null
+++ b/test/fixtures/stub_domains_upstream_nameservers/example.tf
@@ -0,0 +1,28 @@
+/**
+ * Copyright 2018 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+module "example" {
+  source = "../../../examples/stub_domains_upstream_nameservers"
+
+  project_id                     = "${var.project_id}"
+  cluster_name_suffix            = "-${random_string.suffix.result}"
+  region                         = "${var.region}"
+  network                        = "${google_compute_network.main.name}"
+  subnetwork                     = "${google_compute_subnetwork.main.name}"
+  ip_range_pods                  = "${google_compute_subnetwork.main.secondary_ip_range.0.range_name}"
+  ip_range_services              = "${google_compute_subnetwork.main.secondary_ip_range.1.range_name}"
+  compute_engine_service_account = "${var.compute_engine_service_account}"
+}
diff --git a/test/fixtures/stub_domains_upstream_nameservers/network.tf b/test/fixtures/stub_domains_upstream_nameservers/network.tf
new file mode 100644
index 0000000000..2dfbf2d9b2
--- /dev/null
+++ b/test/fixtures/stub_domains_upstream_nameservers/network.tf
@@ -0,0 +1,47 @@
+/**
+ * Copyright 2018 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+resource "random_string" "suffix" {
+  length  = 4
+  special = false
+  upper   = false
+}
+
+provider "google" {
+  project     = "${var.project_id}"
+}
+
+resource "google_compute_network" "main" {
+  name                    = "cft-gke-test-${random_string.suffix.result}"
+  auto_create_subnetworks = "false"
+}
+
+resource "google_compute_subnetwork" "main" {
+  name          = "cft-gke-test-${random_string.suffix.result}"
+  ip_cidr_range = "10.0.0.0/17"
+  region        = "${var.region}"
+  network       = "${google_compute_network.main.self_link}"
+
+  secondary_ip_range {
+    range_name    = "cft-gke-test-pods-${random_string.suffix.result}"
+    ip_cidr_range = "192.168.0.0/18"
+  }
+
+  secondary_ip_range {
+    range_name    = "cft-gke-test-services-${random_string.suffix.result}"
+    ip_cidr_range = "192.168.64.0/18"
+  }
+}
diff --git a/test/fixtures/stub_domains_upstream_nameservers/outputs.tf b/test/fixtures/stub_domains_upstream_nameservers/outputs.tf
new file mode 120000
index 0000000000..726bdc722f
--- /dev/null
+++ b/test/fixtures/stub_domains_upstream_nameservers/outputs.tf
@@ -0,0 +1 @@
+../shared/outputs.tf
\ No newline at end of file
diff --git a/test/fixtures/stub_domains_upstream_nameservers/terraform.tfvars b/test/fixtures/stub_domains_upstream_nameservers/terraform.tfvars
new file mode 120000
index 0000000000..08ac6f4724
--- /dev/null
+++ b/test/fixtures/stub_domains_upstream_nameservers/terraform.tfvars
@@ -0,0 +1 @@
+../shared/terraform.tfvars
\ No newline at end of file
diff --git a/test/fixtures/stub_domains_upstream_nameservers/variables.tf b/test/fixtures/stub_domains_upstream_nameservers/variables.tf
new file mode 120000
index 0000000000..c113c00a3d
--- /dev/null
+++ b/test/fixtures/stub_domains_upstream_nameservers/variables.tf
@@ -0,0 +1 @@
+../shared/variables.tf
\ No newline at end of file
diff --git a/test/fixtures/upstream_nameservers/example.tf b/test/fixtures/upstream_nameservers/example.tf
new file mode 100644
index 0000000000..50f1aadfac
--- /dev/null
+++ b/test/fixtures/upstream_nameservers/example.tf
@@ -0,0 +1,28 @@
+/**
+ * Copyright 2018 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+module "example" {
+  source = "../../../examples/upstream_nameservers"
+
+  project_id                     = "${var.project_id}"
+  cluster_name_suffix            = "-${random_string.suffix.result}"
+  region                         = "${var.region}"
+  network                        = "${google_compute_network.main.name}"
+  subnetwork                     = "${google_compute_subnetwork.main.name}"
+  ip_range_pods                  = "${google_compute_subnetwork.main.secondary_ip_range.0.range_name}"
+  ip_range_services              = "${google_compute_subnetwork.main.secondary_ip_range.1.range_name}"
+  compute_engine_service_account = "${var.compute_engine_service_account}"
+}
diff --git a/test/fixtures/upstream_nameservers/network.tf b/test/fixtures/upstream_nameservers/network.tf
new file mode 100644
index 0000000000..2dfbf2d9b2
--- /dev/null
+++ b/test/fixtures/upstream_nameservers/network.tf
@@ -0,0 +1,47 @@
+/**
+ * Copyright 2018 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+resource "random_string" "suffix" {
+  length  = 4
+  special = false
+  upper   = false
+}
+
+provider "google" {
+  project     = "${var.project_id}"
+}
+
+resource "google_compute_network" "main" {
+  name                    = "cft-gke-test-${random_string.suffix.result}"
+  auto_create_subnetworks = "false"
+}
+
+resource "google_compute_subnetwork" "main" {
+  name          = "cft-gke-test-${random_string.suffix.result}"
+  ip_cidr_range = "10.0.0.0/17"
+  region        = "${var.region}"
+  network       = "${google_compute_network.main.self_link}"
+
+  secondary_ip_range {
+    range_name    = "cft-gke-test-pods-${random_string.suffix.result}"
+    ip_cidr_range = "192.168.0.0/18"
+  }
+
+  secondary_ip_range {
+    range_name    = "cft-gke-test-services-${random_string.suffix.result}"
+    ip_cidr_range = "192.168.64.0/18"
+  }
+}
diff --git a/test/fixtures/upstream_nameservers/outputs.tf b/test/fixtures/upstream_nameservers/outputs.tf
new file mode 120000
index 0000000000..726bdc722f
--- /dev/null
+++ b/test/fixtures/upstream_nameservers/outputs.tf
@@ -0,0 +1 @@
+../shared/outputs.tf
\ No newline at end of file
diff --git a/test/fixtures/upstream_nameservers/terraform.tfvars b/test/fixtures/upstream_nameservers/terraform.tfvars
new file mode 120000
index 0000000000..08ac6f4724
--- /dev/null
+++ b/test/fixtures/upstream_nameservers/terraform.tfvars
@@ -0,0 +1 @@
+../shared/terraform.tfvars
\ No newline at end of file
diff --git a/test/fixtures/upstream_nameservers/variables.tf b/test/fixtures/upstream_nameservers/variables.tf
new file mode 120000
index 0000000000..c113c00a3d
--- /dev/null
+++ b/test/fixtures/upstream_nameservers/variables.tf
@@ -0,0 +1 @@
+../shared/variables.tf
\ No newline at end of file
diff --git a/test/integration/stub_domains_upstream_nameservers/controls/gcloud.rb b/test/integration/stub_domains_upstream_nameservers/controls/gcloud.rb
new file mode 100644
index 0000000000..03612e151e
--- /dev/null
+++ b/test/integration/stub_domains_upstream_nameservers/controls/gcloud.rb
@@ -0,0 +1,50 @@
+# Copyright 2018 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+project_id = attribute('project_id')
+location = attribute('location')
+cluster_name = attribute('cluster_name')
+
+control "gcloud" do
+  title "Google Compute Engine GKE configuration"
+  describe command("gcloud --project=#{project_id} container clusters --zone=#{location} describe #{cluster_name} --format=json") do
+    its(:exit_status) { should eq 0 }
+    its(:stderr) { should eq '' }
+
+    let!(:data) do
+      if subject.exit_status == 0
+        JSON.parse(subject.stdout)
+      else
+        {}
+      end
+    end
+
+    describe "cluster" do
+      it "is running" do
+        expect(data['status']).to eq 'RUNNING'
+      end
+
+      it "has the expected addon settings" do
+        expect(data['addonsConfig']).to eq({
+          "horizontalPodAutoscaling" => {},
+          "httpLoadBalancing" => {},
+          "kubernetesDashboard" => {
+            "disabled" => true,
+          },
+          "networkPolicyConfig" => {},
+        })
+      end
+    end
+  end
+end
diff --git a/test/integration/stub_domains_upstream_nameservers/controls/kubectl.rb b/test/integration/stub_domains_upstream_nameservers/controls/kubectl.rb
new file mode 100644
index 0000000000..5223cbd2d4
--- /dev/null
+++ b/test/integration/stub_domains_upstream_nameservers/controls/kubectl.rb
@@ -0,0 +1,92 @@
+# Copyright 2018 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'kubeclient'
+require 'rest-client'
+
+require 'base64'
+
+kubernetes_endpoint = attribute('kubernetes_endpoint')
+client_token = attribute('client_token')
+ca_certificate = attribute('ca_certificate')
+
+control "kubectl" do
+  title "Kubernetes configuration"
+
+  describe "kubernetes" do
+    let(:kubernetes_http_endpoint) { "https://#{kubernetes_endpoint}/api" }
+    let(:client) do
+      cert_store = OpenSSL::X509::Store.new
+      cert_store.add_cert(OpenSSL::X509::Certificate.new(Base64.decode64(ca_certificate)))
+      Kubeclient::Client.new(
+        kubernetes_http_endpoint,
+        "v1",
+        ssl_options: {
+          cert_store: cert_store,
+          verify_ssl: OpenSSL::SSL::VERIFY_PEER,
+        },
+        auth_options: {
+          bearer_token: Base64.decode64(client_token),
+        },
+      )
+    end
+
+    describe "configmap" do
+      describe "kube-dns" do
+        let(:kubedns_configmap) { client.get_config_map("kube-dns", "kube-system") }
+
+        it "is created by Terraform" do
+          expect(kubedns_configmap.metadata.labels.maintained_by).to eq "terraform"
+        end
+
+        it "reflects the stub_domains configuration" do
+          expect(JSON.parse(kubedns_configmap.data.stubDomains)).to eq({
+            "example.com" => [
+              "10.254.154.11",
+              "10.254.154.12",
+            ],
+            "example.net" => [
+              "10.254.154.11",
+              "10.254.154.12",
+            ],
+          })
+        end
+
+        it "reflects the upstream_nameservers configuration" do
+          expect(JSON.parse(kubedns_configmap.data.upstreamNameservers)).to eq(["8.8.8.8", "8.8.4.4"])
+        end
+      end
+
+      describe "ipmasq" do
+        let(:ipmasq_configmap) { client.get_config_map("ip-masq-agent", "kube-system") }
+
+        it "is created by Terraform" do
+          expect(ipmasq_configmap.metadata.labels.maintained_by).to eq "terraform"
+        end
+
+        it "is configured properly" do
+          expect(YAML.load(ipmasq_configmap.data.config)).to eq({
+            "nonMasqueradeCIDRs" => [
+              "10.0.0.0/8",
+              "172.16.0.0/12",
+              "192.168.0.0/16",
+            ],
+            "resyncInterval" => "60s",
+            "masqLinkLocal" => false,
+          })
+        end
+      end
+    end
+  end
+end
diff --git a/test/integration/stub_domains_upstream_nameservers/inspec.yml b/test/integration/stub_domains_upstream_nameservers/inspec.yml
new file mode 100644
index 0000000000..a14a4d1bd7
--- /dev/null
+++ b/test/integration/stub_domains_upstream_nameservers/inspec.yml
@@ -0,0 +1,20 @@
+name: stub_domains_upstream_nameservers
+attributes:
+  - name: project_id
+    required: true
+    type: string
+  - name: location
+    required: true
+    type: string
+  - name: cluster_name
+    required: true
+    type: string
+  - name: kubernetes_endpoint
+    required: true
+    type: string
+  - name: client_token
+    required: true
+    type: string
+  - name: ca_certificate
+    required: true
+    type: string
diff --git a/test/integration/upstream_nameservers/controls/gcloud.rb b/test/integration/upstream_nameservers/controls/gcloud.rb
new file mode 100644
index 0000000000..03612e151e
--- /dev/null
+++ b/test/integration/upstream_nameservers/controls/gcloud.rb
@@ -0,0 +1,50 @@
+# Copyright 2018 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+project_id = attribute('project_id')
+location = attribute('location')
+cluster_name = attribute('cluster_name')
+
+control "gcloud" do
+  title "Google Compute Engine GKE configuration"
+  describe command("gcloud --project=#{project_id} container clusters --zone=#{location} describe #{cluster_name} --format=json") do
+    its(:exit_status) { should eq 0 }
+    its(:stderr) { should eq '' }
+
+    let!(:data) do
+      if subject.exit_status == 0
+        JSON.parse(subject.stdout)
+      else
+        {}
+      end
+    end
+
+    describe "cluster" do
+      it "is running" do
+        expect(data['status']).to eq 'RUNNING'
+      end
+
+      it "has the expected addon settings" do
+        expect(data['addonsConfig']).to eq({
+          "horizontalPodAutoscaling" => {},
+          "httpLoadBalancing" => {},
+          "kubernetesDashboard" => {
+            "disabled" => true,
+          },
+          "networkPolicyConfig" => {},
+        })
+      end
+    end
+  end
+end
diff --git a/test/integration/upstream_nameservers/controls/kubectl.rb b/test/integration/upstream_nameservers/controls/kubectl.rb
new file mode 100644
index 0000000000..36612a02aa
--- /dev/null
+++ b/test/integration/upstream_nameservers/controls/kubectl.rb
@@ -0,0 +1,79 @@
+# Copyright 2018 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'kubeclient'
+require 'rest-client'
+
+require 'base64'
+
+kubernetes_endpoint = attribute('kubernetes_endpoint')
+client_token = attribute('client_token')
+ca_certificate = attribute('ca_certificate')
+
+control "kubectl" do
+  title "Kubernetes configuration"
+
+  describe "kubernetes" do
+    let(:kubernetes_http_endpoint) { "https://#{kubernetes_endpoint}/api" }
+    let(:client) do
+      cert_store = OpenSSL::X509::Store.new
+      cert_store.add_cert(OpenSSL::X509::Certificate.new(Base64.decode64(ca_certificate)))
+      Kubeclient::Client.new(
+        kubernetes_http_endpoint,
+        "v1",
+        ssl_options: {
+          cert_store: cert_store,
+          verify_ssl: OpenSSL::SSL::VERIFY_PEER,
+        },
+        auth_options: {
+          bearer_token: Base64.decode64(client_token),
+        },
+      )
+    end
+
+    describe "configmap" do
+      describe "kube-dns" do
+        let(:kubedns_configmap) { client.get_config_map("kube-dns", "kube-system") }
+
+        it "is created by Terraform" do
+          expect(kubedns_configmap.metadata.labels.maintained_by).to eq "terraform"
+        end
+
+        it "reflects the upstream_nameservers configuration" do
+          expect(JSON.parse(kubedns_configmap.data.upstreamNameservers)).to eq(["8.8.8.8", "8.8.4.4"])
+        end
+      end
+
+      describe "ipmasq" do
+        let(:ipmasq_configmap) { client.get_config_map("ip-masq-agent", "kube-system") }
+
+        it "is created by Terraform" do
+          expect(ipmasq_configmap.metadata.labels.maintained_by).to eq "terraform"
+        end
+
+        it "is configured properly" do
+          expect(YAML.load(ipmasq_configmap.data.config)).to eq({
+            "nonMasqueradeCIDRs" => [
+              "10.0.0.0/8",
+              "172.16.0.0/12",
+              "192.168.0.0/16",
+            ],
+            "resyncInterval" => "60s",
+            "masqLinkLocal" => false,
+          })
+        end
+      end
+    end
+  end
+end
diff --git a/test/integration/upstream_nameservers/inspec.yml b/test/integration/upstream_nameservers/inspec.yml
new file mode 100644
index 0000000000..dd51197410
--- /dev/null
+++ b/test/integration/upstream_nameservers/inspec.yml
@@ -0,0 +1,20 @@
+name: upstream_nameservers
+attributes:
+  - name: project_id
+    required: true
+    type: string
+  - name: location
+    required: true
+    type: string
+  - name: cluster_name
+    required: true
+    type: string
+  - name: kubernetes_endpoint
+    required: true
+    type: string
+  - name: client_token
+    required: true
+    type: string
+  - name: ca_certificate
+    required: true
+    type: string
diff --git a/variables.tf b/variables.tf
index a4630b3102..acf9e8e006 100644
--- a/variables.tf
+++ b/variables.tf
@@ -206,6 +206,12 @@ variable "stub_domains" {
   default     = {}
 }
 
+variable "upstream_nameservers" {
+  type        = "list"
+  description = "If specified, the values replace the nameservers taken by default from the node’s /etc/resolv.conf"
+  default     = []
+}
+
 variable "non_masquerade_cidrs" {
   type        = "list"
   description = "List of strings in CIDR notation that specify the IP address ranges that do not use IP masquerading."

From c77334c3a4c43734a8d9fbf4773bbafcf6867e70 Mon Sep 17 00:00:00 2001
From: Marko Vlahovic <vlahovic@google.com>
Date: Fri, 5 Jul 2019 16:47:57 -0700
Subject: [PATCH 06/14] Adding tests to ci

---
 test/ci/stub-domains-upstream-nameservers.yml | 18 ++++++++++++++++++
 test/ci/upstream-nameservers.yml              | 18 ++++++++++++++++++
 2 files changed, 36 insertions(+)
 create mode 100644 test/ci/stub-domains-upstream-nameservers.yml
 create mode 100644 test/ci/upstream-nameservers.yml

diff --git a/test/ci/stub-domains-upstream-nameservers.yml b/test/ci/stub-domains-upstream-nameservers.yml
new file mode 100644
index 0000000000..4015338278
--- /dev/null
+++ b/test/ci/stub-domains-upstream-nameservers.yml
@@ -0,0 +1,18 @@
+---
+
+platform: linux
+
+inputs:
+- name: pull-request
+  path: terraform-google-kubernetes-engine
+
+run:
+  path: make
+  args: ['test_integration']
+  dir: terraform-google-kubernetes-engine
+
+params:
+  SUITE: "stub-domains-upstream-nameservers-local"
+  COMPUTE_ENGINE_SERVICE_ACCOUNT: ""
+  REGION: "us-east4"
+  ZONES: '["us-east4-a", "us-east4-b", "us-east4-c"]'
diff --git a/test/ci/upstream-nameservers.yml b/test/ci/upstream-nameservers.yml
new file mode 100644
index 0000000000..987884010a
--- /dev/null
+++ b/test/ci/upstream-nameservers.yml
@@ -0,0 +1,18 @@
+---
+
+platform: linux
+
+inputs:
+- name: pull-request
+  path: terraform-google-kubernetes-engine
+
+run:
+  path: make
+  args: ['test_integration']
+  dir: terraform-google-kubernetes-engine
+
+params:
+  SUITE: "upstream-nameservers-local"
+  COMPUTE_ENGINE_SERVICE_ACCOUNT: ""
+  REGION: "us-east4"
+  ZONES: '["us-east4-a", "us-east4-b", "us-east4-c"]'

From 7d379796e892cbd1636be71344dba000fa67711f Mon Sep 17 00:00:00 2001
From: Aaron Lane <aarondrewlane@gmail.com>
Date: Mon, 8 Jul 2019 15:11:32 -0400
Subject: [PATCH 07/14] [skip ci] Add CHANGELOG entry for #207

---
 CHANGELOG.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 892087843a..da9cd5610c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,7 @@ Extending the adopted spec, each change should have a link to its corresponding
 * Support for configuring cluster IPv4 CIDRs. [#193]
 * Support for configuring IP Masquerade. [#187]
 * Support for v2.9 of the Google providers. [#198]
+* Support for upstreamNameservers. [#207]
 
 ### Fixed
 
@@ -145,6 +146,7 @@ Extending the adopted spec, each change should have a link to its corresponding
 [v0.3.0]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/compare/v0.2.0...v0.3.0
 [v0.2.0]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/compare/v0.1.0...v0.2.0
 
+[#207]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/pull/207
 [#203]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/pull/203
 [#198]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/pull/198
 [#197]: https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/pull/197

From c4458cd96bd77b4828cc69b82649fe5d7e29b8bb Mon Sep 17 00:00:00 2001
From: Aaron Lane <aarondrewlane@gmail.com>
Date: Mon, 8 Jul 2019 15:17:15 -0400
Subject: [PATCH 08/14] [skip ci] Remove deprecated versions from README

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index c3ec7bc284..2fbe870b62 100644
--- a/README.md
+++ b/README.md
@@ -199,7 +199,7 @@ The [project factory](https://github.com/terraform-google-modules/terraform-goog
 - [kubectl](https://github.com/kubernetes/kubernetes/releases) 1.9.x
 #### Terraform and Plugins
 - [Terraform](https://www.terraform.io/downloads.html) 0.11.x
-- [terraform-provider-google](https://github.com/terraform-providers/terraform-provider-google) v2.3, v2.6, v2.9
+- [Terraform Provider for GCP][terraform-provider-google] v2.9
 
 ### Configure a Service Account
 In order to execute this module you must have a Service Account with the

From 46e50959b28c10936970b540f637dc499931f328 Mon Sep 17 00:00:00 2001
From: Aaron Lane <aarondrewlane@gmail.com>
Date: Mon, 8 Jul 2019 15:19:44 -0400
Subject: [PATCH 09/14] [skip ci] Adjust CHANGELOG entry for #198

---
 CHANGELOG.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index da9cd5610c..857b6ad5e7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,8 +26,8 @@ Extending the adopted spec, each change should have a link to its corresponding
 
 ### Fixed
 
-* Dropped support for v2.7 of the Google providers; these versions were
-  incompatible with the guest accelerator. [#198]
+* Dropped support for versions of the Google provider earlier than v2.9; these versions multiple
+  incompatibilities with the module. [#198]
 
 ## [v2.1.0] - 2019-05-30
 

From b9174dc2eeb97117d09853eaf38eb89148b5b468 Mon Sep 17 00:00:00 2001
From: Aaron Lane <aarondrewlane@gmail.com>
Date: Mon, 8 Jul 2019 15:20:11 -0400
Subject: [PATCH 10/14] [skip ci] Set release date for v3.0.0

---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 857b6ad5e7..2f1269c5f0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,7 +8,7 @@ Extending the adopted spec, each change should have a link to its corresponding
 
 ## [Unreleased]
 
-## [v3.0.0] - 2019-07-ZZ
+## [v3.0.0] - 2019-07-08
 
 ### Added
 

From 44fb2f61d981035495032b67ecfbc01b344f97ee Mon Sep 17 00:00:00 2001
From: Aaron Lane <aarondrewlane@gmail.com>
Date: Mon, 8 Jul 2019 15:39:43 -0400
Subject: [PATCH 11/14] Backport provider doc update to README template

---
 autogen/README.md | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/autogen/README.md b/autogen/README.md
index 53b7d4b615..34e1f5f4d6 100644
--- a/autogen/README.md
+++ b/autogen/README.md
@@ -142,9 +142,9 @@ The [project factory](https://github.com/terraform-google-modules/terraform-goog
 #### Terraform and Plugins
 - [Terraform](https://www.terraform.io/downloads.html) 0.11.x
 {% if private_cluster or beta_cluster %}
-- [terraform-provider-google-beta](https://github.com/terraform-providers/terraform-provider-google-beta) v2.3, v2.6, v2.9
+- [Terraform Provider for GCP Beta][terraform-provider-google-beta] v2.9
 {% else %}
-- [terraform-provider-google](https://github.com/terraform-providers/terraform-provider-google) v2.3, v2.6, v2.9
+- [Terraform Provider for GCP][terraform-provider-google] v2.9
 {% endif %}
 
 ### Configure a Service Account
@@ -317,3 +317,8 @@ command.
 {% else %}
 [upgrading-to-v2.0]: docs/upgrading_to_v2.0.md
 {% endif %}
+{% if private_cluster or beta_cluster %}
+[terraform-provider-google-beta]: https://github.com/terraform-providers/terraform-provider-google-beta
+{% else %}
+[terraform-provider-google]: https://github.com/terraform-providers/terraform-provider-google
+{% endif %}

From 7cb8a00be55605345dd07e1b30ef01483450f890 Mon Sep 17 00:00:00 2001
From: Aaron Lane <aarondrewlane@gmail.com>
Date: Mon, 8 Jul 2019 15:40:11 -0400
Subject: [PATCH 12/14] Add reference to README of v3.0 upgrade guide

---
 autogen/README.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/autogen/README.md b/autogen/README.md
index 34e1f5f4d6..e43b896ede 100644
--- a/autogen/README.md
+++ b/autogen/README.md
@@ -111,6 +111,11 @@ Then perform the following commands on the root folder:
 - `terraform apply` to apply the infrastructure build
 - `terraform destroy` to destroy the built infrastructure
 
+## Upgrade to v3.0.0
+
+v3.0.0 is a breaking release. Refer to the
+[Upgrading to v3.0 guide][upgrading-to-v3.0] for details.
+
 ## Upgrade to v2.0.0
 
 v2.0.0 is a breaking release. Refer to the
@@ -318,6 +323,11 @@ command.
 [upgrading-to-v2.0]: docs/upgrading_to_v2.0.md
 {% endif %}
 {% if private_cluster or beta_cluster %}
+[upgrading-to-v3.0]: ../../docs/upgrading_to_v3.0.md
+{% else %}
+[upgrading-to-v3.0]: docs/upgrading_to_v3.0.md
+{% endif %}
+{% if private_cluster or beta_cluster %}
 [terraform-provider-google-beta]: https://github.com/terraform-providers/terraform-provider-google-beta
 {% else %}
 [terraform-provider-google]: https://github.com/terraform-providers/terraform-provider-google

From 15f8e40a4e43dde9af8365bee851bc95e1833ef6 Mon Sep 17 00:00:00 2001
From: Aaron Lane <aarondrewlane@gmail.com>
Date: Mon, 8 Jul 2019 15:51:14 -0400
Subject: [PATCH 13/14] Fix permanent diff with generate and fmt

---
 autogen/cluster_regional.tf | 1 +
 autogen/cluster_zonal.tf    | 7 ++++---
 autogen/dns.tf              | 1 +
 autogen/main.tf             | 5 ++---
 autogen/outputs.tf          | 1 +
 5 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/autogen/cluster_regional.tf b/autogen/cluster_regional.tf
index 847d2808fe..6dcd2e01ed 100644
--- a/autogen/cluster_regional.tf
+++ b/autogen/cluster_regional.tf
@@ -107,6 +107,7 @@ resource "google_container_cluster" "primary" {
     node_config {
       service_account = "${lookup(var.node_pools[0], "service_account", local.service_account)}"
       {% if beta_cluster %}
+
       workload_metadata_config = "${local.cluster_node_metadata_config["${var.node_metadata == "UNSPECIFIED" ? "unspecified" : "specified"}"]}"
       {% endif %}
     }
diff --git a/autogen/cluster_zonal.tf b/autogen/cluster_zonal.tf
index c03c57a0f8..24ed5671e6 100644
--- a/autogen/cluster_zonal.tf
+++ b/autogen/cluster_zonal.tf
@@ -39,10 +39,10 @@ resource "google_container_cluster" "zonal_primary" {
   monitoring_service = "${var.monitoring_service}"
 
   {% if beta_cluster %}
-  enable_binary_authorization       = "${var.enable_binary_authorization}"
-  pod_security_policy_config        = "${var.pod_security_policy_config}"
-  {% endif %}
+  enable_binary_authorization = "${var.enable_binary_authorization}"
+  pod_security_policy_config  = "${var.pod_security_policy_config}"
 
+  {% endif %}
   master_authorized_networks_config = ["${var.master_authorized_networks_config}"]
 
   master_auth {
@@ -108,6 +108,7 @@ resource "google_container_cluster" "zonal_primary" {
     node_config {
       service_account = "${lookup(var.node_pools[0], "service_account", local.service_account)}"
       {% if beta_cluster %}
+
       workload_metadata_config = "${local.cluster_node_metadata_config["${var.node_metadata == "UNSPECIFIED" ? "unspecified" : "specified"}"]}"
       {% endif %}
     }
diff --git a/autogen/dns.tf b/autogen/dns.tf
index 43f1a24a2e..24a3f34844 100644
--- a/autogen/dns.tf
+++ b/autogen/dns.tf
@@ -90,6 +90,7 @@ resource "kubernetes_config_map" "kube-dns-upstream-nameservers-and-stub-domains
     upstreamNameservers = <<EOF
 ${jsonencode(var.upstream_nameservers)}
 EOF
+
     stubDomains = <<EOF
 ${jsonencode(var.stub_domains)}
 EOF
diff --git a/autogen/main.tf b/autogen/main.tf
index 9a6c4229a4..54d836c615 100644
--- a/autogen/main.tf
+++ b/autogen/main.tf
@@ -196,9 +196,8 @@ locals {
   cluster_kubernetes_dashboard_enabled       = "${local.cluster_type_output_kubernetes_dashboard_enabled[local.cluster_type] ? false : true}"
 {% if beta_cluster %}
   # BETA features
-  cluster_istio_enabled    = "${local.cluster_type_output_istio_enabled[local.cluster_type] ? false : true}"
-  cluster_cloudrun_enabled = "${var.cloudrun}"
-
+  cluster_istio_enabled                      = "${local.cluster_type_output_istio_enabled[local.cluster_type] ? false : true}"
+  cluster_cloudrun_enabled                   = "${var.cloudrun}"
   cluster_pod_security_policy_enabled        = "${local.cluster_type_output_pod_security_policy_enabled[local.cluster_type] ? true : false}"
   # /BETA features
 {% endif %}
diff --git a/autogen/outputs.tf b/autogen/outputs.tf
index 58a2e15b0d..fac9e0e67f 100644
--- a/autogen/outputs.tf
+++ b/autogen/outputs.tf
@@ -113,6 +113,7 @@ output "service_account" {
   value       = "${local.service_account}"
 }
 {% if beta_cluster %}
+
 output "istio_enabled" {
   description = "Whether Istio is enabled"
   value       = "${local.cluster_istio_enabled}"

From 321eabede7c25c0a17c1aeaef8677e31c1b22d35 Mon Sep 17 00:00:00 2001
From: Aaron Lane <aarondrewlane@gmail.com>
Date: Mon, 8 Jul 2019 15:52:22 -0400
Subject: [PATCH 14/14] Regenerate modules

---
 README.md                                        | 7 +++++++
 cluster_zonal.tf                                 | 1 -
 dns.tf                                           | 1 +
 modules/beta-private-cluster/README.md           | 9 ++++++++-
 modules/beta-private-cluster/cluster_regional.tf | 1 +
 modules/beta-private-cluster/cluster_zonal.tf    | 5 +++--
 modules/beta-private-cluster/dns.tf              | 1 +
 modules/beta-private-cluster/main.tf             | 4 ++--
 modules/beta-private-cluster/outputs.tf          | 1 +
 modules/beta-public-cluster/README.md            | 9 ++++++++-
 modules/beta-public-cluster/cluster_regional.tf  | 1 +
 modules/beta-public-cluster/cluster_zonal.tf     | 5 +++--
 modules/beta-public-cluster/dns.tf               | 1 +
 modules/beta-public-cluster/main.tf              | 4 ++--
 modules/beta-public-cluster/outputs.tf           | 1 +
 modules/private-cluster/README.md                | 9 ++++++++-
 modules/private-cluster/cluster_zonal.tf         | 1 -
 modules/private-cluster/dns.tf                   | 1 +
 18 files changed, 49 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 2fbe870b62..f175e8d507 100644
--- a/README.md
+++ b/README.md
@@ -97,6 +97,11 @@ Then perform the following commands on the root folder:
 - `terraform apply` to apply the infrastructure build
 - `terraform destroy` to destroy the built infrastructure
 
+## Upgrade to v3.0.0
+
+v3.0.0 is a breaking release. Refer to the
+[Upgrading to v3.0 guide][upgrading-to-v3.0] for details.
+
 ## Upgrade to v2.0.0
 
 v2.0.0 is a breaking release. Refer to the
@@ -367,3 +372,5 @@ command.
 * Dockerfiles - hadolint. Can be found in homebrew
 
 [upgrading-to-v2.0]: docs/upgrading_to_v2.0.md
+[upgrading-to-v3.0]: docs/upgrading_to_v3.0.md
+[terraform-provider-google]: https://github.com/terraform-providers/terraform-provider-google
diff --git a/cluster_zonal.tf b/cluster_zonal.tf
index 8b4eb7cc5a..466b81634d 100644
--- a/cluster_zonal.tf
+++ b/cluster_zonal.tf
@@ -38,7 +38,6 @@ resource "google_container_cluster" "zonal_primary" {
   logging_service    = "${var.logging_service}"
   monitoring_service = "${var.monitoring_service}"
 
-
   master_authorized_networks_config = ["${var.master_authorized_networks_config}"]
 
   master_auth {
diff --git a/dns.tf b/dns.tf
index 1cd73830bc..91b41efac4 100644
--- a/dns.tf
+++ b/dns.tf
@@ -90,6 +90,7 @@ resource "kubernetes_config_map" "kube-dns-upstream-nameservers-and-stub-domains
     upstreamNameservers = <<EOF
 ${jsonencode(var.upstream_nameservers)}
 EOF
+
     stubDomains = <<EOF
 ${jsonencode(var.stub_domains)}
 EOF
diff --git a/modules/beta-private-cluster/README.md b/modules/beta-private-cluster/README.md
index 4cfe31ffb0..8027d6da2b 100644
--- a/modules/beta-private-cluster/README.md
+++ b/modules/beta-private-cluster/README.md
@@ -104,6 +104,11 @@ Then perform the following commands on the root folder:
 - `terraform apply` to apply the infrastructure build
 - `terraform destroy` to destroy the built infrastructure
 
+## Upgrade to v3.0.0
+
+v3.0.0 is a breaking release. Refer to the
+[Upgrading to v3.0 guide][upgrading-to-v3.0] for details.
+
 ## Upgrade to v2.0.0
 
 v2.0.0 is a breaking release. Refer to the
@@ -219,7 +224,7 @@ The [project factory](https://github.com/terraform-google-modules/terraform-goog
 - [kubectl](https://github.com/kubernetes/kubernetes/releases) 1.9.x
 #### Terraform and Plugins
 - [Terraform](https://www.terraform.io/downloads.html) 0.11.x
-- [terraform-provider-google-beta](https://github.com/terraform-providers/terraform-provider-google-beta) v2.3, v2.6, v2.9
+- [Terraform Provider for GCP Beta][terraform-provider-google-beta] v2.9
 
 ### Configure a Service Account
 In order to execute this module you must have a Service Account with the
@@ -387,3 +392,5 @@ command.
 * Dockerfiles - hadolint. Can be found in homebrew
 
 [upgrading-to-v2.0]: ../../docs/upgrading_to_v2.0.md
+[upgrading-to-v3.0]: ../../docs/upgrading_to_v3.0.md
+[terraform-provider-google-beta]: https://github.com/terraform-providers/terraform-provider-google-beta
diff --git a/modules/beta-private-cluster/cluster_regional.tf b/modules/beta-private-cluster/cluster_regional.tf
index 97ca1475af..4142486488 100644
--- a/modules/beta-private-cluster/cluster_regional.tf
+++ b/modules/beta-private-cluster/cluster_regional.tf
@@ -102,6 +102,7 @@ resource "google_container_cluster" "primary" {
 
     node_config {
       service_account = "${lookup(var.node_pools[0], "service_account", local.service_account)}"
+
       workload_metadata_config = "${local.cluster_node_metadata_config["${var.node_metadata == "UNSPECIFIED" ? "unspecified" : "specified"}"]}"
     }
   }
diff --git a/modules/beta-private-cluster/cluster_zonal.tf b/modules/beta-private-cluster/cluster_zonal.tf
index f9bded28f8..9df66bfbc1 100644
--- a/modules/beta-private-cluster/cluster_zonal.tf
+++ b/modules/beta-private-cluster/cluster_zonal.tf
@@ -38,8 +38,8 @@ resource "google_container_cluster" "zonal_primary" {
   logging_service    = "${var.logging_service}"
   monitoring_service = "${var.monitoring_service}"
 
-  enable_binary_authorization       = "${var.enable_binary_authorization}"
-  pod_security_policy_config        = "${var.pod_security_policy_config}"
+  enable_binary_authorization = "${var.enable_binary_authorization}"
+  pod_security_policy_config  = "${var.pod_security_policy_config}"
 
   master_authorized_networks_config = ["${var.master_authorized_networks_config}"]
 
@@ -103,6 +103,7 @@ resource "google_container_cluster" "zonal_primary" {
 
     node_config {
       service_account = "${lookup(var.node_pools[0], "service_account", local.service_account)}"
+
       workload_metadata_config = "${local.cluster_node_metadata_config["${var.node_metadata == "UNSPECIFIED" ? "unspecified" : "specified"}"]}"
     }
   }
diff --git a/modules/beta-private-cluster/dns.tf b/modules/beta-private-cluster/dns.tf
index 1cd73830bc..91b41efac4 100644
--- a/modules/beta-private-cluster/dns.tf
+++ b/modules/beta-private-cluster/dns.tf
@@ -90,6 +90,7 @@ resource "kubernetes_config_map" "kube-dns-upstream-nameservers-and-stub-domains
     upstreamNameservers = <<EOF
 ${jsonencode(var.upstream_nameservers)}
 EOF
+
     stubDomains = <<EOF
 ${jsonencode(var.stub_domains)}
 EOF
diff --git a/modules/beta-private-cluster/main.tf b/modules/beta-private-cluster/main.tf
index 15444cba2a..da81eb19e0 100644
--- a/modules/beta-private-cluster/main.tf
+++ b/modules/beta-private-cluster/main.tf
@@ -192,8 +192,8 @@ locals {
   cluster_horizontal_pod_autoscaling_enabled = "${local.cluster_type_output_horizontal_pod_autoscaling_enabled[local.cluster_type] ? false : true}"
   cluster_kubernetes_dashboard_enabled       = "${local.cluster_type_output_kubernetes_dashboard_enabled[local.cluster_type] ? false : true}"
   # BETA features
-  cluster_istio_enabled    = "${local.cluster_type_output_istio_enabled[local.cluster_type] ? false : true}"
-  cluster_cloudrun_enabled = "${var.cloudrun}"
+  cluster_istio_enabled               = "${local.cluster_type_output_istio_enabled[local.cluster_type] ? false : true}"
+  cluster_cloudrun_enabled            = "${var.cloudrun}"
   cluster_pod_security_policy_enabled = "${local.cluster_type_output_pod_security_policy_enabled[local.cluster_type] ? true : false}"
 
   # /BETA features
diff --git a/modules/beta-private-cluster/outputs.tf b/modules/beta-private-cluster/outputs.tf
index f7c707cc8f..acc7d1b7bc 100644
--- a/modules/beta-private-cluster/outputs.tf
+++ b/modules/beta-private-cluster/outputs.tf
@@ -112,6 +112,7 @@ output "service_account" {
   description = "The service account to default running nodes as if not overridden in `node_pools`."
   value       = "${local.service_account}"
 }
+
 output "istio_enabled" {
   description = "Whether Istio is enabled"
   value       = "${local.cluster_istio_enabled}"
diff --git a/modules/beta-public-cluster/README.md b/modules/beta-public-cluster/README.md
index 8ad09e8d5a..913caf418a 100644
--- a/modules/beta-public-cluster/README.md
+++ b/modules/beta-public-cluster/README.md
@@ -99,6 +99,11 @@ Then perform the following commands on the root folder:
 - `terraform apply` to apply the infrastructure build
 - `terraform destroy` to destroy the built infrastructure
 
+## Upgrade to v3.0.0
+
+v3.0.0 is a breaking release. Refer to the
+[Upgrading to v3.0 guide][upgrading-to-v3.0] for details.
+
 ## Upgrade to v2.0.0
 
 v2.0.0 is a breaking release. Refer to the
@@ -210,7 +215,7 @@ The [project factory](https://github.com/terraform-google-modules/terraform-goog
 - [kubectl](https://github.com/kubernetes/kubernetes/releases) 1.9.x
 #### Terraform and Plugins
 - [Terraform](https://www.terraform.io/downloads.html) 0.11.x
-- [terraform-provider-google-beta](https://github.com/terraform-providers/terraform-provider-google-beta) v2.3, v2.6, v2.9
+- [Terraform Provider for GCP Beta][terraform-provider-google-beta] v2.9
 
 ### Configure a Service Account
 In order to execute this module you must have a Service Account with the
@@ -378,3 +383,5 @@ command.
 * Dockerfiles - hadolint. Can be found in homebrew
 
 [upgrading-to-v2.0]: docs/upgrading_to_v2.0.md
+[upgrading-to-v3.0]: ../../docs/upgrading_to_v3.0.md
+[terraform-provider-google-beta]: https://github.com/terraform-providers/terraform-provider-google-beta
diff --git a/modules/beta-public-cluster/cluster_regional.tf b/modules/beta-public-cluster/cluster_regional.tf
index 88f2aa089c..b651323baf 100644
--- a/modules/beta-public-cluster/cluster_regional.tf
+++ b/modules/beta-public-cluster/cluster_regional.tf
@@ -102,6 +102,7 @@ resource "google_container_cluster" "primary" {
 
     node_config {
       service_account = "${lookup(var.node_pools[0], "service_account", local.service_account)}"
+
       workload_metadata_config = "${local.cluster_node_metadata_config["${var.node_metadata == "UNSPECIFIED" ? "unspecified" : "specified"}"]}"
     }
   }
diff --git a/modules/beta-public-cluster/cluster_zonal.tf b/modules/beta-public-cluster/cluster_zonal.tf
index 66d0352011..dca12fd9ce 100644
--- a/modules/beta-public-cluster/cluster_zonal.tf
+++ b/modules/beta-public-cluster/cluster_zonal.tf
@@ -38,8 +38,8 @@ resource "google_container_cluster" "zonal_primary" {
   logging_service    = "${var.logging_service}"
   monitoring_service = "${var.monitoring_service}"
 
-  enable_binary_authorization       = "${var.enable_binary_authorization}"
-  pod_security_policy_config        = "${var.pod_security_policy_config}"
+  enable_binary_authorization = "${var.enable_binary_authorization}"
+  pod_security_policy_config  = "${var.pod_security_policy_config}"
 
   master_authorized_networks_config = ["${var.master_authorized_networks_config}"]
 
@@ -103,6 +103,7 @@ resource "google_container_cluster" "zonal_primary" {
 
     node_config {
       service_account = "${lookup(var.node_pools[0], "service_account", local.service_account)}"
+
       workload_metadata_config = "${local.cluster_node_metadata_config["${var.node_metadata == "UNSPECIFIED" ? "unspecified" : "specified"}"]}"
     }
   }
diff --git a/modules/beta-public-cluster/dns.tf b/modules/beta-public-cluster/dns.tf
index 1cd73830bc..91b41efac4 100644
--- a/modules/beta-public-cluster/dns.tf
+++ b/modules/beta-public-cluster/dns.tf
@@ -90,6 +90,7 @@ resource "kubernetes_config_map" "kube-dns-upstream-nameservers-and-stub-domains
     upstreamNameservers = <<EOF
 ${jsonencode(var.upstream_nameservers)}
 EOF
+
     stubDomains = <<EOF
 ${jsonencode(var.stub_domains)}
 EOF
diff --git a/modules/beta-public-cluster/main.tf b/modules/beta-public-cluster/main.tf
index b68bd3cf96..a5ee918b2d 100644
--- a/modules/beta-public-cluster/main.tf
+++ b/modules/beta-public-cluster/main.tf
@@ -183,8 +183,8 @@ locals {
   cluster_horizontal_pod_autoscaling_enabled = "${local.cluster_type_output_horizontal_pod_autoscaling_enabled[local.cluster_type] ? false : true}"
   cluster_kubernetes_dashboard_enabled       = "${local.cluster_type_output_kubernetes_dashboard_enabled[local.cluster_type] ? false : true}"
   # BETA features
-  cluster_istio_enabled    = "${local.cluster_type_output_istio_enabled[local.cluster_type] ? false : true}"
-  cluster_cloudrun_enabled = "${var.cloudrun}"
+  cluster_istio_enabled               = "${local.cluster_type_output_istio_enabled[local.cluster_type] ? false : true}"
+  cluster_cloudrun_enabled            = "${var.cloudrun}"
   cluster_pod_security_policy_enabled = "${local.cluster_type_output_pod_security_policy_enabled[local.cluster_type] ? true : false}"
 
   # /BETA features
diff --git a/modules/beta-public-cluster/outputs.tf b/modules/beta-public-cluster/outputs.tf
index f7c707cc8f..acc7d1b7bc 100644
--- a/modules/beta-public-cluster/outputs.tf
+++ b/modules/beta-public-cluster/outputs.tf
@@ -112,6 +112,7 @@ output "service_account" {
   description = "The service account to default running nodes as if not overridden in `node_pools`."
   value       = "${local.service_account}"
 }
+
 output "istio_enabled" {
   description = "Whether Istio is enabled"
   value       = "${local.cluster_istio_enabled}"
diff --git a/modules/private-cluster/README.md b/modules/private-cluster/README.md
index a14a253276..1a77f749d1 100644
--- a/modules/private-cluster/README.md
+++ b/modules/private-cluster/README.md
@@ -102,6 +102,11 @@ Then perform the following commands on the root folder:
 - `terraform apply` to apply the infrastructure build
 - `terraform destroy` to destroy the built infrastructure
 
+## Upgrade to v3.0.0
+
+v3.0.0 is a breaking release. Refer to the
+[Upgrading to v3.0 guide][upgrading-to-v3.0] for details.
+
 ## Upgrade to v2.0.0
 
 v2.0.0 is a breaking release. Refer to the
@@ -208,7 +213,7 @@ The [project factory](https://github.com/terraform-google-modules/terraform-goog
 - [kubectl](https://github.com/kubernetes/kubernetes/releases) 1.9.x
 #### Terraform and Plugins
 - [Terraform](https://www.terraform.io/downloads.html) 0.11.x
-- [terraform-provider-google-beta](https://github.com/terraform-providers/terraform-provider-google-beta) v2.3, v2.6, v2.9
+- [Terraform Provider for GCP Beta][terraform-provider-google-beta] v2.9
 
 ### Configure a Service Account
 In order to execute this module you must have a Service Account with the
@@ -376,3 +381,5 @@ command.
 * Dockerfiles - hadolint. Can be found in homebrew
 
 [upgrading-to-v2.0]: ../../docs/upgrading_to_v2.0.md
+[upgrading-to-v3.0]: ../../docs/upgrading_to_v3.0.md
+[terraform-provider-google-beta]: https://github.com/terraform-providers/terraform-provider-google-beta
diff --git a/modules/private-cluster/cluster_zonal.tf b/modules/private-cluster/cluster_zonal.tf
index b410c08048..1ee89f7e93 100644
--- a/modules/private-cluster/cluster_zonal.tf
+++ b/modules/private-cluster/cluster_zonal.tf
@@ -38,7 +38,6 @@ resource "google_container_cluster" "zonal_primary" {
   logging_service    = "${var.logging_service}"
   monitoring_service = "${var.monitoring_service}"
 
-
   master_authorized_networks_config = ["${var.master_authorized_networks_config}"]
 
   master_auth {
diff --git a/modules/private-cluster/dns.tf b/modules/private-cluster/dns.tf
index 1cd73830bc..91b41efac4 100644
--- a/modules/private-cluster/dns.tf
+++ b/modules/private-cluster/dns.tf
@@ -90,6 +90,7 @@ resource "kubernetes_config_map" "kube-dns-upstream-nameservers-and-stub-domains
     upstreamNameservers = <<EOF
 ${jsonencode(var.upstream_nameservers)}
 EOF
+
     stubDomains = <<EOF
 ${jsonencode(var.stub_domains)}
 EOF