Create an AWS connection

  • Latest Dynatrace
  • How-to guide
  • Published Aug 29, 2025
  • Preview

This is an overview of how to onboard your AWS account in few steps that will generate a deployable CloudFormation template.

The CloudFormation stack will deploy core mandatory resources inside your AWS account (Dynatrace SaaS IAM Monitoring Role, AWS Secrets, Dynatrace API integration Lambda Function).

After a successful deployment, a connection from Dynatrace SaaS to your AWS account will be created. Dynatrace SaaS will then perform API calls to your AWS account to poll and push telemetry into your Dynatrace environment.

The new integration does not deploy or use ActiveGate compute resources inside your AWS account to poll or push telemetry. The experience is transparent and fully managed by Dynatrace SaaS.

Limitations

  • Only standalone connections for AWS accounts are supported. AWS Organizations onboarding of AWS member accounts (using StackSets) is coming soon.
  • AWS commercial partition Regions are supported; GovCloud and China are not supported.

General recommendations

  • We highly discourage onboarding AWS accounts that are actively monitored by our classic AWS integration. Onboarding such accounts might increase the likelihood of AWS APIs throttling, potentially resulting in service interruptions.
  • During the Preview, onboarding AWS accounts with business-critical workloads is not supported.

Prerequisites

Only a Dynatrace account administrator and an AWS admin can successfully complete the initial prerequisites.

Create AWS IAM baseline

Actions in this section can and (should) only be performed by an AWS administrator.

All necessary AWS permissions must be granted to successfully deploy the CloudFormation stacks and associated AWS resources.

In environments where full duty separation is practiced, we recommend that the Dynatrace administrator shares the templates with the platform team/AWS administrators.

Core CFN templates

Conditional CFN templates (deployed based on user opt-in during onboarding)

AWS IAM permission policy for deploying the CloudFormation stacks

Make sure that an AWS user, or a role, used for the CloudFormation stacks deployment is granted with the following (minimum) permission policies.

See the AWS permission policy

To allow the least privilege—restricting users creating the AWS connections that follow a specific naming pattern, use the value for <Deployment-Stack-Name-Prefix>. This ensures that any connection created must adhere to this exact naming convention.

{
  "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:<Deployment-Region>:<AWS-Account-ID>:stackset/Dynatrace*:*",
        "arn:aws:cloudformation:<Deployment-Region>:<AWS-Account-ID>:stack/<Deployment-Stack-Name-Prefix>*/*",
        "arn:aws:cloudformation:*:<AWS-Account-ID>:stack/StackSet-Dynatrace*/*",
        "arn:aws:cloudformation:*:<AWS-Account-ID>:type/resource/*"
      ]
    },
    {
      "Sid": "cloudformation1",
      "Effect": "Allow",
      "Action": [
        "cloudformation:GetTemplate",
        "cloudformation:ValidateTemplate",
        "cloudformation:GetTemplateSummary"
      ],
      "Resource": [
        "*"
      ]
    },
    {
      "Sid": "kms0",
      "Effect": "Allow",
      "Action": [
        "kms:CreateGrant",
        "kms:RevokeGrant"
      ],
      "Resource": [
        "arn:aws:kms:<Deployment-Region>:<AWS-Account-ID>:key/*"
      ]
    },
    {
      "Sid": "lambda",
      "Effect": "Allow",
      "Action": [
        "lambda:CreateFunction",
        "lambda:UpdateFunctionCode",
        "lambda:GetFunction",
        "lambda:InvokeFunction",
        "lambda:DeleteFunction",
        "lambda:TagResource",
        "lambda:UntagResource"
      ],
      "Resource": [
        "arn:aws:lambda:<Deployment-Region>:<AWS-Account-ID>:function:<Deployment-Stack-Name-Prefix>*"
      ]
    },
    {
      "Sid": "iam",
      "Effect": "Allow",
      "Action": [
        "iam:CreatePolicy",
        "iam:CreatePolicyVersion",
        "iam:SetDefaultPolicyVersion",
        "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>*"
      ]
    },
    {
      "Sid": "s3",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": [
        "arn:aws:s3:::dynatrace-data-acquisition/aws/deployment/cfn/*"
      ]
    },
    {
      "Sid": "secretsmanager",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:CreateSecret",
        "secretsmanager:DescribeSecret",
        "secretsmanager:UpdateSecret",
        "secretsmanager:GetSecretValue",
        "secretsmanager:PutSecretValue",
        "secretsmanager:TagResource",
        "secretsmanager:DeleteSecret"
      ],
      "Resource": [
        "arn:aws:secretsmanager:<Deployment-Region>:<AWS-Account-ID>:secret:DynatraceAPIAccessToken*",
        "arn:aws:secretsmanager:<Deployment-Region>:<AWS-Account-ID>:secret:DynatraceAPIPlatformToken*"
      ]
    },
    {
      "Sid": "kms1",
      "Effect": "Allow",
      "Action": [
        "kms:CreateKey",
        "kms:DescribeKey",
        "kms:GetKeyPolicy",
        "kms:PutKeyPolicy",
        "kms:ScheduleKeyDeletion",
        "kms:TagResource",
        "kms:UntagResource",
        "kms:CreateAlias",
        "kms:DeleteAlias",
        "kms:UpdateAlias"
      ],
      "Resource": "*"
    },
    {
      "Sid": "logs",
      "Effect": "Allow",
      "Action": [
        "logs:DeleteLogGroup",
        "logs:CreateLogGroup",
        "logs:DeleteLogStream",
        "logs:CreateLogStream",
        "logs:DescribeLogStreams",
        "logs:PutRetentionPolicy",
        "logs:TagResource",
        "logs:ListTagsForResource",
        "logs:DescribeIndexPolicies",
        "logs:DescribeLogStreams",
        "logs:AssociateKmsKey",
        "logs:DisassociateKmsKey"
      ],
      "Resource": [
        "arn:aws:logs:<Deployment-Region>:<AWS-Account-ID>:log-group:/aws/lambda/<Deployment-Stack-Name-Prefix>*"
      ]
    }
  ]
}

At this point all, the AWS IAM baseline prerequisites have been completed. Keep in mind that the IAM role/user permissions are needed for each onboarded AWS account.

We recommend that the AWS Admin pre-create those IAM constructs programmatically.

Create the Dynatrace IAM baseline

Actions in this section can and (should) only be performed by the Dynatrace account administrator.

The new AWS Platform Monitoring has been integrated with the core Dynatrace Identity & access management (IAM) design.

Learn more about the basic concepts:

In this documentation section context:

Dynatrace account admin

A built-in user with View and manage users and groups permission.

CloudAdminWrite

A customer-created IAM policy that contains all the (least privilege) permission scopes required to support the CloudAdmin IAM user AWS connection managment in Settings Settings.

CloudsAdmins

A customer-created custom IAM group where its members will be able to create and manage AWS connections in Settings Settings.

CloudAdmin

An IAM user, member of the CloudsAdmins group. The name is used here solely for context; any Dynatrace IAM user can be used.

Service user

A non-interactive IAM identity, against which platform tokens will be created.

Data-Acquisition AWS Integration

A built-in IAM policy that contains all the (least privilege) permission scopes required to support the creation of platform tokens for service users.

Platform token

The authentication and authorization secret used to establish secure communication with the Dynatrace APIs. In our context, two platform tokens are to be created:

  • Settings PT—allows the programmatic creation and managment of an AWS connection.
  • Ingest PT—allows the programmatic ingest of push-based telemetry from AWS.

Interactive IAM identity (IAM user)

  1. Create the CloudAdminWrite permission policy:

    1. Go to Account Management and choose the desired Dynatrace account.

    2. Go to Identity & access management > Policy management.

    3. In the upper-right corner, select Create policy.

      Policy name: CloudAdminWrite

      Policy description: Allow the cloud admin users or groups to fully admin (read and write) all cloud connections, from creation to deletion

    4. Copy and paste the Policy statement below:

      ALLOW environment:roles:manage-settings, settings:objects:read,
      extensions:configurations:read, extensions:configurations:write,
      extensions:definitions:read, data-acquisition:events:ingest,
      data-acquisition:logs:ingest, data-acquisition:metrics:ingest,
      storage:logs:read,storage:metrics:read, storage:smartscape:read,
      storage:events:read, storage:buckets:read, iam:service-users:use;

      The iam:service-users:use can be descoped to allow only a specific service user.

      Once you create the service user, the email ID can be used as a condition.

  2. Select Save.

  1. Create the CloudsAdmins group.

    Once the CloudsAdmins group is created, select Permissions > Scope and add the CloudAdminWrite and Standard User policies.

    Apply Account-Wide or Environment-Wide, then select Save.

    Validate: The CloudsAdmins Permissions section should show:

    • CloudAdminWrite
    • Standard User

  2. Assign your CloudAdmin IAM user as a member of the CloudsAdmins group.

Non-interactive IAM identity (service user)

  1. Create a service user.
    1. Use a meaningful name that allows others to understand the initial context, such as aws-east25-prod-aws-connections-tokens-perm.
    2. In step 3, Assign permissions, choose Directly and, in the Permission list, select the Data-Acquisition AWS Integration policy.

While a single service user can be used to vend multiple platform tokens supporting multiple AWS connections, some organizational policies may mandate the creation of a service user per connection. Consult our IAM documentation to learn more.

At this point, all the Dynatrace IAM baseline (one-off) prerequisites have been completed.

Onboarding

Before you start onboarding, make sure all the prerequisites are completed.

  1. Log in to Dynatrace as the IAM user (member of the CloudsAdmins IAM Group) and open Settings Settings.
  2. Go to Collect and capture > Cloud and virtualization > AWS (Preview) and select New connection.

If the button is grayed out, it means you do not have the proper permissions to create a connection. Please, contact your administrator.

1. Select connection model

  1. Enter a friendly connection name that is unique (for example, MyEastProd3Account).

  2. Enter the AWS Account ID where you intend to deploy the connection.

  3. Choose the Deployment region.

    The deployment region is the AWS Region from which the CloudFormation stack will be deployed.

  4. Select Next.

2. Select observability options

  1. Choose the Recommended observability path (expand onboarding observability options below to learn more):
Onboarding observability options

For now, the onboarding wizard supports two paths:

  • Recommended: The default and fastest way to onboard your AWS account. The monitoring configuration is an opinionated (immutable) settings flow—only monitored Regions are customizable. This flow provides:

    • AWS account resources inventory using Clouds Clouds (for supported AWS services).

    • AWS account resources topology, depicted as rich resource entities using Clouds Clouds (for supported AWS services).

    • Amazon CloudWatch API metric polling (per enabled region) for common services and their essential metric collection set.

    • Amazon Data Firehose stream (per enabled region), no auto-log-group subscription.

    Metric collection set is a group of metrics assigned to a supported AWS service. Once assigned, all metrics on this collection set will be scheduled for polling. For more information on service and metrics, see CloudWatch metrics.

  • Advanced: The most fine-grained path to onboard an AWS account. Allows you to fully customize the monitoring configuration to meet any 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.

  1. 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.

  2. Select Next.

After a successful onboarding, you'll be able to customize monitored AWS Regions and all other supported monitoring settings.

3. Get platform tokens for service users

Dynatrace settings token

  1. Select Platform tokens to open a new window redirecting to the platform tokens.

  2. Follow the instructions on how to create a new platform token.

    Generate the token for the Service user.

    Browse the drop down list and choose the relevant service user, which in our example is: aws-east25-prod-aws-connections-tokens-perm.

While it's possible to create a platform token and link it to your own Dynatrace IAM identity (Myself option), we strongly recommend NOT taking this approach.

Dynatrace IAM interactive users might be deleted. When they are deleted, all their linked platform tokens are also deleted, causing a potential service interruption.

If you have trouble—for example, you can't locate the service user on the dropdown list, or the Service user option is grayed out—see Troubleshooting.

  1. Select the following token scopes: 
    settings:objects:read
    settings:objects:write
    extensions:configurations:read
    extensions:configurations:write
    extensions:definitions:read
  2. Paste the newly created token into the Dynatrace settings token field.

Dynatrace ingest token

  1. Repeat steps 1 and 2 above and enable the following scopes:

    data-acquisition:logs:ingest
    data-acquisition:events:ingest
    data-acquisition:metrics:ingest

  2. Copy and paste the newly created platform token into the Dynatrace ingest token field.

  3. Select Download and Next.

    If the download button is grayed out, that means that the Dynatrace token fields are not populated with platform tokens.

Generating the platform tokens and granting permission scopes will not be effective if the service user is not granted the Data-Acquisition AWS Integration. For details, see Prerequisites.

4. Finalize

  1. Go to the AWS Console and log in to the designated AWS account with an AWS IAM user that has all the needed permissions to deploy the CloudFormation stacks.

  2. Select Deploy the CloudFormation in AWS Console.

If you practice roles duty separation, the Dynatrace admin may have no access/permissions to the AWS environment.

In this case, select the Copy Deployment Link.

Share this deeplink and the downloaded platform tokens CSV file with your platform team and/or AWS Admins.

This will allow them to deploy the CloudFormation stack with the wizard configurations that you have set.

  1. Copy the settings and ingest tokens from the downloaded CSV file (the file name will follow the connection friendly name) and paste them into the corresponding CloudFormation parameters (settings token, ingest token).

  2. Deploy the stack.

  3. When the CloudFormation stacks deployment finishes successfully (which can take up to 15 minutes), go back to the wizard and confirm.

If the CloudFormation stack deployment failed, see Troubleshooting.

Successful onboarding involves two elements:

  • In Settings Settings > Collect and capture > Cloud and virtualization > AWS (Preview), the new AWS connection is Healthy.
  • In the AWS CloudFormation console, the CloudFormation stacks are in CREATE_COMPLETE status.

What's next?

  • Go to Clouds Clouds. AWS resources with telemetry should start to appear shortly.

  • See Manage your AWS connections to learn how to manage your newly created connection.

  • Configure CloudWatch log group subscriptions.

  • Access our new launchpad to help you get started with the new AWS Platform Monitoring.

    1. Go to Launcher.
    2. Select Browse all.
    3. Select PREVIEW—AWS Cloud Platform Monitoring.

Troubleshooting

The New connection functionality is disabled. When I hover on it, I see a message that I don't have the permissions.

Make sure that your Dynatrace IAM user has the proper permission scopes to create and manage a connection. For details, see the Create the Dynatrace IAM baseline section.

The CloudFormation stack did not complete successfully. How do I troubleshoot for the root cause?

If your CloudFormation deployment fails, it's often related to a lack of AWS IAM permissions, AWS Service limits being reached, or Service Control Policies configured in your AWS Organizations.

To run our troubleshooting helper script to discover the root cause

  1. Open AWS CloudShell in the AWS Management Console.

    Alternatively, you can run bash with AWS CLI installed.

  2. Download the script:

    wget -q https://dynatrace-data-acquisition.s3.us-east-1.amazonaws.com/aws/deployment/cfn/da-activation-check.sh -O da-activation-check.sh && chmod +x ./da-activation-check.sh

  3. Run the script to analyze the failure reason and script output ./da-activation-check.sh --stack-name <activation-stack-name>.

    The activation main stack name follows the AWS connection name specified the Dynatrace connections list, for example, connection name: MyEastProd3Account

To find the failure reason manually

  1. Go to the AWS Management Console > CloudFormation stack events and search for the root cause.
  2. Also search nested stacks and stackset instances (if logs/events ingest was enabled) for failed events.

If you encounter an error that you cannot resolve on your own, open a Dynatrace support ticket providing the script output.

The root cause of the CloudFormation deployment failure is an invalid or expired token. What can I do?

The best way to solve this issue is to delete the failed stack and repeat the deployment specifying valid tokens as parameters. You can start the deployment from the Dynatrace Settings web UI to generate a new API token.

The root cause of the CloudFormation deployment failures are related to permissions, as I can see messages indicating that I'm not authorized to perform X or Y. What can I do?

If you can see in the CloudFormation stack error messages, such as "User: arn:aws: <...> is not authorized to perform: <...> on resource: <...>", it's because you haven't included the proper user/role permissions required from our policy. Update the setup by adding the required AWS permissions, clean the current setup, and restart the process.

To learn how to clean the current setup, see The CloudFormation stack did not complete successfully. I fixed the issue. How do I clean the current setup and start over?

The root cause of the CloudFormation deployment failure is that the 'Account XXX has not enabled 'Region-XYZ'. What can I do?

If you see, in the CloudFormation stack, error messages such as "Account XXX has not enabled [Region-XYZ]: ...", clean the current setup, enable that Region or remove it from the deployment parameters, and restart the process.

To learn how to clean the current setup, see The CloudFormation stack did not complete successfully. I fixed the issue. How do I clean the current setup and start over?

The root cause of the CloudFormation deployment failure is the creation of the Firehose DeliveryStream. What can I do?

If you see, in the CloudFormation stack, error messages such as "You are not subscribed to this service" or "The AWS Access key Id needs a subscription for the service (Service Firehose)", this is because new services, such as Firehose, require it to be enabled on some new accounts. See how to resolve problems when accessing a service in the AWS Management Console.

After enabling it, clean the current setup and restart the process again.

To learn how to clean the current setup, see The CloudFormation stack did not complete successfully. I fixed the issue. How do I clean the current setup and start over?

The root causes of the CloudFormation deployment failures are 404 or 400 errors. What can I do?

Please contact us at awscloudmonitoring-preview@dynatrace.com or open a Dynatrace support ticket sharing the errors you experienced.

The CloudFormation stack did not complete successfully. I fixed the issue. How do I clean the current setup and start over?

In the AWS CloudFormation console, delete the master Dynatrace stack. The main stack name follows the connection name in our example MyEastProd3Account. Follow the AWS guidelines on deleting stacks.

Once the stack and its nested stacks are completely deleted

  1. In Dynatrace, go to Settings Settings > Cloud and virtualization > AWS (Preview).
  2. Find and select the connection action menu on the right .
  3. Select Delete.
  4. You are now able to start the wizard and create a new connection.
Not all the resources created are properly tagged on Dynatrace.

Even if your organization enforces tagging via Service Control Policies or IAM, some of the resources created by CloudFormation do not support tag propagation. For details, please see AWS CloudFormation resource tagging.

I have enabled logs push-based ingest via Firehose, but I cannot seem to locate log records on Dynatrace.

Looking at the Destination error logs tab (AWS Firehose console), if you get this message:

Delivery to the endpoint was unsuccessful. See Troubleshooting HTTP Endpoints in the Firehose documentation for more information. Response received with status code. 403: "requestId":"xxxx,"errorMessage":"The authorization token does not provide the necessary permissions. details: missing_scopes=[data-acquisition:logs:ingest]

Verify that

  1. The platform ingest token is assigned with the correct permission scope (data-acquisition:logs:ingest).
  2. The Dynatrace service user linked to the token is also assigned with same token permission scope (data-acquisition:logs:ingest).
  3. The platform ingest token has not expired or was deleted.
  4. The service user has not been deleted.
  5. The platform token environment scope is adjusted to the correct Dynatrace environment.
When creating the platform token, why is the "service user" option grayed out?

Your IAM user might not have permission to create platform tokens for (existing) service users. Contact you Dynatrace Admin to learn if the prerequisites were followed. In this case, a specific permission scope must be granted.

Share your feedback

The onboarding experience is an evolving core product feature. We are continually working to collect feedback.

During the Preview, we will reach out and ask for feedback. We highly appreciate your willingness to share any suggestions. You can also share your feedback at our dedicated Dynatrace Community channel

Related tags
Infrastructure Observability