feat: Add Essential Contacts support (#617)

* initial commit - module and example

* initial commit - module and example

added testing

updating test

docs update

whitespace fixes

linting fixes

title change

cleanup

composed essential_contacts submodule in main module

whitespace

added essential_contacts to variables

replace EC list variable with map

re-wrote tests

* verify version = false

* typo

Co-authored-by: Bharath KKB <[email protected]>

* remove essential contacts from old test suite

* update to go test suite

* formatting

* typo

* shortened test command

* use example over fixture

* remove fixture

* typo

* remove ruby tests

* update go packages

* fix example references

* better test commands

* formatting

* update go

* import utils

* variable description names

* var description updates

Co-authored-by: Bharath KKB <[email protected]>

.kitchen.yml

@@ -76,6 +76,7 @@ suites:
           controls:
           - svpc
 
+
 # Disabled due to issue #275
 # (https://github.com/terraform-google-modules/terraform-google-project-factory/issues/275)
 #  - name: full

README.md

@@ -134,12 +134,14 @@ determining that location is as follows:
 | disable\_services\_on\_destroy | Whether project services will be disabled when the resources are destroyed | `bool` | `true` | no |
 | domain | The domain name (optional). | `string` | `""` | no |
 | enable\_shared\_vpc\_host\_project | If this project is a shared VPC host project. If true, you must *not* set svpc\_host\_project\_id variable. Default is false. | `bool` | `false` | no |
+| essential\_contacts | A mapping of users or groups to be assigned as Essential Contacts to the project, specifying a notification category | `map(list(string))` | `{}` | no |
 | folder\_id | The ID of a folder to host this project | `string` | `""` | no |
 | grant\_services\_network\_role | Whether or not to grant service agents the network roles on the host project | `bool` | `true` | no |
 | grant\_services\_security\_admin\_role | Whether or not to grant Kubernetes Engine Service Agent the Security Admin role on the host project so it can manage firewall rules | `bool` | `false` | no |
 | group\_name | A group to control the project by being assigned group\_role (defaults to project editor) | `string` | `""` | no |
 | group\_role | The role to give the controlling group (group\_name) over the project (defaults to project editor) | `string` | `"roles/editor"` | no |
 | labels | Map of labels for project | `map(string)` | `{}` | no |
+| language\_tag | Language code to be used for essential contacts notifications | `string` | `"en-US"` | no |
 | lien | Add a lien on the project to prevent accidental deletion | `bool` | `false` | no |
 | name | The name for the project | `string` | n/a | yes |
 | org\_id | The organization ID. | `string` | n/a | yes |

build/int.cloudbuild.yaml

@@ -104,6 +104,28 @@ steps:
   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 budget-local']
 
+# essential contacts
+- id: init-essential-contacts-example
+  waitFor:
+    - prepare
+  name: 'gcr.io/cloud-foundation-cicd/$_DOCKER_IMAGE_DEVELOPER_TOOLS:$_DOCKER_TAG_VERSION_DEVELOPER_TOOLS'
+  args: ['/bin/bash', '-c', 'cft test run TestEssentialContactsExample --stage init --verbose']
+- id: apply-essential-contacts-example
+  waitFor:
+    - init-essential-contacts-example
+  name: 'gcr.io/cloud-foundation-cicd/$_DOCKER_IMAGE_DEVELOPER_TOOLS:$_DOCKER_TAG_VERSION_DEVELOPER_TOOLS'
+  args: ['/bin/bash', '-c', 'cft test run TestEssentialContactsExample --stage apply --verbose']
+- id: verify-essential-contacts-example
+  waitFor:
+    - apply-essential-contacts-example
+  name: 'gcr.io/cloud-foundation-cicd/$_DOCKER_IMAGE_DEVELOPER_TOOLS:$_DOCKER_TAG_VERSION_DEVELOPER_TOOLS'
+  args: ['/bin/bash', '-c', 'cft test run TestEssentialContactsExample --stage verify --verbose']
+- id: destroy-essential-contacts-example
+  waitFor:
+    - verify-essential-contacts-example
+  name: 'gcr.io/cloud-foundation-cicd/$_DOCKER_IMAGE_DEVELOPER_TOOLS:$_DOCKER_TAG_VERSION_DEVELOPER_TOOLS'
+  args: ['/bin/bash', '-c', 'cft test run TestEssentialContactsExample --stage destroy --verbose']
+
 - id: create dynamic-shared-vpc-local
   waitFor:
       - prepare

examples/essential_contacts/README.md

@@ -0,0 +1,22 @@
+# Essential Contacts
+
+This example illustrates how to use the essential_contacts submodule to assign emails to specific notification types and languages.
+
+<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| billing\_account | Billing account ID. | `string` | n/a | yes |
+| folder\_id | The ID of a folder to host this project. | `string` | n/a | yes |
+| org\_id | The organization ID. | `string` | n/a | yes |
+| project\_id | The GCP project to create Essential Contacts in | `string` | n/a | yes |
+| random\_string\_for\_testing | A random string of characters to be appended to resource names to ensure uniqueness | `string` | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| project\_id | The GCP project with Essential Contacts |
+
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

examples/essential_contacts/main.tf

@@ -0,0 +1,42 @@
+/**
+ * Copyright 2021 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 "project-factory" {
+  source = "../../"
+
+  name              = "pf-ci-test-ec-${var.random_string_for_testing}"
+  random_project_id = true
+  org_id            = var.org_id
+  folder_id         = var.folder_id
+  billing_account   = var.billing_account
+
+  activate_apis = [
+    "compute.googleapis.com",
+    "container.googleapis.com",
+    "essentialcontacts.googleapis.com"
+  ]
+
+  essential_contacts = {
+    "[email protected]"    = ["ALL"],
+    "[email protected]" = ["SECURITY", "TECHNICAL"],
+    "[email protected]"      = ["TECHNICAL"]
+  }
+
+  language_tag = "en-US"
+
+  default_service_account     = "DISABLE"
+  disable_services_on_destroy = false
+}

examples/essential_contacts/outputs.tf

@@ -0,0 +1,20 @@
+/**
+ * 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 "project_id" {
+  value       = module.project-factory.project_id
+  description = "The GCP project with Essential Contacts"
+}

examples/essential_contacts/variables.tf

@@ -0,0 +1,40 @@
+/**
+ * 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" {
+  type        = string
+  description = "The GCP project to create Essential Contacts in"
+}
+
+variable "org_id" {
+  type        = string
+  description = "The organization ID."
+}
+
+variable "folder_id" {
+  type        = string
+  description = "The ID of a folder to host this project."
+}
+
+variable "billing_account" {
+  type        = string
+  description = "Billing account ID."
+}
+
+variable "random_string_for_testing" {
+  type        = string
+  description = "A random string of characters to be appended to resource names to ensure uniqueness"
+}

examples/essential_contacts/versions.tf

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+
+terraform {
+  required_version = ">= 0.13"
+  required_providers {
+    google = {
+      source  = "hashicorp/google"
+      version = "~> 4.0"
+    }
+    google-beta = {
+      source  = "hashicorp/google-beta"
+      version = "~> 4.0"
+    }
+  }
+}

main.tf

@@ -107,3 +107,14 @@ module "quotas" {
   project_id      = module.project-factory.project_id
   consumer_quotas = var.consumer_quotas
 }
+
+/******************************************
+  Essential Contacts to create if set
+ *****************************************/
+module "essential_contacts" {
+  source = "./modules/essential_contacts"
+
+  project_id         = module.project-factory.project_id
+  essential_contacts = var.essential_contacts
+  language_tag       = var.language_tag
+}

modules/essential_contacts/README.md

@@ -0,0 +1,46 @@
+# Essential Contacts configuration
+
+This module uses the [`google_essential_contacts_contact`](https://www.terraform.io/docs/providers/google/r/google_project_service.html)
+resource to add contact emails which will receive notification types from Google Cloud, using specified subcription types.
+
+## Prerequisites
+
+1. Service account used to run Terraform has permission to administer Essential Contacts:
+[`roles/essentialcontacts.admin`](https://cloud.google.com/iam/docs/understanding-roles#other-roles).
+2. The target project has the Essential Contacts API enabled `essentialcontacts.googleapis.com `
+
+## Example Usage
+```
+module "essential_contacts" {
+  source     = "../../modules/essential_contacts"
+  project_id = var.project_id
+
+  essential_contacts = {
+    "[email protected]"    = ["ALL"],
+    "[email protected]" = ["SECURITY", "TECHNICAL"],
+    "[email protected]"      = ["TECHNICAL"]
+  }
+
+  language_tag = "en-US"
+}
+```
+
+See [examples/essential_contacts](./examples/essential_contacts) for a full example.
+
+<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| essential\_contacts | A mapping of users or groups to be assigned as Essential Contacts to the project, specifying a notification category | `map(list(string))` | `{}` | no |
+| language\_tag | Language code to be used for essential contacts notifiactions | `string` | n/a | yes |
+| project\_id | The GCP project you want to send Essential Contacts notifications for | `any` | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| essential\_contacts | Essential Contact resources created |
+| project\_id | The GCP project you want to enable APIs on |
+
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

modules/essential_contacts/main.tf

@@ -0,0 +1,28 @@
+/**
+ * Copyright 2022 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.
+ */
+
+/******************************************
+  Essential Contact configuration
+ *****************************************/
+
+resource "google_essential_contacts_contact" "contact" {
+  for_each = var.essential_contacts
+
+  parent                              = "projects/${var.project_id}"
+  email                               = each.key
+  language_tag                        = var.language_tag
+  notification_category_subscriptions = each.value
+}

modules/essential_contacts/outputs.tf

@@ -0,0 +1,25 @@
+/**
+ * Copyright 2022 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 "essential_contacts" {
+  description = "Essential Contact resources created"
+  value       = [for contact in google_essential_contacts_contact.contact : contact.name]
+}
+
+output "project_id" {
+  description = "The GCP project you want to enable APIs on"
+  value       = var.project_id
+}

modules/essential_contacts/variables.tf

@@ -0,0 +1,30 @@
+/**
+ * Copyright 2022 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 GCP project you want to send Essential Contacts notifications for"
+}
+
+variable "essential_contacts" {
+  description = "A mapping of users or groups to be assigned as Essential Contacts to the project, specifying a notification category"
+  type        = map(list(string))
+  default     = {}
+}
+
+variable "language_tag" {
+  description = "Language code to be used for essential contacts notifiactions"
+  type        = string
+}

modules/essential_contacts/versions.tf

@@ -0,0 +1,35 @@
+/**
+ * Copyright 2022 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.
+ */
+
+terraform {
+  required_version = ">= 0.13"
+  required_providers {
+    google = {
+      source  = "hashicorp/google"
+      version = ">= 3.43, <5.0"
+    }
+    google-beta = {
+      source  = "hashicorp/google-beta"
+      version = ">= 3.43, <5.0"
+    }
+  }
+  provider_meta "google" {
+    module_name = "blueprints/terraform/terraform-google-project-factory:essential_contacts/v11.1.1"
+  }
+  provider_meta "google-beta" {
+    module_name = "blueprints/terraform/terraform-google-project-factory:essential_contacts/v11.1.1"
+  }
+}