Create an AWS connection via API

Latest Dynatrace
How-to guide

Dynatrace is designed to support large and complex AWS environments.

By default, a Dynatrace environment can accommodate up to 3,000 AWS connections (each connection representing a single AWS account).

This is a soft limit. If you plan to exceed this (per Dynatrace environment), we kindly ask you to open a support request so we can proactively increase this limit, ensuring a smooth experience.

Prerequisites

An AWS account with the proper IAM permissions and access, examine the CFN templates and least privilige IAM permissions required to deploy the CFN stacks.
A bastion EC2 with the latest AWS CLI and attached IAM role which allows you to deploy the CFN stacks.
Create settings and ingest platform tokens. The (current) easiest way to create them is to use the new connection (UI) wizard step 3 to generate and download them. There is no need to complete the connection wizard.

Create a new AWS monitoring configuration using REST API

The monitoring configuration is the blueprint that contains all the settings that will be used on initial AWS account onboarding.

Settings can be modified post onboarding.

1. Prepare the request payload

[
	{
		"scope": "integration-aws",
		"value": {
			"enabled": false,
			"description": "{configuration-name}",
			"version": "1.0.0",
			"featureSets": [
				"ApiGateway_essential",
				"ApplicationELB_essential",
				"AutoScaling_essential",
				"CloudFront_essential",
				"DynamoDB_essential",
				"EBS_essential",
				"EC2_essential",
				"ECR_essential",
				"ECS_essential",
				"EFS_essential",
				"ELB_essential",
				"ElastiCache_essential",
				"Firehose_essential",
				"Lambda_essential",
				"NATGateway_essential",
				"NetworkELB_essential",
				"PrivateLinkEndpoints_essential",
				"PrivateLinkServices_essential",
				"RDS_essential",
				"Route53_essential",
				"S3_essential",
				"SNS_essential",
				"SQS_essential"
			],
			"aws": {
				"smartscapeConfiguration": {
					"enabled": true
				},
				"deploymentRegion": "{deployment-region}",
				"credentials": [
					{
						"enabled": false,
						"description": "{configuration-name}",
						"connectionId": "*",
						"accountId": "{aws-account-id}"
					}
				],
				"regionFiltering": [
					"{monitored-region-a}",
					"{monitored-region-b}",
					"{monitored-region-n}"
				],
				"metricsConfiguration": {
					"enabled": true,
					"regions": [
					"{monitored-region-a}",
					"{monitored-region-b}",
					"{monitored-region-n}"
					]
				},
				"cloudWatchLogsConfiguration": {
					"enabled": false,
					"regions": [
					"{monitored-region-a}",
					"{monitored-region-n}"
					]
				},
				"configurationMode": "QUICK_START",
				"deploymentScope": "SINGLE_ACCOUNT",
				"deploymentMode": "AUTOMATED",
				"manualDeploymentStatus": "NA",
				"automatedDeploymentStatus": "NA"
			}
		}
	}
]

Placeholder	Description
`{configuration-name}`	Name of the new monitoring configuration. Use only letters, numbers, and hyphens. It must start with a letter.
`{aws-account-id}`	Numeric AWS account ID to monitor, for example: `123456789012`.
`{deployment-region}`	AWS Region where you deploy the onboarding CloudFormation stack, for example: `us-east-1`.
`regionFiltering/{monitored-region-a}` … `{monitored-region-n}`¹	AWS Regions from which you poll CloudWatch metrics and topology (monitored regions), for example: `us-east-1`, `eu-central-1`.
`metricsConfiguration/{monitored-region-a}` … `{monitored-region-n}`¹	UI/forward-compatibility field. This region list must be identical to `regionFiltering` (for example: `us-east-1`, `eu-central-1`).
`cloudWatchLogsConfiguration.enabled`	Set to `true` or `false`.
`cloudWatchLogsConfiguration.regions`²	AWS Regions from which you push logs (CloudWatch Logs and Firehose), for example: `{monitored-region-a}` … `{monitored-region-n}`.

For both regionFiltering and metricsConfiguration, the us-east-1 region must always be set as the topology service polls for global AWS resources which only reside on us-east-1.

Region set for cloudWatchLogsConfiguration must be part of regionFiltering and metricsConfiguration region lists. This will allow supported logs to depict as signal-in-context using Clouds Clouds.

To allow telemetry signals in context and inventory on all relevant regions, the topology service must poll for topology signals on all regions where any signal in ingested or pushed (logs, eventbridge events).

2. Create the submit REST API request

curl -X 'POST' \
'{your-environment-url}/platform/extensions/v1/com.dynatrace.extension.da-aws/monitoring-configuration' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {your-bearer-token}' \
-d '{monitoring-configuration-payload}'

Placeholder	Description
`{your-bearer-token}`	Settings platform token (created as a prerequisite)
`{monitoring-configuration-payload}`	Request payload prepared in step 1

Successful request will respond with new monitoring configuration ID (in objectId field). Example:

[
  {
    "objectId": "e4bf05f3-d829-3689-8dd4-a9d2aeab0607",
    "code": 200
  }
]

Note that the value of objectId field should be used in the next step in the placeholder: {new-monitoring-configuration-id}.

If the API call fails, validate that:

You have access to the settings API.
Your settings platform token is valid and assigned to the correct Dynatrace environment/account.

3. Deploy the CloudFormation stack

On your EC2 bastion:

wget -O da-aws-activation_v1.0.0.yaml https://dynatrace-data-acquisition.s3.amazonaws.com/aws/deployment/cfn/v1.0.0/da-aws-activation.yaml && \
aws cloudformation deploy \
--region {deployment-region} \
--stack-name {configuration-name} \
--template-file da-aws-activation_v1.0.0.yaml \
--capabilities CAPABILITY_NAMED_IAM \
--parameter-overrides pDynatraceUrl={your-environment-url} pMonitoringConfigId={new-monitoring-configuration-id} pDtApiToken={settings-platform-token} pDtIngestToken={ingest-platform-token} pDtLogsIngestEnabled=TRUE pDtLogsIngestRegions={logs-ingest-regions}

Placeholder	Description
`{configuration-name}`	Value specified in step 1
`{deployment-region}`	Value specified in step 1
`{your-environment-url}`	Value specified in step 1
`{new-monitoring-configuration-id}`	Value from API response specified in step 2 (`objectId`)
`{settings-platform-token}`	Settings platform token (created as a prerequisite)
`{ingest-platform-token}`	Ingest platform token (created as a prerequisite)
`{logs-ingest-regions}`	Comma-separated list of regions specified in step 1 (`cloudWatchLogsConfiguration`)

After successful completion, head over to Settings.

In a few minutes, the newly created connection should be visible and in the Healthy state.

Core CFN stacks

Current latest production version: v1.0.0

Main deployment stack

Conditional (nested) CFN stacks

Deployed based on user opt-in during onboarding

AWS resources created by the CloudFormation templates

Level 1: Main template resources (`da-aws-activation.yaml`)

Direct resources created in deployment region:

DynatraceApiClientStack (AWS::CloudFormation::Stack)
- Nested stack that creates API client function (Dynatrace API interaction, create/delete connection)
- Reference: da-aws-nested-dt-api-function.yaml
ReportStartedStatusResource (Custom::DynatraceApiAccessFunction)
- Custom resource to report deployment start status to Dynatrace
DynatraceIntegrationStack (AWS::CloudFormation::Stack)
- Nested stack for core integration
- Reference: da-aws-nested-integration.yaml
DynatraceStackSetRoleStack (AWS::CloudFormation::Stack)
- Conditional: Only created if log or event ingest is enabled
- Creates StackSet administration and execution roles
- Reference: da-aws-nested-stackset-role.yaml
DynatraceLogIngestStackSet (AWS::CloudFormation::StackSet)
- Conditional: Only if pDtLogsIngestEnabled = 'TRUE'
- Deploys log ingestion infrastructure to specified regions
- Reference: da-aws-stack-logs.yaml
DynatraceEventIngestStackSet (AWS::CloudFormation::StackSet)
- Conditional: Only if pDtEventsIngestEnabled = 'TRUE'
- Deploys event ingestion infrastructure to specified regions
- Reference: da-aws-stack-events.yaml
ReportCompleteStatusResource (Custom::DynatraceApiAccessFunction)
- Custom resource to report deployment completion status to Dynatrace

Level 2: Nested stack resources

From DynatraceApiClientStack (da-aws-nested-dt-api-function.yaml)—expected resources:

Lambda Function: Dynatrace API client function
IAM Role: Lambda execution role
Secrets Manager Secret: Storage for Dynatrace API token
KMS Key (Conditional): Customer Managed Key if pUseCMK = 'TRUE'
KMS Alias (Conditional): Alias for the CMK
Lambda Log Group: CloudWatch Logs for the Lambda function

From DynatraceIntegrationStack (da-aws-nested-integration.yaml)—expected resources:

IAM Role: Dynatrace monitoring role with trust relationship to Dynatrace account
IAM Policy: Monitoring permissions policy
Custom Resource: To establish connection with Dynatrace

From DynatraceStackSetRoleStack (da-aws-nested-stackset-role.yaml)—expected resources:

IAM Role: StackSet administration role
IAM Role: StackSet execution role
IAM Policies: Attached to both roles

Level 3: Deployed core resources (management region)

Minimum resources (no log/event ingest enabled), deployed only on a single region (management region):

Two custom resources: Report deployment start and finish status
Lambda function + IAM roles + Secrets Manager: Created/delete connection, store dynatrace platform tokens in Secret Manager
Dynatrace monitoring IAM role: Dynatrace monitoring role with trust relationship to Dynatrace account

Level 4: StackSet-deployed resources (conditional per region)

From DynatraceLogIngestStackSet (da-aws-stack-logs.yaml); deployed to each region in pDtLogsIngestRegions list. Expected resources per region:

Kinesis Data Firehose Delivery Stream: For log forwarding to Dynatrace
IAM Role: Firehose delivery role
S3 Bucket: Backup/buffer bucket for failed deliveries
Secrets Manager Secret: Dynatrace ingest token storage
KMS Key (conditional): If pUseCMK = 'TRUE'

From DynatraceEventIngestStackSet (da-aws-stack-events.yaml); deployed to each region in pDtEventsIngestRegions list. Expected resources per region:

EventBridge Rule: To capture AWS events
EventBridge API Destination: Dynatrace endpoint
EventBridge Connection: Authentication for API destination
IAM Role: EventBridge execution role
Secrets Manager Secret: Dynatrace ingest token storage

Modify an existing monitoring configuration

To modify an existing monitoring configuration, follow the steps below.

1. Retrieve existing configuration using GET request

curl -X 'GET' \
'{your-environment-url}/platform/extensions/v1/com.dynatrace.extension.da-aws/monitoring-configuration/{existing-monitoring-configuration-id}' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {your-bearer-token}'

2. Modify JSON

Modify the retrieved configuration JSON as needed.

For example, add/remove monitored regions, enable/disable features, and more.

3. Update the configuration using PUT request

curl -X 'PUT' \
'{your-environment-url}/platform/extensions/v1/com.dynatrace.extension.da-aws/monitoring-configuration/{existing-monitoring-configuration-id}' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {your-bearer-token}' \
-d '{modified-monitoring-configuration-payload}'

Placeholder	Description
`{your-bearer-token}`	Settings platform token
`{your-environment-url}`	URL of you Dynatrace environment, for example: `https://abc12345.apps.dynatrace.com`
`{existing-monitoring-configuration-id}`	ID of the monitoring configuration you want to modify
`{modified-monitoring-configuration-payload}`	Modified configuration JSON from step 2

4. Successful request

Successful request will respond with updated monitoring configuration ID (in objectId field). Example:

{
"objectId": "e4bf05f3-d829-3689-8dd4-a9d2aeab0607",
"code": 200
}

Delete an existing monitoring configuration

A deleted monitoring configuration does not delete the CFN stacks in AWS.

You must delete these manually to avoid lingering resources which will incur AWS and Dynatrace costs.

Delete the CFN stack using AWS CLI from your EC2 bastion.

aws cloudformation delete-stack --stack-name {StackName} --region {DeployedRegionName}

To delete an existing monitoring configuration, use the following DELETE request:

curl -X 'DELETE' \
'{your-environment-url}/platform/extensions/v1/com.dynatrace.extension.da-aws/monitoring-configuration/{existing-monitoring-configuration-id}' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {your-bearer-token}'

Placeholder	Description
`{your-bearer-token}`	Settings platform token
`{your-environment-url}`	URL of you Dynatrace environment, for example: `https://abc12345.apps.dynatrace.com`
`{existing-monitoring-configuration-id}`	ID of the monitoring configuration you want to delete

Successful request will respond with 204 No Content status, indicating that the configuration has been deleted successfully.