Replace basic example using terraform-google-vm and introduce automat…

…ed testing

- Add integration tests
- Add lint tests
- Use terraform-google-vm for basic example
- Update changelog

.gitignore

@@ -3,3 +3,5 @@
 **/backend.tf
 **/terraform.tfvars
 **/values-*.yaml
+.kitchen
+credentials.json

CHANGELOG.md

@@ -7,6 +7,16 @@ project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [2.1.0] - 2019-10-01
+
+### Changed
+
+- Updated basic example to use [terraform-google-vm](https://github.com/terraform-google-modules/terraform-google-vm) managed instance group. [#14]
+
+### Added
+
+- Introduced new lint testing and integration testing based on `terraform-google-modules` standards. [#12]
+
 ## [2.0.0] - 2019-08-02
 
 ### Changed
@@ -25,7 +35,8 @@ project adheres to [Semantic Versioning](http://semver.org/).
 ## [1.0.0] - 2017-08-28
 
 
-[Unreleased]: https://github.com/GoogleCloudPlatform/terraform-google-lb/compare/v2.0.0...HEAD
+[Unreleased]: https://github.com/GoogleCloudPlatform/terraform-google-lb/compare/v2.1.0...HEAD
+[2.0.1]: https://github.com/GoogleCloudPlatform/terraform-google-lb/compare/2.0.0...v2.1.0
 [2.0.0]: https://github.com/GoogleCloudPlatform/terraform-google-lb/compare/1.0.3...v2.0.0
 [1.0.3]: https://github.com/GoogleCloudPlatform/terraform-google-lb/compare/1.0.2...1.0.3
 [1.0.2]: https://github.com/GoogleCloudPlatform/terraform-google-lb/compare/1.0.1...1.0.2

CONTRIBUTING.md

@@ -1,48 +1,99 @@
-# How to become a contributor and submit your own code
+# Contributing
 
-## Contributor License Agreements
+This document provides guidelines for contributing to the module.
 
-We'd love to accept your sample apps and patches! Before we can take them, we
-have to jump a couple of legal hurdles.
+## Dependencies
 
-Please fill out either the individual or corporate Contributor License
-Agreement (CLA).
+The following dependencies must be installed on the development system:
 
-  * If you are an individual writing original source code and you're sure you
-    own the intellectual property, then you'll need to sign an [individual CLA]
-    (https://developers.google.com/open-source/cla/individual).
-  * If you work for a company that wants to allow you to contribute your work,
-    then you'll need to sign a [corporate CLA]
-    (https://developers.google.com/open-source/cla/corporate).
+- [Docker Engine][docker-engine]
+- [Google Cloud SDK][google-cloud-sdk]
+- [make]
 
-Follow either of the two links above to access the appropriate CLA and
-instructions for how to sign and return it. Once we receive it, we'll
-be able to accept your pull requests.
+## Generating Documentation for Inputs and Outputs
 
-## Contributing A Patch
+The Inputs and Outputs tables in the READMEs of the root module,
+submodules, and example modules are automatically generated based on
+the `variables` and `outputs` of the respective modules. These tables
+must be refreshed if the module interfaces are changed.
 
-1. Submit an issue describing your proposed change to the repo in question.
-1. The repo owner will respond to your issue promptly.
-1. If your proposed change is accepted, and you haven't already done so, sign a
-   Contributor License Agreement (see details above).
-1. Fork the desired repo, develop and test your code changes.
-1. Ensure that your code adheres to the existing style in the sample to which
-   you are contributing.
-1. Ensure that your code has an appropriate set of unit tests which all pass.
-1. Submit a pull request.
+### Execution
 
-## Style
+Run `make generate_docs` to generate new Inputs and Outputs tables.
 
-Format your HCL code with [`hclfmt`](https://github.com/fatih/hclfmt).
+## Integration Testing
 
-Make sure there are no differences between the `hclfmt` output and your .tf files:
+Integration tests are used to verify the behaviour of the root module,
+submodules, and example modules. Additions, changes, and fixes should
+be accompanied with tests.
+
+The integration tests are run using [Kitchen][kitchen],
+[Kitchen-Terraform][kitchen-terraform], and [InSpec][inspec]. These
+tools are packaged within a Docker image for convenience.
+
+The general strategy for these tests is to verify the behaviour of the
+[example modules](./examples/), thus ensuring that the root module,
+submodules, and example modules are all functionally correct.
+
+### Test Environment
+The easiest way to test the module is in an isolated test project. The setup for such a project is defined in [test/setup](./test/setup/) directory.
+
+To use this setup, you need a service account with Project Creator access on a folder. Export the Service Account credentials to your environment like so:
 
 ```
-diff -B <( cat *.tf ) <( hclfmt *.tf )
+export SERVICE_ACCOUNT_JSON=$(< credentials.json)
 ```
 
-Write changes to the files:
+You will also need to set a few environment variables:
+```
+export TF_VAR_org_id="your_org_id"
+export TF_VAR_folder_id="your_folder_id"
+export TF_VAR_billing_account="your_billing_account_id"
+```
 
+With these settings in place, you can prepare a test project using Docker:
+```
+make docker_test_prepare
 ```
-hclfmt -w *.tf
-```
+
+### Noninteractive Execution
+
+Run `make test_integration_docker` to test all of the example modules
+noninteractively, using the prepared test project.
+
+### Interactive Execution
+
+1. Run `make docker_run` to start the testing Docker container in
+   interactive mode.
+
+1. Run `kitchen_do create <EXAMPLE_NAME>` to initialize the working
+   directory for an example module.
+
+1. Run `kitchen_do converge <EXAMPLE_NAME>` to apply the example module.
+
+1. Run `kitchen_do verify <EXAMPLE_NAME>` to test the example module.
+
+1. Run `kitchen_do destroy <EXAMPLE_NAME>` to destroy the example module
+   state.
+
+## Linting and Formatting
+
+Many of the files in the repository can be linted or formatted to
+maintain a standard of quality.
+
+### Execution
+
+Run `make docker_test_lint`.
+
+[docker-engine]: https://www.docker.com/products/docker-engine
+[flake8]: http://flake8.pycqa.org/en/latest/
+[gofmt]: https://golang.org/cmd/gofmt/
+[google-cloud-sdk]: https://cloud.google.com/sdk/install
+[hadolint]: https://github.com/hadolint/hadolint
+[inspec]: https://inspec.io/
+[kitchen-terraform]: https://github.com/newcontext-oss/kitchen-terraform
+[kitchen]: https://kitchen.ci/
+[make]: https://en.wikipedia.org/wiki/Make_(software)
+[shellcheck]: https://www.shellcheck.net/
+[terraform-docs]: https://github.com/segmentio/terraform-docs
+[terraform]: https://terraform.io

LICENSE

@@ -199,4 +199,4 @@ 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.
+limitations under the License.

Makefile

@@ -0,0 +1,85 @@
+# Copyright 2019 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
+#
+#     https://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.
+
+# Please note that this file was generated from [terraform-google-module-template](https://github.com/terraform-google-modules/terraform-google-module-template).
+# Please make sure to contribute relevant changes upstream!
+
+# Make will use bash instead of sh
+SHELL := /usr/bin/env bash
+
+DOCKER_TAG_VERSION_DEVELOPER_TOOLS := 0.1.0
+DOCKER_IMAGE_DEVELOPER_TOOLS := cft/developer-tools
+REGISTRY_URL := gcr.io/cloud-foundation-cicd
+
+# Enter docker container for local development
+.PHONY: docker_run
+docker_run:
+	docker run --rm -it \
+		-e SERVICE_ACCOUNT_JSON \
+		-v $(CURDIR):/workspace \
+		$(REGISTRY_URL)/${DOCKER_IMAGE_DEVELOPER_TOOLS}:${DOCKER_TAG_VERSION_DEVELOPER_TOOLS} \
+		/bin/bash
+
+# Execute prepare tests within the docker container
+.PHONY: docker_test_prepare
+docker_test_prepare:
+	docker run --rm -it \
+		-e SERVICE_ACCOUNT_JSON \
+		-e TF_VAR_org_id \
+		-e TF_VAR_folder_id \
+		-e TF_VAR_billing_account \
+		-v $(CURDIR):/workspace \
+		$(REGISTRY_URL)/${DOCKER_IMAGE_DEVELOPER_TOOLS}:${DOCKER_TAG_VERSION_DEVELOPER_TOOLS} \
+		/usr/local/bin/execute_with_credentials.sh prepare_environment
+
+# Clean up test environment within the docker container
+.PHONY: docker_test_cleanup
+docker_test_cleanup:
+	docker run --rm -it \
+		-e SERVICE_ACCOUNT_JSON \
+		-e TF_VAR_org_id \
+		-e TF_VAR_folder_id \
+		-e TF_VAR_billing_account \
+		-v $(CURDIR):/workspace \
+		$(REGISTRY_URL)/${DOCKER_IMAGE_DEVELOPER_TOOLS}:${DOCKER_TAG_VERSION_DEVELOPER_TOOLS} \
+		/usr/local/bin/execute_with_credentials.sh cleanup_environment
+
+# Execute integration tests within the docker container
+.PHONY: docker_test_integration
+docker_test_integration:
+	docker run --rm -it \
+		-e SERVICE_ACCOUNT_JSON \
+		-v $(CURDIR):/workspace \
+		$(REGISTRY_URL)/${DOCKER_IMAGE_DEVELOPER_TOOLS}:${DOCKER_TAG_VERSION_DEVELOPER_TOOLS} \
+		/usr/local/bin/test_integration.sh
+
+# Execute lint tests within the docker container
+.PHONY: docker_test_lint
+docker_test_lint:
+	docker run --rm -it \
+		-v $(CURDIR):/workspace \
+		$(REGISTRY_URL)/${DOCKER_IMAGE_DEVELOPER_TOOLS}:${DOCKER_TAG_VERSION_DEVELOPER_TOOLS} \
+		/usr/local/bin/test_lint.sh
+
+# Generate documentation
+.PHONY: docker_generate_docs
+docker_generate_docs:
+	docker run --rm -it \
+		-v $(CURDIR):/workspace \
+		$(REGISTRY_URL)/${DOCKER_IMAGE_DEVELOPER_TOOLS}:${DOCKER_TAG_VERSION_DEVELOPER_TOOLS} \
+		/bin/bash -c 'source /usr/local/bin/task_helper_functions.sh && generate_docs'
+
+# Alias for backwards compatibility
+.PHONY: generate_docs
+generate_docs: docker_generate_docs

README.md

@@ -1,35 +1,55 @@
 # Regional TCP Load Balancer Terraform Module
-
 Modular Regional TCP Load Balancer for GCE using target pool and forwarding rule.
 
-<a href="https://concourse-tf.gcp.solutions/teams/main/pipelines/tf-examples-lb-basic" target="_blank">
-<img src="https://concourse-tf.gcp.solutions/api/v1/teams/main/pipelines/tf-examples-lb-basic/badge" /></a>
-
 ## Compatibility
-
- This module is meant for use with Terraform 0.12. If you haven't [upgraded](https://www.terraform.io/upgrade-guides/0-12.html)
- and need a Terraform 0.11.x-compatible version of this module, the last released version intended for
- Terraform 0.11.x is [1.0.3](https://github.com/GoogleCloudPlatform/terraform-google-lb/releases/tag/1.0.3)
+This module is meant for use with Terraform 0.12. If you haven't [upgraded](https://www.terraform.io/upgrade-guides/0-12.html) and need a Terraform 0.11.x-compatible version of this module, the last released version intended for Terraform 0.11.x is [1.0.3](https://github.com/terraform-google-modules/terraform-google-lb/releases/tag/1.0.3)
 
 ## Usage
+Basic usage is as follows:
+```hcl
+module "load_balancer" {
+  source       = "terraform-google-modules/lb"
+  region       = var.region
+  name         = "load-balancer"
+  service_port = 80
+  target_tags  = ["allow-lb-service"]
+  network      = var.network
+}
 
-```ruby
-module "gce-lb-fr" {
-  source       = "GoogleCloudPlatform/lb/google"
-  region       = "${var.region}"
-  name         = "group1-lb"
-  service_port = "${module.mig1.service_port}"
-  target_tags  = ["${module.mig1.target_tags}"]
+module "managed_instance_group" {
+  source            = "terraform-google-modules/vm/google//modules/mig"
+  region            = var.region
+  target_size       = 2
+  hostname          = "mig-simple"
+  instance_template = module.instance_template.self_link
+  target_pools      = [module.load_balancer.target_pool]
+  named_ports = [{
+    name = "http"
+    port = 80
+  }]
 }
 ```
-
-## Resources created
-
-**Figure 1.** *diagram of terraform resources*
-
-![architecture diagram](https://raw.githubusercontent.com/GoogleCloudPlatform/terraform-google-lb/master/diagram.png)
-
-- [`google_compute_forwarding_rule.default`](https://www.terraform.io/docs/providers/google/r/compute_forwarding_rule.html): TCP Forwarding rule to the service port on the instances.
-- [`google_compute_target_pool.default`](https://www.terraform.io/docs/providers/google/r/compute_target_pool.html): The target pool created for the instance group.
-- [`google_compute_http_health_check.default`](https://www.terraform.io/docs/providers/google/r/compute_http_health_check.html): The health check for the instance group targeted at the service port.
-- [`google_compute_firewall.default-lb-fw`](https://www.terraform.io/docs/providers/google/r/compute_firewall.html): Firewall that allows traffic from anywhere to instances service port.
+Full functional examples are located in the [examples](./examples/) directory.
+
+<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-----:|:-----:|
+| firewall\_project | Name of the project to create the firewall rule in. Useful for shared VPC. Default is var.project. | string | `""` | no |
+| name | Name for the forwarding rule and prefix for supporting resources. | string | n/a | yes |
+| network | Name of the network to create resources in. | string | `"default"` | no |
+| project | The project to deploy to, if not set the default provider project is used. | string | `""` | no |
+| region | Region used for GCP resources. | string | n/a | yes |
+| service\_port | TCP port your service is listening on. | number | n/a | yes |
+| session\_affinity | How to distribute load. Options are `NONE`, `CLIENT_IP` and `CLIENT_IP_PROTO` | string | `"NONE"` | no |
+| target\_tags | List of target tags to allow traffic using firewall rule. | list(string) | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| external\_ip | The external ip address of the forwarding rule. |
+| target\_pool | The `self_link` to the target pool resource created. |
+
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

build/int.cloudbuild.yaml

@@ -0,0 +1,41 @@
+# Copyright 2019 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
+#
+#     https://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.
+
+timeout: 3600s
+steps:
+- id: 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 && prepare_environment']
+  env:
+  - 'TF_VAR_org_id=$_ORG_ID'
+  - 'TF_VAR_folder_id=$_FOLDER_ID'
+  - 'TF_VAR_billing_account=$_BILLING_ACCOUNT'
+- id: create
+  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']
+- id: converge
+  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']
+- id: verify
+  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']
+- id: destroy
+  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']
+tags:
+- 'ci'
+- 'integration'
+substitutions:
+  _DOCKER_IMAGE_DEVELOPER_TOOLS: 'cft/developer-tools'
+  _DOCKER_TAG_VERSION_DEVELOPER_TOOLS: '0.1.0'