feat: Add usage example for monitoring alerts on KMS key versions (#162)

examples/autokey_example/main.tf

@@ -16,7 +16,7 @@
 
 module "autokey" {
   source  = "terraform-google-modules/kms/google//modules/autokey"
-  version = "3.1.0"
+  version = "~> 3.2"
 
   project_id            = var.project_id
   autokey_folder_number = var.folder_id

examples/import_only_example/main.tf

@@ -21,7 +21,8 @@ resource "random_pet" "main" {
 }
 
 module "kms" {
-  source = "../.."
+  source  = "terraform-google-modules/kms/google"
+  version = "~> 3.2"
 
   project_id = var.project_id
   keyring    = random_pet.main.id

examples/monitoring_alerts/README.md

@@ -0,0 +1,24 @@
+# Monitoring Alert Example
+
+This example provides monitoring e-mail alerts for KMS key versions scheduled for destruction. If multiple key versions are deleted in less than 5 minutes, a single notification will be sent.
+
+<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| email\_addresses\_to\_be\_notified | Email addresses used for sending notifications to. | `list(string)` | n/a | yes |
+| location | Location to create the KMS key and keyring. | `string` | `"us-central1"` | no |
+| monitor\_all\_keys\_in\_the\_project | True for all KMS key versions under the same project to be monitored, false for only the KMS key version created in this example to be monitored. Default: false. | `bool` | n/a | yes |
+| project\_id | The ID of the project in which to provision resources. | `string` | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| key | The version of the created KMS key. |
+| keyring | The keyring created. |
+| notification\_channel\_names | Notification channel names. |
+| project\_id | GCP Project ID where key version was created. |
+
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

examples/monitoring_alerts/main.tf

@@ -0,0 +1,82 @@
+/**
+ * Copyright 2024 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.
+ */
+
+/**
+ * Send a warning email when a KMS key version is scheduled for destruction.
+ * If multiple key versions are deleted in less than 5 minutes, a single notification will be sent.
+ */
+
+# See all the request types available for google.cloud.kms.v1 here: https://cloud.google.com/kms/docs/reference/rpc/google.cloud.kms.v1. For this example specifically we are monitoring and alerting DestroyCryptoKeyVersionRequest.
+locals {
+  all_keys_filter   = "protoPayload.request.@type=\"type.googleapis.com/google.cloud.kms.v1.DestroyCryptoKeyVersionRequest\""
+  single_key_filter = "${local.all_keys_filter} AND protoPayload.request.name=~\"${values(module.kms.keys)[0]}/.*\""
+  # It's possible to replace "${values(module.kms.keys)[0]}" with your own existing KMS key's name. It's not required to create a new KMS key to take leverage from this example.
+}
+
+resource "random_string" "suffix" {
+  length  = 4
+  special = false
+  upper   = false
+}
+
+module "kms" {
+  source  = "terraform-google-modules/kms/google"
+  version = "~> 3.2"
+
+  project_id      = var.project_id
+  keyring         = "alert-keyring-${random_string.suffix.result}"
+  location        = var.location
+  keys            = ["alert-key"]
+  prevent_destroy = false
+}
+
+resource "google_monitoring_alert_policy" "main" {
+  project      = var.project_id
+  display_name = "KMS Key Version Destruction Alert"
+  documentation {
+    content = "KMS Key Version alert: one or more key versions from ${var.project_id} project were scheduled for destruction."
+  }
+  combiner = "OR"
+  conditions {
+    display_name = "Destroy condition"
+    condition_matched_log {
+      filter = var.monitor_all_keys_in_the_project ? local.all_keys_filter : local.single_key_filter
+    }
+  }
+
+  alert_strategy {
+    notification_rate_limit {
+      period = "300s"
+    }
+  }
+
+  notification_channels = [for email_ch in google_monitoring_notification_channel.email_channel : email_ch.name]
+
+  severity = "WARNING"
+}
+
+resource "google_monitoring_notification_channel" "email_channel" {
+  for_each = toset(var.email_addresses_to_be_notified)
+
+  project      = var.project_id
+  display_name = "KMS version scheduled for destruction alert channel"
+  type         = "email"
+  description  = "Sends email notifications for KMS key versions scheduled for destruction alerts"
+
+  labels = {
+    email_address = each.value
+  }
+}

examples/monitoring_alerts/outputs.tf

@@ -0,0 +1,35 @@
+/**
+ * Copyright 2024 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 "key" {
+  value       = values(module.kms.keys)[0]
+  description = "The version of the created KMS key."
+}
+
+output "keyring" {
+  value       = module.kms.keyring_name
+  description = "The keyring created."
+}
+
+output "project_id" {
+  value       = var.project_id
+  description = "GCP Project ID where key version was created."
+}
+
+output "notification_channel_names" {
+  value       = [for channel in google_monitoring_notification_channel.email_channel : channel.name]
+  description = "Notification channel names."
+}

examples/monitoring_alerts/variables.tf

@@ -0,0 +1,36 @@
+/**
+ * Copyright 2024 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 ID of the project in which to provision resources."
+  type        = string
+}
+
+variable "monitor_all_keys_in_the_project" {
+  type        = bool
+  description = "True for all KMS key versions under the same project to be monitored, false for only the KMS key version created in this example to be monitored. Default: false."
+}
+
+variable "email_addresses_to_be_notified" {
+  type        = list(string)
+  description = "Email addresses used for sending notifications to."
+}
+
+variable "location" {
+  type        = string
+  description = "Location to create the KMS key and keyring."
+  default     = "us-central1"
+}

test/fixtures/monitoring_alerts_on_project/main.tf

@@ -0,0 +1,23 @@
+/**
+ * Copyright 2024 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 "monitoring_alert_on_project" {
+  source = "../../../examples/monitoring_alerts"
+
+  monitor_all_keys_in_the_project = true
+  project_id                      = var.project_id
+  email_addresses_to_be_notified  = ["email@example.com", "email2@example.com"]
+}

test/fixtures/monitoring_alerts_on_project/outputs.tf

@@ -0,0 +1,35 @@
+/**
+ * Copyright 2024 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 "key" {
+  value       = module.monitoring_alert_on_project.key
+  description = "The version of the created KMS key."
+}
+
+output "keyring" {
+  value       = module.monitoring_alert_on_project.keyring
+  description = "The keyring created."
+}
+
+output "project_id" {
+  value       = module.monitoring_alert_on_project.project_id
+  description = "GCP Project ID where key version was created."
+}
+
+output "notification_channel_names" {
+  value       = module.monitoring_alert_on_project.notification_channel_names
+  description = "Notification channel names."
+}

test/fixtures/monitoring_alerts_on_project/variables.tf

@@ -0,0 +1,20 @@
+/**
+ * Copyright 2024 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 ID of the project in which to provision resources."
+  type        = string
+}

test/fixtures/monitoring_alerts_specific_key/main.tf

@@ -0,0 +1,23 @@
+/**
+ * Copyright 2024 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 "monitoring_alert_specific_key" {
+  source = "../../../examples/monitoring_alerts"
+
+  monitor_all_keys_in_the_project = false
+  project_id                      = var.project_id
+  email_addresses_to_be_notified  = ["email@example.com", "email2@example.com"]
+}

test/fixtures/monitoring_alerts_specific_key/outputs.tf

@@ -0,0 +1,35 @@
+/**
+ * Copyright 2024 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 "key" {
+  value       = module.monitoring_alert_specific_key.key
+  description = "The version of the created KMS key."
+}
+
+output "keyring" {
+  value       = module.monitoring_alert_specific_key.keyring
+  description = "The keyring created."
+}
+
+output "project_id" {
+  value       = module.monitoring_alert_specific_key.project_id
+  description = "GCP Project ID where key version was created."
+}
+
+output "notification_channel_names" {
+  value       = module.monitoring_alert_specific_key.notification_channel_names
+  description = "Notification channel names."
+}

test/fixtures/monitoring_alerts_specific_key/variables.tf

@@ -0,0 +1,20 @@
+/**
+ * Copyright 2024 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 ID of the project in which to provision resources."
+  type        = string
+}