Update documentation and add example integration (#9)

README.md

@@ -42,7 +42,31 @@ We literally have [*hundreds of terraform modules*][terraform_modules] that are
 
 ## Usage
 
-**Note:** At the moment the module supports `RDS integration only`. It will be modified as necessary to integrate the needful services.
+**Note:** At the moment this module supports a limited set of IAM policies to support Datadog integrations. More can be added as needed.
+
+### Structure
+
+This module follows [Datadog's documentation](https://docs.datadoghq.com/integrations/amazon_web_services/)
+by supporting a `core` integration which is the minimum set of permissions needed for any Datadog integration,
+plus an additional integration per service which contains the additional permissions Datadog has documented
+are required for that service.
+
+To make things easier, this module also implements an `all` integration which includes all the permissions Datadog
+lists under "All Permissions" as the maximal set of permissions required, so you can just set
+`integrations = ["all"]` and be done.
+
+**Note:** For legacy reasons, the `RDS` policy is retained to be a stand-alone policy for supporting Datadog's RDS integration.
+It is not a good example to follow. Use [`Lambda`](lambda.tf) as your example for adding more integrations.
+
+### Installation
+
+For security, Datadog uses an [AWS External ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html)
+when assuming the role this module creates. To configure this:
+1. Go to Datadog's [integration control panel](https://app.datadoghq.com/account/settings#integrations/amazon_web_services)
+   and begin the integration process by adding an account, at which point Datadog will generate the `AWS External ID`.
+1. Set the Terraform variable `datadog_external_id` to the AWS External ID as a string.
+1. Apply the Terraform plan to create the role, and note the name of the role created.
+1. Enter the name of the created role in Datadog's integration control panel where it says "AWS Role name:".
 
 Include this module in your existing terraform code:
 
@@ -53,7 +77,7 @@ module "datadog_aws_integration" {
   name                       = "${var.name}"
   stage                      = "${var.stage}"
   datadog_external_id        = "dfae1fe3434..."
-  integrations               = ["RDS", "S3", ...]
+  integrations               = ["core", "Lambda", ...]
 }
 ```
 
@@ -72,26 +96,23 @@ Available targets:
   lint                                Lint terraform code
 
 ```
-
 ## Inputs
 
 | Name | Description | Type | Default | Required |
 |------|-------------|:----:|:-----:|:-----:|
-| attributes | Additional attributes (e.g. `policy` or `role`) | list | `<list>` | no |
-| datadog_aws_account_id | Datadog’s AWS account ID | string | - | yes |
-| datadog_external_id | External Id of the DataDog service | string | - | yes |
-| delimiter | Delimiter to be used between `name`, `namespace`, `stage`, etc. | string | `-` | no |
-| integrations | List of AWS Services to integration with the DataDog service (e.g EC2, RDS, Billing ...) | list | - | yes |
-| name | The Name of the application or solution  (e.g. `bastion` or `portal`) | string | - | yes |
+| attributes | Additional attributes (e.g. `1`) | list | `<list>` | no |
+| datadog_aws_account_id | The AWS account ID Datadog's integration servers use for all integrations | string | `464622532012` | no |
+| datadog_external_id | AWS External ID for this Datadog integration | string | - | yes |
+| integrations | List of AWS permission names to apply for different integrations (`all`, `core`, `rds`) | list | - | yes |
+| name | The Name of the application or solution  (e.g. `bastion` or `portal`) | string | `datadog` | no |
 | namespace | Namespace (e.g. `cp` or `cloudposse`) | string | - | yes |
 | stage | Stage (e.g. `prod`, `dev`, `staging`) | string | - | yes |
-| tags | Additional tags (e.g. `map('BusinessUnit','XYZ')`) | map | `<map>` | no |
 
 ## Outputs
 
 | Name | Description |
 |------|-------------|
-| role | Name of AWS IAM Role associated with creating integration |
+| role | Name of the AWS IAM Role for Datadog to use for this integration |
 
 
 
@@ -174,7 +195,7 @@ In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow.
 
 ## Copyright
 
-Copyright © 2017-2018 [Cloud Posse, LLC](https://cpco.io/copyright)
+Copyright © 2017-2019 [Cloud Posse, LLC](https://cpco.io/copyright)
 
 
 

README.yaml

@@ -1,7 +1,8 @@
 ---
 #
 # This is the canonical configuration for the `README.md`
-# Run `make readme` to rebuild the `README.md`
+# Run `make init`, `make readme/deps` to load all the dependencies
+# then run `make readme` as needed to rebuild the `README.md`
 #
 
 # Name of this project
@@ -54,7 +55,31 @@ description: |-
 
 # How to use this project
 usage: |-
-  **Note:** At the moment the module supports `RDS integration only`. It will be modified as necessary to integrate the needful services.
+  **Note:** At the moment this module supports a limited set of IAM policies to support Datadog integrations. More can be added as needed.
+
+  ### Structure
+
+  This module follows [Datadog's documentation](https://docs.datadoghq.com/integrations/amazon_web_services/)
+  by supporting a `core` integration which is the minimum set of permissions needed for any Datadog integration,
+  plus an additional integration per service which contains the additional permissions Datadog has documented
+  are required for that service.
+
+  To make things easier, this module also implements an `all` integration which includes all the permissions Datadog
+  lists under "All Permissions" as the maximal set of permissions required, so you can just set
+  `integrations = ["all"]` and be done.
+
+  **Note:** For legacy reasons, the `RDS` policy is retained to be a stand-alone policy for supporting Datadog's RDS integration.
+  It is not a good example to follow. Use [`Lambda`](lambda.tf) as your example for adding more integrations.
+
+  ### Installation
+
+  For security, Datadog uses an [AWS External ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html)
+  when assuming the role this module creates. To configure this:
+  1. Go to Datadog's [integration control panel](https://app.datadoghq.com/account/settings#integrations/amazon_web_services)
+     and begin the integration process by adding an account, at which point Datadog will generate the `AWS External ID`.
+  1. Set the Terraform variable `datadog_external_id` to the AWS External ID as a string.
+  1. Apply the Terraform plan to create the role, and note the name of the role created.
+  1. Enter the name of the created role in Datadog's integration control panel where it says "AWS Role name:".
 
   Include this module in your existing terraform code:
 
@@ -65,7 +90,7 @@ usage: |-
     name                       = "${var.name}"
     stage                      = "${var.stage}"
     datadog_external_id        = "dfae1fe3434..."
-    integrations               = ["RDS", "S3", ...]
+    integrations               = ["core", "Lambda", ...]
   }
   ```
 

docs/terraform.md

@@ -1,21 +1,18 @@
-
 ## Inputs
 
 | Name | Description | Type | Default | Required |
 |------|-------------|:----:|:-----:|:-----:|
-| attributes | Additional attributes (e.g. `policy` or `role`) | list | `<list>` | no |
-| datadog_aws_account_id | Datadog’s AWS account ID | string | - | yes |
-| datadog_external_id | External Id of the DataDog service | string | - | yes |
-| delimiter | Delimiter to be used between `name`, `namespace`, `stage`, etc. | string | `-` | no |
-| integrations | List of AWS Services to integration with the DataDog service (e.g EC2, RDS, Billing ...) | list | - | yes |
-| name | The Name of the application or solution  (e.g. `bastion` or `portal`) | string | - | yes |
+| attributes | Additional attributes (e.g. `1`) | list | `<list>` | no |
+| datadog_aws_account_id | The AWS account ID Datadog's integration servers use for all integrations | string | `464622532012` | no |
+| datadog_external_id | AWS External ID for this Datadog integration | string | - | yes |
+| integrations | List of AWS permission names to apply for different integrations (`all`, `core`, `rds`) | list | - | yes |
+| name | The Name of the application or solution  (e.g. `bastion` or `portal`) | string | `datadog` | no |
 | namespace | Namespace (e.g. `cp` or `cloudposse`) | string | - | yes |
 | stage | Stage (e.g. `prod`, `dev`, `staging`) | string | - | yes |
-| tags | Additional tags (e.g. `map('BusinessUnit','XYZ')`) | map | `<map>` | no |
 
 ## Outputs
 
 | Name | Description |
 |------|-------------|
-| role | Name of AWS IAM Role associated with creating integration |
+| role | Name of the AWS IAM Role for Datadog to use for this integration |
 

lambda.tf

@@ -0,0 +1,40 @@
+data "aws_iam_policy_document" "lambda" {
+  statement {
+    sid    = "DatadogLambd"
+    effect = "Allow"
+
+    actions = [
+      "lambda:List*",
+      "logs:DescribeLogGroups",
+      "logs:DescribeLogStreams",
+      "logs:FilterLogEvents",
+      "tag:GetResources",
+    ]
+
+    resources = ["*"]
+  }
+}
+
+module "lambda_label" {
+  source     = "git::https://github.com/cloudposse/terraform-null-label.git?ref=0.6.2"
+  namespace  = "${var.namespace}"
+  stage      = "${var.stage}"
+  name       = "${var.name}"
+  attributes = ["${compact(concat(var.attributes, list("lambda")))}"]
+}
+
+locals {
+  lambda_count = "${contains(split(",", lower(join(",", var.integrations))), "lambda") ? 1 : 0}"
+}
+
+resource "aws_iam_policy" "lambda" {
+  count  = "${local.lambda_count}"
+  name   = "${module.lambda_label.id}"
+  policy = "${data.aws_iam_policy_document.lambda.json}"
+}
+
+resource "aws_iam_role_policy_attachment" "lambda" {
+  count      = "${local.lambda_count}"
+  role       = "${aws_iam_role.default.name}"
+  policy_arn = "${join("", aws_iam_policy.lambda.*.arn)}"
+}

outputs.tf

@@ -1,4 +1,4 @@
 output "role" {
   value       = "${aws_iam_role.default.name}"
-  description = "Name of AWS IAM Role associated with creating integration"
+  description = "Name of the AWS IAM Role for Datadog to use for this integration"
 }

variables.tf

@@ -18,11 +18,11 @@ variable "attributes" {
 }
 
 variable "datadog_external_id" {
-  description = "External Id of the Datadog service"
+  description = "AWS External ID for this Datadog integration"
 }
 
 variable "datadog_aws_account_id" {
-  description = "Datadog’s AWS account ID"
+  description = "The AWS account ID Datadog's integration servers use for all integrations"
   default     = "464622532012"
 }