feat: Add an auth submodule outputting a kubeconfig (#469)

* Add GKE auth submodule

* Add example of auth submodule

* Fix copyright dates

* Linting

* Register test

* Add test fixtures

.kitchen.yml

@@ -99,6 +99,13 @@ suites:
       systems:
         - name: simple_regional_private
           backend: local
+  - name: "simple_regional_with_kubeconfig"
+    driver:
+      root_module_directory: test/fixtures/simple_regional_with_kubeconfig
+    verifier:
+      systems:
+        - name: simple_regional_with_kubeconfig
+          backend: local
   - name: "simple_zonal"
     driver:
       root_module_directory: test/fixtures/simple_zonal

build/int.cloudbuild.yaml

@@ -124,6 +124,26 @@ steps:
     - verify simple-regional-private-local
   name: 'gcr.io/cloud-foundation-cicd/$_DOCKER_IMAGE_DEVELOPER_TOOLS:$_DOCKER_TAG_VERSION_DEVELOPER_TOOLS'
   args: ['/bin/bash', '-c', 'source /usr/local/bin/task_helper_functions.sh && kitchen_do destroy simple-regional-private-local']
+- id: create simple-regional-with-kubeconfig-local
+  waitFor:
+    - prepare
+  name: 'gcr.io/cloud-foundation-cicd/$_DOCKER_IMAGE_DEVELOPER_TOOLS:$_DOCKER_TAG_VERSION_DEVELOPER_TOOLS'
+  args: ['/bin/bash', '-c', 'source /usr/local/bin/task_helper_functions.sh && kitchen_do create simple-regional-with-kubeconfig-local']
+- id: converge simple-regional-with-kubeconfig-local
+  waitFor:
+    - create simple-regional-with-kubeconfig-local
+  name: 'gcr.io/cloud-foundation-cicd/$_DOCKER_IMAGE_DEVELOPER_TOOLS:$_DOCKER_TAG_VERSION_DEVELOPER_TOOLS'
+  args: ['/bin/bash', '-c', 'source /usr/local/bin/task_helper_functions.sh && kitchen_do converge simple-regional-with-kubeconfig-local']
+- id: verify simple-regional-with-kubeconfig-local
+  waitFor:
+    - converge simple-regional-with-kubeconfig-local
+  name: 'gcr.io/cloud-foundation-cicd/$_DOCKER_IMAGE_DEVELOPER_TOOLS:$_DOCKER_TAG_VERSION_DEVELOPER_TOOLS'
+  args: ['/bin/bash', '-c', 'source /usr/local/bin/task_helper_functions.sh && kitchen_do verify simple-regional-with-kubeconfig-local']
+- id: destroy simple-regional-with-kubeconfig-local
+  waitFor:
+    - verify simple-regional-with-kubeconfig-local
+  name: 'gcr.io/cloud-foundation-cicd/$_DOCKER_IMAGE_DEVELOPER_TOOLS:$_DOCKER_TAG_VERSION_DEVELOPER_TOOLS'
+  args: ['/bin/bash', '-c', 'source /usr/local/bin/task_helper_functions.sh && kitchen_do destroy simple-regional-with-kubeconfig-local']
 - id: create simple-regional-with-networking-local
   waitFor:
     - prepare

examples/simple_regional_with_kubeconfig/README.md

@@ -0,0 +1,46 @@
+# Simple Regional Cluster
+
+This example illustrates how to create a simple cluster and output a `kubeconfig`
+
+<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+## 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 services | 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 |
+| skip\_provisioners | Flag to skip local-exec provisioners | bool | `"false"` | no |
+| 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 |
+| kubeconfig\_raw |  |
+| kubernetes\_endpoint |  |
+| location |  |
+| master\_kubernetes\_version | The master Kubernetes version |
+| network |  |
+| project\_id |  |
+| region |  |
+| service\_account | The default service account used for running nodes. |
+| subnetwork |  |
+| zones | List of zones in which the cluster resides |
+
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+
+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

examples/simple_regional_with_kubeconfig/main.tf

@@ -0,0 +1,48 @@
+/**
+ * Copyright 2020 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 = "simple-regional"
+}
+
+provider "google" {
+  version = "~> 3.3.0"
+  region  = var.region
+}
+
+module "gke" {
+  source                 = "../../"
+  project_id             = var.project_id
+  name                   = "${local.cluster_type}-cluster${var.cluster_name_suffix}"
+  regional               = true
+  region                 = var.region
+  network                = var.network
+  subnetwork             = var.subnetwork
+  ip_range_pods          = var.ip_range_pods
+  ip_range_services      = var.ip_range_services
+  create_service_account = false
+  service_account        = var.compute_engine_service_account
+  skip_provisioners      = var.skip_provisioners
+}
+
+module "gke_auth" {
+  source = "../../modules/auth"
+
+  project_id   = var.project_id
+  location     = module.gke.location
+  cluster_name = module.gke.name
+}
+

examples/simple_regional_with_kubeconfig/outputs.tf

@@ -0,0 +1,39 @@
+/**
+ * Copyright 2020 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_auth.host
+}
+
+output "client_token" {
+  sensitive = true
+  value     = module.gke_auth.token
+}
+
+output "ca_certificate" {
+  value = module.gke_auth.cluster_ca_certificate
+}
+
+output "kubeconfig_raw" {
+  value = module.gke_auth.kubeconfig_raw
+}
+
+output "service_account" {
+  description = "The default service account used for running nodes."
+  value       = module.gke.service_account
+}
+

examples/simple_regional_with_kubeconfig/test_outputs.tf

@@ -0,0 +1,63 @@
+/**
+ * Copyright 2020 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
+}

examples/simple_regional_with_kubeconfig/variables.tf

@@ -0,0 +1,54 @@
+/**
+ * Copyright 2020 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 services"
+}
+
+variable "compute_engine_service_account" {
+  description = "Service account to associate to the nodes in the cluster"
+}
+
+variable "skip_provisioners" {
+  type        = bool
+  description = "Flag to skip local-exec provisioners"
+  default     = false
+}

modules/auth/README.md

@@ -0,0 +1,44 @@
+# Terraform Kubernetes Engine Auth Module
+
+This module allows configuring authentication to a GKE cluster
+using an [OpenID Connect token](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens)
+retrieved from GCP as a `kubeconfig` file or as outputs intended for use with
+the `kubernetes` / `helm` providers.
+
+This module retrieves a token for the account configured with the `google`
+provider as the Terraform runner using the provider's `credentials`,
+`access_token`, or other means of authentication.
+
+## Usage
+
+```tf
+module "gke_auth" {
+  source           = "terraform-google-modules/kubernetes-engine/google//modules/auth"
+
+  project_id       = "my-project-id"
+  cluster_name     = "my-cluster-name"
+  location         = module.gke.location
+}
+```
+
+
+### `kubeconfig` output
+
+```hcl
+resource "local_file" "kubeconfig" {
+  content  = module.gke_auth.kubeconfig_raw
+  filename = "${path.module}/kubeconfig"
+}
+```
+
+### `kubernetes`/`helm` provider output
+
+```hcl
+provider "kubernetes" {
+  load_config_file = false
+
+  cluster_ca_certificate = module.gke_auth.cluster_ca_certificate
+  host                   = module.gke_auth.host
+  token                  = module.gke_auth.token
+}
+```

modules/auth/main.tf

@@ -0,0 +1,34 @@
+/**
+ * Copyright 2020 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.
+ */
+
+data "google_container_cluster" "gke_cluster" {
+  name     = var.cluster_name
+  location = var.location
+  project  = var.project_id
+}
+
+data "google_client_config" "provider" {}
+
+data "template_file" "kubeconfig" {
+  template = file("${path.module}/templates/kubeconfig-template.yaml.tpl")
+
+  vars = {
+    context                = data.google_container_cluster.gke_cluster.name
+    cluster_ca_certificate = data.google_container_cluster.gke_cluster.master_auth[0].cluster_ca_certificate
+    endpoint               = data.google_container_cluster.gke_cluster.endpoint
+    token                  = data.google_client_config.provider.access_token
+  }
+}