README.yaml

---
#
# This is the canonical configuration for the `README.md`
# Run `make readme` to rebuild the `README.md`
#

# Name of this project
name: terraform-datadog-platform

# Tags of this project
tags:
  - terraform
  - terraform-modules
  - monitor
  - datadog
  - monitoring
  - synthetics
  - rbac
  - role
  - permission

# Categories of this project
categories:
  - terraform-modules/monitoring

# Logo for this project
#logo: docs/logo.png

# License of this project
license: "APACHE2"

# Canonical GitHub repo
github_repo: cloudposse/terraform-datadog-platform

# Badges to display
badges:
  - name: "Latest Release"
    image: "https://img.shields.io/github/release/cloudposse/terraform-datadog-platform.svg"
    url: "https://github.com/cloudposse/terraform-datadog-platform/releases/latest"
  - name: "Slack Community"
    image: "https://slack.cloudposse.com/badge.svg"
    url: "https://slack.cloudposse.com"

related:
  - name: "terraform-aws-datadog-integration"
    description: "Terraform module to configure Datadog AWS integration"
    url: "https://github.com/cloudposse/terraform-aws-datadog-integration"
  - name: "terraform-yaml-config"
    description: "Terraform module to convert local and remote YAML configuration templates into Terraform lists and maps"
    url: "https://github.com/cloudposse/terraform-yaml-config"

# Short description of this project
description: |-
  Terraform module to provision Datadog resources.

  The module consists of the following submodules:

    - [monitors](modules/monitors) - to provision Datadog [monitors](https://docs.datadoghq.com/api/v1/monitors/)
    - [synthetics](modules/synthetics) - to provision Datadog [synthetics](https://docs.datadoghq.com/synthetics/)
    - [permissions](modules/permissions) - to look up all available Datadog [permissions](https://docs.datadoghq.com/account_management/rbac/permissions/)
    - [roles](modules/roles) - to provision Datadog [roles](https://docs.datadoghq.com/account_management/rbac)

introduction: |-
  Datadog resources (monitors, roles, etc.) are defined as [catalog](catalog) of YAML configuration files.

  We maintain a comprehensive [catalog](catalog) of Datadog resources and welcome contributions via pull request!

  The [examples/complete](examples/complete) in this module uses the catalog to provision the monitors on Datadog.

  The [examples/synthetics](examples/synthetics) shows how to provision synthetics on Datadog for synthetic monitoring.

  The [examples/rbac](examples/rbac) shows how to use custom RBAC to provision Datadog roles with permissions and assign roles to monitors.


references:
  - name: "Terraform Datadog monitor resources"
    description: "Provides a Datadog monitor resource. Used to create and manage Datadog monitors"
    url: "https://registry.terraform.io/providers/DataDog/datadog/latest/docs/resources/monitor"

  - name: "Create a monitor"
    description: "Create datadog monitors"
    url: "https://docs.datadoghq.com/api/v1/monitors/#create-a-monitor"

  - name: "Terraform Datadog role resources"
    description: "Provides a Datadog role resource. Used to create and manage Datadog roles"
    url: "https://registry.terraform.io/providers/DataDog/datadog/latest/docs/resources/role"

  - name: "Datadog permissions"
    description: "Use this data source to retrieve the list of Datadog permissions by name and their corresponding ID, for use in the role resource"
    url: "https://registry.terraform.io/providers/DataDog/datadog/latest/docs/data-sources/permissions"

  - name: "Role Based Access Control"
    description: "Roles categorize users and define what account permissions those users have, such as what data they can read or what account assets they can modify"
    url: "https://docs.datadoghq.com/account_management/rbac"

# How to use this project
usage: |-

  Provision Datadog monitors from the catalog of YAML definitions:

  ```hcl
    module "monitor_configs" {
      source  = "cloudposse/config/yaml"
      version = "0.8.1"

      map_config_local_base_path = path.module
      map_config_paths           = var.monitor_paths

      context = module.this.context
    }

    module "datadog_monitors" {
      source = "cloudposse/platform/datadog//modules/monitors"
      # version = "x.x.x"

      datadog_monitors     = module.monitor_configs.map_configs
      alert_tags           = var.alert_tags
      alert_tags_separator = var.alert_tags_separator

      context = module.this.context
   }
  ```

  Provision Datadog synthetics:

  ```hcl
    module "synthetic_configs" {
      source  = "cloudposse/config/yaml"
      version = "0.8.1"

      map_config_local_base_path = path.module
      map_config_paths           = var.synthetic_paths

      context = module.this.context
    }

    module "datadog_synthetics" {
      source = "cloudposse/platform/datadog//modules/synthetics"
      # version = "x.x.x"

      datadog_synthetics   = module.synthetic_configs.map_configs
      alert_tags           = var.alert_tags
      alert_tags_separator = var.alert_tags_separator

      context = module.this.context
    }
  ```

  Provision Datadog monitors, Datadog roles with defined permissions, and assign roles to monitors:

  ```hcl
    module "monitor_configs" {
      source  = "cloudposse/config/yaml"
      version = "0.8.1"

      map_config_local_base_path = path.module
      map_config_paths           = var.monitor_paths

      context = module.this.context
    }

    module "role_configs" {
      source  = "cloudposse/config/yaml"
      version = "0.8.1"

      map_config_local_base_path = path.module
      map_config_paths           = var.role_paths

      context = module.this.context
    }

    locals {
      monitors_write_role_name    = module.datadog_roles.datadog_roles["monitors-write"].name
      monitors_downtime_role_name = module.datadog_roles.datadog_roles["monitors-downtime"].name

      monitors_roles_map = {
        aurora-replica-lag              = [local.monitors_write_role_name, local.monitors_downtime_role_name]
        ec2-failed-status-check         = [local.monitors_write_role_name, local.monitors_downtime_role_name]
        redshift-health-status          = [local.monitors_downtime_role_name]
        k8s-deployment-replica-pod-down = [local.monitors_write_role_name]
      }
    }

    module "datadog_roles" {
      source = "cloudposse/platform/datadog//modules/roles"
      # version = "x.x.x"

      datadog_roles = module.role_configs.map_configs

      context = module.this.context
    }

    module "datadog_monitors" {
      source = "cloudposse/platform/datadog//modules/monitors"
      # version = "x.x.x"

      datadog_monitors     = module.monitor_configs.map_configs
      alert_tags           = var.alert_tags
      alert_tags_separator = var.alert_tags_separator
      restricted_roles_map = local.monitors_roles_map

      context = module.this.context
    }
  ```

examples: |-
  Review the [examples](examples) folder to see how to use the Datadog modules.

include:
  - "docs/targets.md"
  - "docs/terraform.md"

# Contributors to this project
contributors:
  - name: "Erik Osterman"
    github: "osterman"
  - name: "Andriy Knysh"
    github: "aknysh"
  - name: "Vladimir"
    github: "SweetOps"
  - name: "Yonatan Koren"
    github: "korenyoni"