Merge pull request #4 from mineiros-io/soerenmartius/terradoc

Add terradoc definition
mineiros-io · Dec 15, 2021 · 5dc1b78 · 5dc1b78
2 parents 21755fb + 6c685d7
commit 5dc1b78
Show file tree

Hide file tree

Showing 3 changed files with 335 additions and 178 deletions.
diff --git a/README.md b/README.md
@@ -1,17 +1,22 @@
-[<img src="https://raw.githubusercontent.com/mineiros-io/brand/3bffd30e8bdbbde32c143e2650b2faa55f1df3ea/mineiros-primary-logo.svg" width="400"/>](https://mineiros.io/?ref=terraform-module-template)
+[<img src="https://raw.githubusercontent.com/mineiros-io/brand/3bffd30e8bdbbde32c143e2650b2faa55f1df3ea/mineiros-primary-logo.svg" width="400"/>](https://mineiros.io/?ref=terraform-google-billing-budget)
 
-[![Build Status](https://github.com/mineiros-io/terraform-module-template/workflows/Tests/badge.svg)](https://github.com/mineiros-io/terraform-module-template/actions)
-[![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/mineiros-io/terraform-module-template.svg?label=latest&sort=semver)](https://github.com/mineiros-io/terraform-module-template/releases)
+[![Build Status](https://github.com/mineiros-io/terraform-google-billing-budget/workflows/Tests/badge.svg)](https://github.com/mineiros-io/terraform-google-billing-budget/actions)
+[![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/mineiros-io/terraform-google-billing-budget.svg?label=latest&sort=semver)](https://github.com/mineiros-io/terraform-google-billing-budget/releases)
 [![Terraform Version](https://img.shields.io/badge/Terraform-1.x-623CE4.svg?logo=terraform)](https://github.com/hashicorp/terraform/releases)
-[![AWS Provider Version](https://img.shields.io/badge/AWS-3-F8991D.svg?logo=terraform)](https://github.com/terraform-providers/terraform-provider-aws/releases)
+[![Google Provider Version](https://img.shields.io/badge/google-3-1A73E8.svg?logo=terraform)](https://github.com/terraform-providers/terraform-provider-google/releases)
 [![Join Slack](https://img.shields.io/badge/slack-@mineiros--community-f32752.svg?logo=slack)](https://mineiros.io/slack)
 
-# terraform-module-template
+# terraform-google-monitoring-notification-channel
 
-A [Terraform] base module for [Amazon Web Services (AWS)][aws].
+A [Terraform] module to manage [notification channels](https://cloud.google.com/monitoring/support/notification-options)
+on [Google Cloud Platform (GCP)](https://cloud.google.com).
+
+A NotificationChannel is a medium through which an alert is delivered when
+a policy violation is detected. Examples of channels include email, SMS,
+and third-party messaging applications.
 
 **_This module supports Terraform version 1
-and is compatible with the Terraform AWS Provider version 3._**
+and is compatible with the Terraform Google Cloud Provider version 3._**
 
 This module is part of our Infrastructure as Code (IaC) framework
 that enables our users and customers to easily deploy and manage reusable,
@@ -26,8 +31,8 @@ secure, and production-grade cloud infrastructure.
     - [Module Configuration](#module-configuration)
 - [Module Attributes Reference](#module-attributes-reference)
 - [External Documentation](#external-documentation)
-  - [AWS Documentation IAM](#aws-documentation-iam)
-  - [Terraform AWS Provider Documentation](#terraform-aws-provider-documentation)
+  - [GCP Billing Budgets Documentation](#gcp-billing-budgets-documentation)
+  - [Terraform GCP Provider Documentation](#terraform-gcp-provider-documentation)
 - [Module Versioning](#module-versioning)
   - [Backwards compatibility in `0.0.z` and `0.y.z` version](#backwards-compatibility-in-00z-and-0yz-version)
 - [About Mineiros](#about-mineiros)
@@ -40,21 +45,28 @@ secure, and production-grade cloud infrastructure.
 
 This module implements the following Terraform resources
 
-- `google_resource`
-- `google_something_else`
-
-and supports additional features of the following modules:
-
-- [mineiros-io/something/google](https://github.com/mineiros-io/terraform-google-something)
+- `google_monitoring_notification_channel`
 
 ## Getting Started
 
-Most common usage of the module:
+Create a slack notification channel:
 
 ```hcl
-module "terraform-module-template" {
-  source = "git@github.com:mineiros-io/terraform-module-template.git?ref=v0.0.1"
-}
+module "terraform-google-billing-budget" {
+  source = "git@github.com:mineiros-io/terraform-google-monitoring-notification-channel.git?ref=v0.0.1"
+
+  type        = "slack"
+
+  display_name = "slack-alert"
+  description  = "An example Slack notification channel."
+
+  labels       = {
+    channel_name = "#alerts"
+  }
+
+  sensitive_labels = {
+    auth_token = "XXX"
+  }
 ```
 
 ## Module Argument Reference
@@ -65,6 +77,82 @@ See [variables.tf] and [examples/] for details and use-cases.
 
 #### Main Resource Configuration
 
+- [**`type`**](#var-type): *(**Required** `string`)*<a name="var-type"></a>
+
+  The type of the notification channel. Valid values are `email`, `slack`, `sms`, `webhook_basicauth` and `pagerduty`.
+
+- [**`project`**](#var-project): *(Optional `string`)*<a name="var-project"></a>
+
+  The ID of the project in which the resource belongs. If it is not set, the provider project is used.
+
+  Default is `null`.
+
+- [**`display_name`**](#var-display_name): *(Optional `string`)*<a name="var-display_name"></a>
+
+  An human-readable name for this notification channel. It is recommended that you specify a non-empty and unique name in order to make it easier to identify the channels in your project, though this is not enforced. The display name is limited to 512 Unicode characters.
+
+  Default is `null`.
+
+- [**`description`**](#var-description): *(Optional `string`)*<a name="var-description"></a>
+
+  An optional human-readable description of this notification channel. This description may provide additional details, beyond the display name, for the channel. This may not exceed 1024 Unicode characters.
+
+  Default is `"Notification managed by the mineiros-io/terraform-google-monitoring-notification-channel Terraform module."`.
+
+- [**`enabled`**](#var-enabled): *(Optional `bool`)*<a name="var-enabled"></a>
+
+  Whether notifications are forwarded to the described channel. This makes it possible to disable delivery of notifications to a particular channel without removing the channel from all alerting policies that reference the channel. This is a more convenient approach when the change is temporary and you want to receive notifications from the same set of alerting policies on the channel at some point in the future.
+
+  Default is `true`.
+
+- [**`labels`**](#var-labels): *(Optional `string`)*<a name="var-labels"></a>
+
+  Configuration fields that define the channel and its behavior. Labels with sensitive data should be configured via the 'sensitive_labels' block.
+
+  Default is `{}`.
+
+  Example:
+
+  ```hcl
+  labels = {
+    email_address = "address@example.com"
+  }
+  ```
+
+- [**`user_labels`**](#var-user_labels): *(Optional `string`)*<a name="var-user_labels"></a>
+
+  User-supplied key/value data that does not need to conform to the corresponding notification channel schema, unlike the `labels` field. The field can contain up to 64 entries. Each key and value is limited to 63 Unicode characters or 128 bytes, whichever is smaller. Labels and values can contain only lowercase letters, numerals, underscores, and dashes. Keys must begin with a letter.
+
+  Default is `{}`.
+
+- [**`sensitive_labels`**](#var-sensitive_labels): *(Optional `object(sensitive_labels)`)*<a name="var-sensitive_labels"></a>
+
+  Different notification type behaviors are configured primarily using the the labels field on this resource. This block contains the labels which contain secrets or passwords so that they can be marked sensitive and hidden from plan output. The name of the field, eg: password, will be the key in the labels map in the api request. Credentials may not be specified in both locations and will cause an error. Changing from one location to a different credential configuration in the config will require an apply to update state.
+
+  Default is `null`.
+
+  Example:
+
+  ```hcl
+  sensitive_labels = {
+    auth_token = "example-token"
+  }
+  ```
+
+  The object accepts the following attributes:
+
+  - [**`auth_token`**](#attr-auth_token-1): *(Optional `string`)*<a name="attr-auth_token-1"></a>
+
+    An authorization token for a notification channel. Channel types that support this field include: `slack` Note: This property is sensitive and will not be displayed in the plan.
+
+  - [**`password`**](#attr-password-1): *(Optional `string`)*<a name="attr-password-1"></a>
+
+    An password for a notification channel. Channel types that support this field include: `webhook_basicauth` Note: This property is sensitive and will not be displayed in the plan.
+
+  - [**`service_key`**](#attr-service_key-1): *(Optional `string`)*<a name="attr-service_key-1"></a>
+
+    An servicekey token for a notification channel. Channel types that support this field include: `pagerduty` Note: This property is sensitive and will not be displayed in the plan.
+
 #### Module Configuration
 
 - [**`module_enabled`**](#var-module_enabled): *(Optional `bool`)*<a name="var-module_enabled"></a>
@@ -73,21 +161,44 @@ See [variables.tf] and [examples/] for details and use-cases.
 
   Default is `true`.
 
-- [**`module_tags`**](#var-module_tags): *(Optional `map(string)`)*<a name="var-module_tags"></a>
+- [**`module_timeouts`**](#var-module_timeouts): *(Optional `object(google_monitoring_notification_channel)`)*<a name="var-module_timeouts"></a>
 
-  A map of tags that will be applied to all created resources that accept tags. Tags defined with 'module_tags' can be overwritten by resource-specific tags.
+  How long certain operations (per resource type) are allowed to take before being considered to have failed.
 
   Default is `{}`.
 
   Example:
 
   ```hcl
-  module_tags = {
-    environment = "staging"
-    team        = "platform"
+  module_timeouts = {
+    google_monitoring_notification_channel = {
+      create = "4m"
+      update = "4m"
+      delete = "4m"
+    }
   }
   ```
 
+  The object accepts the following attributes:
+
+  - [**`google_monitoring_notification_channel`**](#attr-google_monitoring_notification_channel-1): *(Optional `object(timeouts)`)*<a name="attr-google_monitoring_notification_channel-1"></a>
+
+    Timeout for the `google_monitoring_notification_channel` resource.
+
+    The object accepts the following attributes:
+
+    - [**`create`**](#attr-create-2): *(Optional `string`)*<a name="attr-create-2"></a>
+
+      Timeout for `create` operations.
+
+    - [**`update`**](#attr-update-2): *(Optional `string`)*<a name="attr-update-2"></a>
+
+      Timeout for `update` operations.
+
+    - [**`delete`**](#attr-delete-2): *(Optional `string`)*<a name="attr-delete-2"></a>
+
+      Timeout for `delete` operations.
+
 - [**`module_depends_on`**](#var-module_depends_on): *(Optional `list(dependencies)`)*<a name="var-module_depends_on"></a>
 
   A list of dependencies. Any object can be _assigned_ to this list to define a hidden external dependency.
@@ -96,7 +207,7 @@ See [variables.tf] and [examples/] for details and use-cases.
 
   ```hcl
   module_depends_on = [
-    aws_vpc.vpc
+    google_monitoring_alert_policy.alert-policy 
   ]
   ```
 
@@ -108,24 +219,15 @@ The following attributes are exported in the outputs of the module:
 
   Whether this module is enabled.
 
-- **`module_tags`**
-
-  The map of tags that are being applied to all created resources that accept tags.
-
 ## External Documentation
 
-### AWS Documentation IAM
+### GCP Billing Budgets Documentation
 
-- https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html
-- https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html
-- https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html
+- https://cloud.google.com/monitoring/support/notification-options
 
-### Terraform AWS Provider Documentation
+### Terraform GCP Provider Documentation
 
-- https://www.terraform.io/docs/providers/aws/r/iam_role.html
-- https://www.terraform.io/docs/providers/aws/r/iam_role_policy.html
-- https://www.terraform.io/docs/providers/aws/r/iam_role_policy_attachment.html
-- https://www.terraform.io/docs/providers/aws/r/iam_instance_profile.html
+- https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/monitoring_notification_channel
 
 ## Module Versioning
 
@@ -180,20 +282,19 @@ Copyright &copy; 2020-2022 [Mineiros GmbH][homepage]
 
 <!-- References -->
 
-[homepage]: https://mineiros.io/?ref=terraform-module-template
+[homepage]: https://mineiros.io/?ref=terraform-google-billing-budget
 [hello@mineiros.io]: mailto:hello@mineiros.io
 [badge-license]: https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg
 [releases-terraform]: https://github.com/hashicorp/terraform/releases
-[releases-aws-provider]: https://github.com/terraform-providers/terraform-provider-aws/releases
 [apache20]: https://opensource.org/licenses/Apache-2.0
 [slack]: https://mineiros.io/slack
 [terraform]: https://www.terraform.io
-[aws]: https://aws.amazon.com/
+[gcp]: https://cloud.google.com
 [semantic versioning (semver)]: https://semver.org/
-[variables.tf]: https://github.com/mineiros-io/terraform-module-template/blob/main/variables.tf
-[examples/]: https://github.com/mineiros-io/terraform-module-template/blob/main/examples
-[issues]: https://github.com/mineiros-io/terraform-module-template/issues
-[license]: https://github.com/mineiros-io/terraform-module-template/blob/main/LICENSE
-[makefile]: https://github.com/mineiros-io/terraform-module-template/blob/main/Makefile
-[pull requests]: https://github.com/mineiros-io/terraform-module-template/pulls
-[contribution guidelines]: https://github.com/mineiros-io/terraform-module-template/blob/main/CONTRIBUTING.md
+[variables.tf]: https://github.com/mineiros-io/terraform-google-billing-budget/blob/main/variables.tf
+[examples/]: https://github.com/mineiros-io/terraform-google-billing-budget/blob/main/examples
+[issues]: https://github.com/mineiros-io/terraform-google-billing-budget/issues
+[license]: https://github.com/mineiros-io/terraform-google-billing-budget/blob/main/LICENSE
+[makefile]: https://github.com/mineiros-io/terraform-google-billing-budget/blob/main/Makefile
+[pull requests]: https://github.com/mineiros-io/terraform-google-billing-budget/pulls
+[contribution guidelines]: https://github.com/mineiros-io/terraform-google-billing-budget/blob/main/CONTRIBUTING.md