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
  - slo
  - child-organization

# 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)
    - [slo](modules/slo) - to provision Datadog [Service Level Objectives](https://docs.datadoghq.com/monitors/service_level_objectives/)
    - [child_organization](modules/child_organization) - to provision Datadog [child organizations](https://docs.datadoghq.com/account_management/multi_organization/)
    - [organization_settings](modules/organization_settings) - to manage Datadog organization's settings

  __Notes on Datadog child organizations:__

  * Users can be added to the parent-organization and/or multiple child-organizations and switch between them from the user account settings menu
  * The parent-organization can view the usage of individual child-organizations, allowing them to track trends in usage
  * The Multi-organization account feature is not enabled by default. Contact Datadog support to have it enabled
  * Free and Trial organizations cannot enable SAML
  * We can only create Datadog child organizations with terraform, but cannot destroy them. When trying to destroy, the following error is thrown:
    ```
      Warning: Cannot delete organization.

      Remove organization by contacting support (https://docs.datadoghq.com/help).
    ```

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.

  The [examples/slo](examples/slo) shows how to provision Service Level Objectives on Datadog for SLO monitoring.

  The [examples/child_organization](examples/child_organization) shows how to provision Datadog child organizations.

  The [examples/organization_settings](examples/organization_settings) shows how to provision Datadog organization settings.

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"

  - name: "Managing Multiple-Organization Accounts"
    description: "It is possible to manage multiple child-organizations from one parent-organization account. This is typically used by Managed Service Providers that have customers which should not have access to each others' data"
    url: "https://docs.datadoghq.com/account_management/multi_organization"

# 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
  locals {
    synthetics_files = flatten([for p in var.synthetic_paths : fileset(path.module, p)])
    synthetics_list  = [for f in local.synthetics_files : yamldecode(file(f))]
    synthetics_map   = merge(local.synthetics_list...)
  }

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

    datadog_synthetics   = local.synthetics_map
    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
  }
  ```

  Provision a Datadog child organization:

  ```hcl
  module "datadog_child_organization" {
    source = "cloudposse/platform/datadog//modules/child_organization"
    # version = "x.x.x"

    organization_name                = "test"
    saml_enabled                     = false  # Note that Free and Trial organizations cannot enable SAML
    saml_autocreate_users_domains    = []
    saml_autocreate_users_enabled    = false
    saml_idp_initiated_login_enabled = true
    saml_strict_mode_enabled         = false
    private_widget_share             = false
    saml_autocreate_access_role      = "ro"

    context = module.this.context
  }
  ```

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

  Also checkout our [terraform-aws-components](https://github.com/cloudposse/terraform-aws-components) repository for more examples of how to use a mixture of modules to enhance monitors, slos, and synthetics with inheritence and templating!

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"
  - name: "RB"
    github: "nitrocode"
  - name: "Benjamin Smith"
    github: "benbentwo"