Skip to content

Terraform installation and permissions #238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 27, 2020
Merged

Terraform installation and permissions #238

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
201c2aa
Terraform installation and permissions
tianchu Mar 27, 2020
ec3659b
Apply suggestions from code review
tianchu Mar 27, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 140 additions & 1 deletion aws/logs_monitoring/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ AWS Lambda function to ship logs from S3 and CloudWatch, custom metrics and trac

Since version 3.0.0, the forwarder Lambda function is managed by CloudFormation. To upgrade an older forwarder installation to 3.0.0 and above, follow the steps below.

<details><summary>Steps</summary>

1. Install a new forwarder following the [installation](#installation) steps.
1. Find the installed forwarder Lambda function under the stack's "Resources" tab with logical ID `Forwarder`.
1. Manually migrate a few triggers (CloudWatch log group subscription filter and S3 bucket event notification) on the old forwarder to the new one.
Expand All @@ -45,6 +47,8 @@ Since version 3.0.0, the forwarder Lambda function is managed by CloudFormation.
1. Delete the old forwarder Lambda function when you feel comfortable.
1. If you have old forwarder Lambda functions installed in multiple AWS accounts and regions, repeat the steps above in every account and region combination.

</details>

### Adjusting forwarder settings

1. Find the [datadog-forwarder (if you didn't rename it)](https://console.aws.amazon.com/cloudformation/home#/stacks?filteringText=datadog) CloudFormation stack.
Expand Down Expand Up @@ -74,12 +78,147 @@ Set the environment variable `DD_LOG_LEVEL` to `debug` on the Forwarder Lambda f

If for some reason you cannot install the forwarder using the provided CloudFormation template (e.g., AWS China or GovCloud), you can install the forwarder manually following the steps below. Feel free to open an issue or pull request to let us know if there is anything we can improve to make the template work for you.

<details><summary>Steps</summary>

1. Create a Python3.7 Lambda function using `aws-dd-forwarder-<VERSION>.zip` from the latest [releases](https://github.com/DataDog/datadog-serverless-functions/releases).
1. Save your Datadog API key in AWS Secrets Manager, set environment variable `DD_API_KEY_SECRET_ARN` with the secret ARN on the Lambda function, and add the `secretsmanager:GetSecretValue` permission to the Lambda execution role.
1. If you need to forward logs from S3 buckets, add the `s3:GetObject` permission to the Lambda execution role.
1. If you need to forward custom metrics and traces from your Lambda functions' logs for serverless monitoring, attach these [layers](https://github.com/DataDog/datadog-serverless-functions/blob/3639499bf602ea3d04493028aa08d1076cc02234/aws/logs_monitoring/template.yaml#L264) (switch to master branch for the latest layer versions) to the forwarder, and set environment variable `DD_ENHANCED_METRICS` to `false` on the forwarder.
1. If you need to forward custom metrics and traces from your Lambda functions' logs for serverless monitoring (not yet supported in AWS China and GovCloud), attach these [layers](https://github.com/DataDog/datadog-serverless-functions/blob/3639499bf602ea3d04493028aa08d1076cc02234/aws/logs_monitoring/template.yaml#L264) (switch to master branch for the latest layer versions) to the forwarder, and set environment variable `DD_ENHANCED_METRICS` to `false` on the forwarder.
1. Configure [triggers](https://docs.datadoghq.com/integrations/amazon_web_services/?tab=allpermissions#send-aws-service-logs-to-datadog).

</details>

## Terraform Installation

The Forwarder can be installed using Terraform resource [aws_cloudformation_stack](https://www.terraform.io/docs/providers/aws/r/cloudformation_stack.html) as a wrapper on top of the provided CloudFormation template.

<details><summary>Sample Configuration</summary>

```tf
variable "dd_api_key" {
type = string
description = "Datadog API key"
}

resource "aws_cloudformation_stack" "datadog-forwarder" {
name = "datadog-forwarder"
capabilities = ["CAPABILITY_IAM", "CAPABILITY_NAMED_IAM", "CAPABILITY_AUTO_EXPAND"]
parameters = {
DdApiKey = var.dd_api_key
FunctionName = "datadog-forwarder"
}
template_url = "https://datadog-cloudformation-template.s3.amazonaws.com/aws/forwarder/latest.yaml"
}
```

</details>

## Permissions

To deploy the CloudFormation Stack with the default options, you need to have the permissions below to save your Datadog API key as a secret, create a S3 bucket to store the Forwarder's code (zip file), and create Lambda functions (including execution roles and log groups).

<details><summary>IAM Statements</summary>

```json
{
"Effect": "Allow",
"Action": [
"cloudformation:*",
"secretsmanager:CreateSecret",
"secretsmanager:TagResource",
"s3:CreateBucket",
"s3:GetObject",
"iam:CreateRole",
"iam:GetRole",
"iam:PassRole",
"iam:PutRolePolicy",
"iam:AttachRolePolicy",
"lambda:CreateFunction",
"lambda:GetFunction",
"lambda:GetFunctionConfiguration",
"lambda:GetLayerVersion",
"lambda:InvokeFunction",
"lambda:PutFunctionConcurrency",
"lambda:AddPermission",
"logs:CreateLogGroup",
"logs:DescribeLogGroups",
"logs:PutRetentionPolicy"
],
"Resource": "*"
}
```

</details>

The CloudFormation Stack creates following IAM roles:

- ForwarderRole: The execution role for the Forwarder Lambda function to read logs from S3, fetch your Datadog API key from Secrets Manager, and write its own logs.
<details><summary>IAM Statements</summary>

```json
[
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": "*"
},
{
"Action": [
"s3:GetObject"
],
"Resource": "arn:aws:s3:::*",
"Effect": "Allow"
},
{
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": "<ARN of DdApiKeySecret>",
"Effect": "Allow"
}
]
```

</details>
- ForwarderZipCopierRole: The execution role for the ForwarderZipCopier Lambda function to download the Forwarder deployment zip file to a S3 bucket.
<details><summary>IAM Statements</summary>

```json
[
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": "*"
},
{
"Action": [
"s3:PutObject",
"s3:DeleteObject"
],
"Resource": "<S3Bucket to Store the Forwarder Zip>",
"Effect": "Allow"
},
{
"Action": [
"s3:ListBucket"
],
"Resource": "<S3Bucket to Store the Forwarder Zip>",
"Effect": "Allow"
}
]
```

</details>


## Notes

* For S3 logs, there may be some latency between the time a first S3 log file is posted and the Lambda function wakes up.
Expand Down