How to integrate AWS Organizations

Latest Dynatrace
How-to guide

This is a guide to integrating your AWS Organizations with the new Dynatrace Cloud Platform Monitoring. The target audience is Dynatrace admins and AWS platform teams, as well as Site Reliability Engineers (SREs) who will act as the AWS administrators.

Prerequisites

Only a Dynatrace administrator and an AWS (delegated) administrator can successfully complete the initial prerequisites.
Get familiar with the Onboard AWS Organizations concepts before you begin.

AWS

To complete the AWS portion of this integration, you need to be an AWS administrator with access and permissions to create StackSets and to deploy stack instances from a registered delegated administrator member account. For details, see below.

AWS IAM permission policy for creating stacksets and deploy stack instances

To ensure your AWS delegated administrator (IAM User or Role) can successfully manage StackSets and deploy stack instances across your organization while adhering to the principle of least privilege, you need the below minimum policy attached to the IAM User or Role (AWS delegated administrator).

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "cloudformation0",
      "Effect": "Allow",
      "Action": [
        "cloudformation:CreateStack",
        "cloudformation:DescribeStacks",
        "cloudformation:UpdateStack",
        "cloudformation:ListStacks",
        "cloudformation:DescribeStackResources",
        "cloudformation:DeleteStack",
        "cloudformation:CreateChangeSet",
        "cloudformation:DescribeChangeSet",
        "cloudformation:ExecuteChangeSet",
        "cloudformation:CreateStackInstances",
        "cloudformation:ListStackInstances",
        "cloudformation:DescribeStackInstance",
        "cloudformation:DeleteStackInstances",
        "cloudformation:CreateStackSet",
        "cloudformation:UpdateStackSet",
        "cloudformation:DescribeStackSet",
        "cloudformation:DescribeStackSetOperation",
        "cloudformation:ListStackSetOperationResults",
        "cloudformation:DeleteStackSet",
        "cloudformation:TagResource",
        "cloudformation:UntagResource"
      ],
      "Resource": [
        "arn:aws:cloudformation:*:<AWS-Account-ID>:stackset-target/*",
        "arn:aws:cloudformation:*:<AWS-Account-ID>:stackset/Dynatrace*:*",
        "arn:aws:cloudformation:*:<AWS-Account-ID>:stack/<Deployment-Stack-Name-Prefix>*",
        "arn:aws:cloudformation:*:<AWS-Account-ID>:stack/StackSet-<Deployment-Stack-Name-Prefix>*/*",
        "arn:aws:cloudformation:*:<AWS-Account-ID>:type/resource/*"
      ]
    },
    {
      "Sid": "cloudformation1",
      "Effect": "Allow",
      "Action": [
        "cloudformation:GetTemplate",
        "cloudformation:ValidateTemplate",
        "cloudformation:GetTemplateSummary"
      ],
      "Resource": [
        "*"
      ]
    },
    {
      "Sid": "lambda",
      "Effect": "Allow",
      "Action": [
        "lambda:CreateFunction",
        "lambda:UpdateFunctionCode",
        "lambda:UpdateFunctionConfiguration",
        "lambda:GetFunction",
        "lambda:InvokeFunction",
        "lambda:DeleteFunction",
        "lambda:TagResource",
        "lambda:UntagResource"
      ],
      "Resource": [
        "arn:aws:lambda:*:<AWS-Account-ID>:function:<Deployment-Stack-Name-Prefix>*",
        "arn:aws:lambda:*:<AWS-Account-ID>:function:DynatraceApiClientFunction*"
      ]
    },
    {
      "Sid": "iam",
      "Effect": "Allow",
      "Action": [
        "iam:CreatePolicy",
        "iam:CreatePolicyVersion",
        "iam:DeletePolicyVersion",
        "iam:DeletePolicy",
        "iam:CreateRole",
        "iam:UpdateRole",
        "iam:DeleteRole",
        "iam:PassRole",
        "iam:AttachRolePolicy",
        "iam:PutRolePolicy",
        "iam:DetachRolePolicy",
        "iam:DeleteRolePolicy",
        "iam:GetRole",
        "iam:GetPolicy",
        "iam:ListPolicyVersions",
        "iam:TagPolicy",
        "iam:TagRole",
        "iam:UntagPolicy",
        "iam:UntagRole",
        "iam:GetRolePolicy",
        "iam:UpdateAssumeRolePolicy"
      ],
      "Resource": [
        "arn:aws:iam::<AWS-Account-ID>:policy/<Deployment-Stack-Name-Prefix>*",
        "arn:aws:iam::<AWS-Account-ID>:role/<Deployment-Stack-Name-Prefix>*",
        "arn:aws:iam::<AWS-Account-ID>:role/Dynatrace*",
        "arn:aws:iam::<AWS-Account-ID>:policy/Dynatrace*"
      ]
    },
    {
      "Sid": "s3",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:CreateBucket",
        "s3:DeleteBucket",
        "s3:PutLifecycleConfiguration",
        "s3:PutBucketTagging",
        "s3:PutEncryptionConfiguration"
      ],
      "Resource": [
        "arn:aws:s3:::dynatrace*"
      ]
    },
    {
      "Sid": "secretsmanager",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:CreateSecret",
        "secretsmanager:DescribeSecret",
        "secretsmanager:UpdateSecret",
        "secretsmanager:GetSecretValue",
        "secretsmanager:PutSecretValue",
        "secretsmanager:TagResource",
        "secretsmanager:DeleteSecret",
        "secretsmanager:PutResourcePolicy",
        "secretsmanager:DeleteResourcePolicy"
      ],
      "Resource": [
        "arn:aws:secretsmanager:*:<AWS-Account-ID>:secret:/dynatrace*",
        "arn:aws:secretsmanager:*:<AWS-Account-ID>:secret:events!connection/DynatraceEventBusConnection*",
        "arn:aws:secretsmanager:*:<AWS-Account-ID>:secret:DynatraceAPIAccessToken*",
        "arn:aws:secretsmanager:*:<AWS-Account-ID>:secret:DynatraceAPIPlatformToken*"
      ]
    },
    {
      "Sid": "kms0",
      "Effect": "Allow",
      "Action": [
        "kms:CreateKey",
        "kms:TagResource",
        "kms:UntagResource",
        "kms:CreateGrant",
        "kms:RevokeGrant",
        "kms:DescribeKey",
        "kms:GetKeyPolicy",
        "kms:PutKeyPolicy",
        "kms:ScheduleKeyDeletion"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:RequestTag/dt:CreatedBy": "Dynatrace"
        }
      }
    },
    {
      "Sid": "kms1",
      "Effect": "Allow",
      "Action": [
        "kms:CreateAlias",
        "kms:DeleteAlias",
        "kms:UpdateAlias"
      ],
      "Resource": [
        "arn:aws:kms:*:<AWS-Account-ID>:key/*"
      ],
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/dt:CreatedBy": "Dynatrace"
        }
      }
    },
    {
      "Sid": "kms2",
      "Effect": "Allow",
      "Action": [
        "kms:CreateAlias",
        "kms:DeleteAlias",
        "kms:UpdateAlias"
      ],
      "Resource": "arn:aws:kms:*:<AWS-Account-ID>:alias/dynatrace/*/keys/aws/integration/*"
    },
    {
      "Sid": "logs0",
      "Effect": "Allow",
      "Action": [
        "logs:DescribeLogGroups",
        "logs:DescribeLogStreams",
        "logs:ListTagsForResource",
        "logs:DescribeIndexPolicies"
      ],
      "Resource": "*"
    },
    {
      "Sid": "logs1",
      "Effect": "Allow",
      "Action": [
        "logs:DeleteLogGroup",
        "logs:CreateLogGroup",
        "logs:DeleteLogStream",
        "logs:CreateLogStream",
        "logs:DescribeLogStreams",
        "logs:PutRetentionPolicy",
        "logs:TagResource",
        "logs:ListTagsForResource",
        "logs:DescribeIndexPolicies",
        "logs:AssociateKmsKey",
        "logs:DisassociateKmsKey",
        "logs:PutLogEvents"
      ],
      "Resource": [
        "arn:aws:logs:*:<AWS-Account-ID>:log-group:/aws/lambda/<Deployment-Stack-Name-Prefix>*",
        "arn:aws:logs:*:<AWS-Account-ID>:log-group:/aws/datafirehose/dynatrace*",
        "arn:aws:logs:*:<AWS-Account-ID>:log-group:/aws/kinesisfirehose/<Deployment-Stack-Name-Prefix>*",
        "arn:aws:logs:*:<AWS-Account-ID>:log-group:/aws/kinesisfirehose/dynatrace*",
        "arn:aws:logs:*:<AWS-Account-ID>:log-group:/aws/lambda/DynatraceApiClientFunction*"
      ]
    },
    {
      "Sid": "events0",
      "Effect": "Allow",
      "Action": [
        "events:ListTargetsByRule",
        "events:DescribeRule",
        "events:PutTargets",
        "events:PutRule",
        "events:DescribeConnection",
        "events:CreateConnection",
        "events:UpdateConnection",
        "events:DeleteConnection",
        "events:DeleteRule",
        "events:RemoveTargets",
        "events:TagResource",
        "events:UntagResource"
      ],
      "Resource": [
        "arn:aws:events:*:<AWS-Account-ID>:connection/DynatraceConnection*",
        "arn:aws:events:*:<AWS-Account-ID>:rule/Dynatrace*"
      ]
    },
    {
      "Sid": "events1",
      "Effect": "Allow",
      "Action": [
        "events:CreateApiDestination",
        "events:DescribeApiDestination",
        "events:UpdateApiDestination",
        "events:DeleteApiDestination"
      ],
      "Resource": [
        "*"
      ]
    },
    {
      "Sid": "firehose",
      "Effect": "Allow",
      "Action": [
        "firehose:DeleteDeliveryStream",
        "firehose:UpdateDestination",
        "firehose:CreateDeliveryStream",
        "firehose:DescribeDeliveryStream",
        "firehose:TagDeliveryStream",
        "firehose:UntagDeliveryStream",
        "firehose:ListTagsForDeliveryStream",
        "firehose:StartDeliveryStreamEncryption",
        "firehose:StopDeliveryStreamEncryption"
      ],
      "Resource": [
        "arn:aws:firehose:*:<AWS-Account-ID>:deliverystream/DynatraceLogDeliveryStream*"
      ]
    }
  ]
}

We encourage following the AWS recommendations for registering a delegated administrator member account.
The AWS Organizations administrator has activated trusted access for StackSets.
The currently (potentially) implemented service control policies (SCPs) do not block the successful deployment of the CloudFormation resources in the designated accounts.

Dynatrace

To complete the Dynatrace portion of this integration, you need to be a member of the CloudsAdmins IAM group. For details, see instructions on Dynatrace IAM baseline creation.

Integrate AWS Organizations

Before you start, make sure the prerequisites have been completed.

As a Dynatrace administrator

Log in to Dynatrace as the IAM user (member of the CloudsAdmins group) and open Settings.
Go to Collect and capture > Cloud and virtualization > AWS > Organization Templates and select New Organization template.

If the button is grayed out, it means you do not have the proper permissions to create a connection. Please, contact your administrator.
Enter a friendly template name that is unique (for example, myPlayGroundOrg), then enter the AWS Organizations ID.
Select the observability option.
1. Choose the Recommended observability path. Two paths are currently supported:
  - Recommended: The monitoring configuration is an opinionated (immutable) option, only monitored Regions are customizable. Per AWS member account, this flow provides:
    
    AWS account resources inventory using Clouds (for supported AWS services).
    
    AWS account resources topology, depicted as rich resource entities using Clouds (for supported AWS services).
    
    Amazon CloudWatch API metric polling (per enabled region) for our recommended services (automatically opted-in).
    
    The Regions that were selected, allowing the AWS administrator to deploy Amazon Data Firehose streams for logs ingest as stacksets on the AWS Organizations Console.
  - Advanced: The most fine-grained path monitoring configuration. Allows the full customization any monitoring setting to meet advanced use cases.
  Regardless of the selected path, customizing all the supported monitoring settings is possible post-onboarding.
  The topology signal is an auto-enabled signal; you can't disable it.
2. Choose the monitored AWS Regions you want to monitor.
  
  The monitored regions are the AWS Regions in which Dynatrace can securely poll metrics, topology and push logs from.
  
  You need to enable us-east-1 regardless of your desired monitored regions, since global AWS resources reside in us-east-1.
3. Select Next.
After a successful onboarding, you'll be able to customize monitored AWS Regions and all other supported monitoring settings, per AWS member account.
Generate the settings and ingest platform tokens, then select Next.
Select Download deployment instructions and then Finish.
Share the deployment instructions with your AWS Organizations delegated admin.

The deployment instructions assets contain a file with sensitive secrets (platform tokens).

Head back to the Organization templates tab, the template is now a live monitoring configuration.

As an AWS Organizations delegated administrator

The foundational StackSet must be created as the first stack instance.

1. Create and deploy the foundational StackSet/stack instance

In the CloudFormation console

Head over to the desired AWS management region.
Select StackSets and select Create stack set.
Make sure the Service-managed permission model is selected.
Enter template URL into Amazon S3 URL field:

https://dynatrace-data-acquisition.s3.amazonaws.com/aws/deployment/organizations/latest/da-aws-orgs-foundational.yaml
Select Next.

Set all the required parameters values, most values are taken from the shared instruction file.

See the table below for detailed explanation of each parameter:

Parameter	Description
Dynatrace settings platform token(`pDtApiToken`)	Value from the settings platform token (from the file)
Dynatrace log and event ingest token(`pDtIngestToken`)	Value from the ingest platform token (from the file)
AWS management region(`pManagementRegion`)	Set the AWS management region in which the StackSets will be created.
AWS Organization Id(`pAwsOrganizationId`)	AWS Organization identifier (from the file)
Dynatrace environment URL(`pDynatraceUrl`)	The URL of your Dynatrace environment (from the file)
Deployment instance identifier(`pDeploymentInstanceIdentifier`)	Optional Identifier of the Secrets Manager deployment where the Dynatrace platform tokens were deployed.Use this parameter only if you are deploying multiple instances of the foundational StackSets and you want to target a specific set of secrets.

Select Next.
Optional Add tags.
Select Next.
Make sure that Automatic deployment is set to Activated.
In Deployment targets:
1. Select Deploy to organizational units (OUs).
2. Set the AWS Organizations Unit ID where the designated AWS member account that should host the foundational AWS resources resides.
3. Set Account filter type - optional to Intersection and enter the foundational AWS Account ID.
4. Specify Regions:
  - Required Select the AWS management region (pManagementRegion).
  - Select all the other AWS Regions where AWS member accounts are expected to interact with the Dynatrace APIs (logs ingest, EventBridge events ingest).
5. Deployment options: Refer to the AWS guide or accept the defaults.
Review all the settings and select Submit to start the StackSet creation and stack instance deployment.

The StackSet creation must complete successfully. If the create operation fails, see the troubleshooting guide.

Do NOT proceed to the next validations/steps until the create StackSet creation ends successfully.

Foundational stack instance deployment must complete with the SUCCEEDED status (CloudFormation console > StackSets > Stack set details > Stack instances tab).

2. Create and deploy the core StackSet/stack instance(s)

You can create the core StackSet only after the foundational StackSet deployment has completed successfully.

In the CloudFormation console

Head over to the desired AWS management region.
Select StackSets and select Create stack set.
Make sure Service-managed permissions is selected.
Enter template URL into Amazon S3 URL field:

https://dynatrace-data-acquisition.s3.amazonaws.com/aws/deployment/organizations/latest/da-aws-orgs-core.yaml

EventBridge not supported
If you want to deploy the template in the region where EventBridge is not supported (for example, mx-central-1), use this template URL instead: https://dynatrace-data-acquisition.s3.amazonaws.com/aws/deployment/organizations/latest-no-events/da-aws-orgs-core.yaml.
Select Next.

Set all the required parameters values. Values are taken from the shared instructions file and from the foundational stack instance deployment.

See the table below for a detailed explanation of each parameter:

Parameter	Description
AWS Organization Id(`pAwsOrganizationId`)	AWS Organizations identifier (from the file).
Dynatrace foundational account ID(`pSecretsAccountId`)	The ID of the AWS account where the foundational stack instance was deployed.
AWS management region(`pManagementRegion`)	Select the SAME AWS management region that you have set when creating the foundational stack instance.
Dynatrace environment URL(`pDynatraceUrl`)	The URL of your Dynatrace environment (from the file).
Dynatrace monitoring configuration ID(`pMonitoringConfigId`)	AWS monitoring settings configuration ID (from the file).
Deployment instance identifier(`pDeploymentInstanceIdentifier`)	Optional Identifier of the Secrets Manager deployment where the Dynatrace Platform tokens were deployed (use this parameter only if you are deploying multiple instances of the Foundational StackSets and you want to target a specific set of Secrets).
Deploy log ingestion resources(`pDtLogsIngestEnabled`)	Set to `TRUE` to enable log ingestion.
Deploy event ingestion resources(`pDtEventsIngestEnabled`)	Set to `TRUE` to enable event ingestion.
AWS EventBridge event sources (`pEventSources`)	Comma-separated list of values of event sources to forward to Dynatrace (for example, `aws.ec2`, `aws.s3`, `aws.lambda`).
AWS EventBridge event bus name (`pEventBridgeBusName`)	Existing Amazon EventBridge name from which to consume the events from. Must already exist in each opted-in region.
Use Customer Managed Key (`pUseCMK`)	Optional Create and use a Customer Managed Key (CMK) for encryption.

Select Next.
Optional Add tags.
Select I acknowledge that AWS CloudFormation might create IAM resources with custom names.
Select Next.
Make sure that Automatic deployment is set to Activated.
In Deployment targets:
- Set the organizational units (OUs) or AWS Account IDs which you want to integrate with Dynatrace.
  
  If this is your initial deployment of our AWS Organizations integration, we highly recommended to target a single organizational units (OU) with few AWS accounts which are considered the least business-critical.
  This approach will allow you to evaluate possible Organizations constrains, examine the results and telemetry, and potentially make custom changes to the IaC templates in order to meet your specific environment requirments.
- The selected targets results that each matched AWS member account will be onboarded as an AWS connection, telemetry should start flowing as soon as the successful deployment ends.
Specify Regions:
- Required Select the AWS management region (pManagementRegion).
- Select all the other AWS Regions where AWS member accounts are expected to interact with the Dynatrace APIs (Firehose logs ingest, EventBridge events ingest).
  
  Do not confuse with CloudWatch metrics opted-in regions—monitored regions—which are set when creating the monitoring configuration (from template), and can (easily) be modified in Settings.
  The AWS Regions you set in this step must be included in the list of regions that you have set during the foundational StackSet creation.
Deployment options: Refer to the AWS guide or accept the defaults.
Review all the settings and select Submit to start the core StackSet creation and stack instances deployment:
- StackSet create operation must complete successfully. If the create operation fails, see the troubleshooting guide.
- Track the stack instances deployment operation in the Cloudformation StackSets console (CloudFormation console > StackSets > Stack set details > Stack instances tab).
- The desired state for each AWS member account deployment is in SUCCEEDED status.

The number of deployed stack instances should be the number of targeted AWS member accounts multiplied by each opted-in region at step 13 above.

What's next?

Head over to Settings > Collect and capture > Cloud and virtualization > AWS.

The Accounts tab should shortly get populated with AWS connections where the Account type column should identify them as Organization member and the status should be Healthy.
Go to Clouds. AWS resources with telemetry should start to appear shortly.
Configure CloudWatch log group subscriptions in onboarded member account if the log ingest option is enabled.