Merge pull request #14 from terraform-google-modules/aaron-lane/submo…

…dules

Redesign to use submodules

.gitignore

@@ -45,4 +45,5 @@ crash.log
 
 credentials.json
 
-examples/automatic_labelling/function_source.zip
+examples/automatic-labelling-from-localhost/function_source.zip
+examples/automatic-labelling-from-repository/function_source_copy

Makefile

@@ -21,7 +21,7 @@ SHELL := /usr/bin/env bash
 # Docker build config variables
 CREDENTIALS_PATH 			?= /cft/workdir/credentials.json
 DOCKER_ORG 				:= gcr.io/cloud-foundation-cicd
-DOCKER_TAG_BASE_KITCHEN_TERRAFORM 	?= 0.11.10_216.0.0_1.19.1_0.1.10
+DOCKER_TAG_BASE_KITCHEN_TERRAFORM 	?= 1.0.0
 DOCKER_REPO_BASE_KITCHEN_TERRAFORM 	:= ${DOCKER_ORG}/cft/kitchen-terraform:${DOCKER_TAG_BASE_KITCHEN_TERRAFORM}
 
 all: check generate_docs

README.md

@@ -1,79 +1,83 @@
-# terraform-google-event-function
+# Event Function
 
-This module configures a system which responds to filtered Stackdriver
-Logging events by invoking a Cloud Functions function.
+This module configures a system which responds to events by invoking a
+Cloud Functions function.
 
-A project-level Stackdriver Logging export uses a provided filter to
-identify events of interest and publish them to a dedicated Pub/Sub
-topic. A Cloud Functions function subscribes to the topic and uses
-provided source code to process each event. The source code is
-retrieved from an archive which is created locally and stored in a
-Storage bucket.
+The root module configures a function sourced from a directory on
+localhost to respond to a given event trigger. The source directory is
+compressed and uploaded as a Cloud Storage bucket object which will be
+leveraged by the function.
+
+Alternatively, the
+[repository-function submodule][repository-function-submodule]
+configures a function sourced from a Cloud Source Repositories
+repository.
 
 ## Usage
 
-The [examples directory](examples) contains tested references of how to
-use this module.
+The
+[automatic-labelling-from-localhost example][automatic-labelling-from-localhost-example]
+is a tested reference of how to use the root module with the
+[event-project-log-entry submodule][event-project-log-entry-submodule].
 
 [^]: (autogen_docs_start)
 
 ## Inputs
 
 | Name | Description | Type | Default | Required |
 |------|-------------|:----:|:-----:|:-----:|
-| function\_available\_memory\_mb | The amount of memory in megabytes allotted for the function to use. | string | `"256"` | no |
-| function\_description | The description of the function. | string | `"Processes log export events provided through a Pub/Sub topic subscription."` | no |
-| function\_entry\_point | The name of a method in the function source which will be invoked when the function is executed. | string | n/a | yes |
-| function\_environment\_variables | A set of key/value environment variable pairs to assign to the function. | map | `<map>` | no |
-| function\_event\_trigger\_failure\_policy\_retry | A toggle to determine if the function should be retried on failure. | string | `"false"` | no |
-| function\_labels | A set of key/value label pairs to assign to the function. | map | `<map>` | no |
-| function\_runtime | The runtime in which the function will be executed. | string | `"nodejs6"` | no |
-| function\_source\_archive\_bucket\_labels | A set of key/value label pairs to assign to the function source archive bucket. | map | `<map>` | no |
-| function\_source\_directory | The contents of this directory will be archived and used as the function source. | string | n/a | yes |
-| function\_timeout\_s | The amount of time in seconds allotted for the execution of the function. | string | `"60"` | no |
-| log\_export\_filter | The filter to apply when exporting logs to the Pub/Sub topic. | string | n/a | yes |
+| available\_memory\_mb | The amount of memory in megabytes allotted for the function to use. | string | `"256"` | no |
+| description | The description of the function. | string | `"Processes events."` | no |
+| entry\_point | The name of a method in the function source which will be invoked when the function is executed. | string | n/a | yes |
+| environment\_variables | A set of key/value environment variable pairs to assign to the function. | map | `<map>` | no |
+| event\_trigger | A source that fires events in response to a condition in another service. | map | n/a | yes |
+| labels | A set of key/value label pairs to assign to any lableable resources. | map | `<map>` | no |
 | name | The name to apply to any nameable resources. | string | n/a | yes |
 | project\_id | The ID of the project to which resources will be applied. | string | n/a | yes |
 | region | The region in which resources will be applied. | string | n/a | yes |
+| runtime | The runtime in which the function will be executed. | string | `"nodejs6"` | no |
+| source\_directory | The pathname of the directory which contains the function source code. | string | n/a | yes |
+| timeout\_s | The amount of time in seconds allotted for the execution of the function. | string | `"60"` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| name | The name of the function. |
 
 [^]: (autogen_docs_end)
 
 ## Requirements
 
-The following requirements must be met in order to invoke this module:
-
-1. [Software dependencies](#software-dependencies).
-2. [IAM roles](#iam-roles).
-3. [APIs](#apis).
+The following sections describe the requirements which must be met in
+order to invoke this module.
 
 ### Software Dependencies
 
 The following software dependencies must be installed on the system
 from which this module will be invoked:
 
-- [Terraform][terraform-site] v0.11.x
-- [Google Terraform provider][terraform-provider-google-site] v1.20.0
+- [Terraform][terraform-site] v0.11.Z
+- [Terraform Provider for Archive][terraform-provider-archive-site]
+  v1.2.Z
+- [Terraform Provider for Google Cloud Platform][terraform-provider-gcp-site]
+  v2.1.Z
 
 ### IAM Roles
 
 The Service Account which will be used to invoke this module must have
 the following IAM roles:
 
-- Cloud Functions Developer
-- Compute Viewer
-- Logs Configuration Writer
-- Pub/Sub Admin
-- Service Account User
-- Storage Admin
+- Cloud Functions Developer: `roles/cloudfunctions.developer`
+- Storage Admin: `roles/storage.admin`
 
 ### APIs
 
 The project against which this module will be invoked must have the
 following APIs enabled:
 
-- Cloud Functions API
-- Cloud Pub/Sub API
-- Google Cloud Storage
+- Cloud Functions API: `cloudfunctions.googleapis.com`
+- Cloud Storage API: `storage-component.googleapis.com`
 
 The [Project Factory module][project-factory-module-site] can be used to
 provision projects with specific APIs activated.
@@ -176,7 +180,10 @@ from which the documentation will be generated:
 
 Run `make generate_docs` to update the documentation.
 
+[automatic-labelling-from-localhost-example]: examples/automatic-labelling-from-localhost
 [bundler-site]: https://bundler.io/
+[event-project-log-entry-submodule]: modules/event-project-log-entry
+[repository-function-submodule]: modules/repository-function
 [flake8-site]: https://pypi.org/project/flake8/
 [gofmt-site]: https://golang.org/cmd/gofmt/
 [hadolint-site]: https://github.com/hadolint/hadolint/
@@ -188,6 +195,6 @@ Run `make generate_docs` to update the documentation.
 [sample-variable-file]: test/fixtures/shared/terraform.tfvars.sample
 [shellcheck-site]: https://www.shellcheck.net/
 [terraform-docs-site]: https://github.com/segmentio/terraform-docs/releases/
-[terraform-provider-google-site]: https://github.com/terraform-providers/terraform-provider-google/
+[terraform-provider-gcp-site]: https://github.com/terraform-providers/terraform-provider-google/
 [terraform-site]: https://www.terraform.io/
 [terraform-validate-site]: https://www.terraform.io/docs/commands/validate.html

examples/automatic-labelling-from-localhost/README.md

@@ -0,0 +1,64 @@
+# Automatic Labelling from Localhost
+
+This example demonstrates how to use the
+[root module][root-module] and the
+[event-project-log-entry submodule][event-project-log-entry-submodule]
+to configure a system
+which responds to Compute VM creation events by labelling them with the
+principal email address of the account responsible for causing the events.
+
+## Usage
+
+To provision this example, populate `terraform.tfvars` with the [required variables][#inputs] and run the following commands within
+this directory:
+
+- `terraform init` to initialize the directory
+- `terraform plan` to generate the execution plan
+- `terraform apply` to apply the execution plan
+- `terraform destroy` to destroy the infrastructure
+
+[^]: (autogen_docs_start)
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-----:|:-----:|
+| project\_id | The ID of the project to which resources will be applied. | string | n/a | yes |
+| region | The region in which resources will be applied. | string | n/a | yes |
+| zone | The zone in which resources will be applied. | string | n/a | yes |
+
+[^]: (autogen_docs_end)
+
+## Requirements
+
+The following sections describe the requirements which must be met in
+order to invoke this module. The requirements of the
+[root module][root-module-requirements] and the
+[event-project-log-entry submodule][event-project-log-entry-submodule-requirements]
+must also be met.
+
+### Software Dependencies
+
+The following software dependencies must be installed on the system
+from which this module will be invoked:
+
+- [Terraform][terraform-site] v0.11.Z
+
+### IAM Roles
+
+The Service Account which will be used to invoke this module must have
+the following IAM roles:
+
+- Compute Instance Admin (v1): `roles/compute.instanceAdmin.v1`
+
+### APIs
+
+The project against which this module will be invoked must have the
+following APIs enabled:
+
+- Compute Engine API: `compute.googleapis.com`
+
+[event-project-log-entry-submodule-requirements]: ../../modules/event-project-log-entry/README.md#requirements
+[event-project-log-entry-submodule]: ../../modules/event-project-log-entry
+[root-module-requirements]: ../../README.md#requirements
+[root-module]: ../..

test/fixtures/automatic_labelling/main.tf → examples/automatic-labelling-from-localhost/main.tf

@@ -14,40 +14,61 @@
  * limitations under the License.
  */
 
+terraform {
+  required_version = "~> 0.11.0"
+}
+
 provider "archive" {
-  version = "~> 1.1"
+  version = "~> 1.0"
 }
 
 provider "google" {
-  version = "~> 1.20"
+  version = "~> 2.1"
 }
 
 provider "random" {
   version = "~> 2.0"
 }
 
 provider "null" {
-  version = "~> 2.0"
+  version = "~> 1.0"
 }
 
 resource "random_pet" "main" {
   separator = "-"
 }
 
-module "automatic_labelling" {
-  source = "../../../examples/automatic_labelling"
+module "event_project_log_entry" {
+  source = "../../modules/event-project-log-entry"
 
+  filter     = "protoPayload.@type=\"type.googleapis.com/google.cloud.audit.AuditLog\" protoPayload.methodName:insert operation.first=true"
+  name       = "${random_pet.main.id}"
   project_id = "${var.project_id}"
-  name       = "automatic-labelling-${random_pet.main.id}"
-  region     = "${var.region}"
 }
 
-resource "null_resource" "wait_for_cloud_functions_function" {
+module "localhost_function" {
+  source = "../.."
+
+  description = "Labels resource with owner information."
+  entry_point = "labelResource"
+
+  environment_variables = {
+    LABEL_KEY = "principal-email"
+  }
+
+  event_trigger    = "${module.event_project_log_entry.function_event_trigger}"
+  name             = "${random_pet.main.id}"
+  project_id       = "${var.project_id}"
+  region           = "${var.region}"
+  source_directory = "${path.module}/function_source"
+}
+
+resource "null_resource" "wait_for_function" {
   provisioner "local-exec" {
     command = "sleep 60"
   }
 
-  depends_on = ["module.automatic_labelling"]
+  depends_on = ["module.localhost_function"]
 }
 
 resource "google_compute_instance" "main" {
@@ -58,7 +79,7 @@ resource "google_compute_instance" "main" {
   }
 
   machine_type = "f1-micro"
-  name         = "unlabelled"
+  name         = "unlabelled-${random_pet.main.id}"
   zone         = "${var.zone}"
 
   network_interface = {
@@ -67,5 +88,5 @@ resource "google_compute_instance" "main" {
 
   project = "${var.project_id}"
 
-  depends_on = ["null_resource.wait_for_cloud_functions_function"]
+  depends_on = ["null_resource.wait_for_function"]
 }

examples/automatic-labelling-from-localhost/outputs.tf

@@ -0,0 +1,20 @@
+/**
+ * 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
+ *
+ *      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 "compute_instance_name" {
+  value       = "${google_compute_instance.main.name}"
+  description = "The name of the unlabelled Compute instance."
+}

examples/automatic-labelling-from-repository/README.md

@@ -0,0 +1,67 @@
+# Automatic Labelling from Repository
+
+This example demonstrates how to use the
+[repository-function submodule][repository-function-submodule] and the
+[event-project-log-entry submodule][event-project-log-entry-submodule]
+to configure a system
+which responds to Compute VM creation events by labelling them with the
+principal email address of the account responsible for causing the events.
+
+## Usage
+
+To provision this example, populate `terraform.tfvars` with the [required variables][#inputs] and run the following commands within
+this directory:
+
+- `terraform init` to initialize the directory
+- `terraform plan` to generate the execution plan
+- `terraform apply` to apply the execution plan
+- `terraform destroy` to destroy the infrastructure
+
+[^]: (autogen_docs_start)
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|:----:|:-----:|:-----:|
+| project\_id | The ID of the project to which resources will be applied. | string | n/a | yes |
+| region | The region in which resources will be applied. | string | n/a | yes |
+| zone | The zone in which resources will be applied. | string | n/a | yes |
+
+[^]: (autogen_docs_end)
+
+## Requirements
+
+The following sections describe the requirements which must be met in
+order to invoke this module. The
+[repository-function submodule requirements][repository-function-submodule-requirements]
+and the
+[event-project-log-entry submodule requirements][event-project-log-entry-submodule-requirements]
+must also be met.
+
+### Software Dependencies
+
+The following software dependencies must be installed on the system
+from which this module will be invoked:
+
+- [Terraform][terraform-site] v0.11.Z
+
+### IAM Roles
+
+The Service Account which will be used to invoke this module must have
+the following IAM roles:
+
+- Compute Instance Admin (v1): `roles/compute.instanceAdmin.v1`
+- Source Repository Admin: `roles/source.admin`
+
+### APIs
+
+The project against which this module will be invoked must have the
+following APIs enabled:
+
+- Cloud Source Repositories API: `sourcerepo.googleapis.com`
+- Compute Engine API: `compute.googleapis.com`
+
+[event-project-log-entry-submodule-requirements]: ../../modules/event-project-log-entry/README.md#requirements
+[event-project-log-entry-submodule]: ../../modules/event-project-log-entry
+[repository-function-submodule-requirements]: ../../modules/repository-function/README.md#requirements
+[repository-function-submodule]: ../../modules/repository-function