Deploy OneAgent using AWS Systems Manager Distributor

With the AWS Systems Manager Distributor you can distribute and automatically deploy OneAgent on your EC2 instances using the AWS Systems Manager Distributor.

Prerequisites

Before you start deploying the DynatraceOneAgent distributor package, make sure your Amazon EC2 instances meet the following prerequisites:

AWS tags

AWS tags on instance metadata are turned off by default at launch. To allow them follow the official AWS documentation.

AWS Systems Manager

AWS Systems Manager must be set up for your AWS account and AWS Systems Manager Agent (SSM Agent) must be installed on the EC2 instances where you want to deploy DynatraceOneAgent distributor package. Follow the AWS Systems Manager Quick Setup or more comprehensive Setting up AWS Systems Manager.

Supported operating systems

The DynatraceOneAgent distributor package is supported on the following operating systems:

Operating system
Version
Architecture
Windows
x86-64,
Amazon Linux
x86-64, ARM64 (AArch641)
Ubuntu
16.04, 18.04, 22.04
x86-64, ARM64 (AArch641)
Red Hat Enterprise Linux
8.x, 9.x
x86-64
SUSE Enterprise Linux
15.x
x86-64, ARM64 (AArch641)
1

Support for ARM64 architecture, including AWS Graviton processors, is in Early Adopter release.

Wget

Dynatrace OneAgent distributor package requires Wget installed on your Linux-based instance. If there's no Wget installed on your instance, the OneAgent distributor package will install it for you automatically. Wget is necessary to download the latest OneAgent version.

AWS CLI

AWS CLI is required if you're using Parameter Store or Secrets Manager to store the PaaS token. If there's no AWS CLI installed, the OneAgent distributor package will install the latest version.

If your instance is running AWS CLI version 1, you need to add the SSM_DYNATRACE_TOKEN_REGION parameter with the region where your instance is running to the SSM Distributor configuration, as region autodiscovery via EC2 IMDS is only available in AWS CLI version 2.

Limitations

Deploying OneAgent using AWS Systems Manager Distributor is currently not supported if you set Dynatrace Managed Cluster as the SSM_DYNATRACE_URL parameter value.

Installation

To install the DynatraceOneAgent distributor package

  1. Open the AWS Systems Manager console.

  2. In the navigation panel, select Distributor.

  3. On the Distributor page, select Third party and select the DynatraceOneAgent package.

  4. Select the installation mode. You can install or update the DynatraceOneAgent package one time or schedule the installation. For details on installing the Distributor packages, see AWS Systems Manager Distributor documentation.

  5. To configure the DynatraceOneAgent package installation, add the parameters to the Additional Arguments field of the Systems Manager Run Command. The parameters require a PaaS token.

    To provide a PaaS token, we recommend using a centralized cloud secret management system, such as AWS Secrets Manager or Parameter Store.

    • Provide a PaaS token via AWS Secrets Manager recommended

      1. Create a secret:

        aws secretsmanager create-secret --name dynatrace-paas-token --secret-string "paas_token_value"

      2. Add an IAM policy to the IAM role attached to your EC2 instance(s) that grants access to retrieve the secret from the Secrets Manager. Here's an example policy that's attached to the IAM role (other options can be found in the AWS User Guide):

        {
          "Version": "2012-10-17",
          "Statement": [
            {
              "Effect": "Allow",
              "Action": "secretsmanager:GetSecretValue",
              "Resource": "arn:aws:secretsmanager:us-east-2:123456789012:secret:dynatrace-paas-token"
            }
          ]
        }

        If your Secret is encrypted with a CMK KMS Key, you also need to grant Decrypt permissions on both: the IAM Role and the KMS Key policy. For more information, check the AWS Secrets Manager documentation.

      3. Provide the secret name via SSM_DYNATRACE_TOKEN_SECRET_ID on the SSM Distributor package parameters. Example:

        {
          "SSM_DYNATRACE_URL" : "https://environment.live.dynatrace.com/",
          "SSM_DYNATRACE_TOKEN_SECRET_ID" : "dynatrace-paas-token"
        }

    • Provide a PaaS token via Parameter Store recommended

      1. Create a SecureString parameter type.

        aws ssm put-parameter --name "dynatrace-paas-token" --value "paas_token_value" --type "SecureString"

      2. Add an IAM policy to the IAM Role attached to your EC2 instance(s) that grants access to retrieve the secret from the Parameter Store. Here's an example policy. For more information, check the AWS Systems Manager Documentation.

        {
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Effect": "Allow",
                    "Action": [
                        "ssm:GetParameter"
                    ],
                        "Resource": "arn:aws:ssm:us-east-2:123456789012:parameter/dynatrace-paas-token"
                }
            ]
        }

      3. Provide the secret name via SSM_DYNATRACE_TOKEN_PARAMETER_NAME on the SSM Distributor parameters. Example:

        {
        "SSM_DYNATRACE_URL" : "https://environment.live.dynatrace.com/",
        "SSM_DYNATRACE_TOKEN" : "abcdefghij123456",
        }

    • Provide a PaaS token via SSM_DYNATRACE_TOKEN env variable. not-recommended

      Using the SSM_DYNATRACE_TOKEN parameter is not secure because the PaaS token will be visible in the Run Command history.

    AWS distributor

    {
    "SSM_DYNATRACE_URL" : "https://your-tenant.live.dynatrace.com/",
    "SSM_DYNATRACE_HOST_GROUP" : "MY-HOST-GROUP",
    "SSM_DYNATRACE_MONITORING_MODE" : "infra-only",
    "SSM_DYNATRACE_APP_LOG_CONTENT_ACCESS" : "true",
    "SSM_DYNATRACE_TOKEN_SECRET_ID" : "dynatrace-paas-token"
    }

  6. Verify the installation.

    • After you run the installation, check the progress in the Command status area. When you see the Success status it means the installation was successful.
    Initiating DynatraceOneAgent_ 1.0.51 install
    Plugin aws:runPowerShellScript ResultStatus Success
    install output: Running install.ps1
    Installing Dynatrace OneAgent on Windows...
    script version: 1.0.51
    Configuration parameters:
    - Dynatrace URL: https://environment.live.dynatrace.com/
    --quiet
    Installing Dynatrace Package on Windows...
    - downloading agent from: https://environment.live.dynatrace.com/ to: %PROGRAMDATA%\Amazon\SSM\Packages\DynatraceOneAgent_\1.0.51\Dynatrace-OneAgent-Windows.exe
    - running installation
    - cleaning up
    Done
    Successfully installed DynatraceOneAgent_ 1.0.51
    • In Dynatrace, go to Deployment Status. Search for recently connected EC2 hosts to verify the result of the installation.

  7. Restart all processes that you want to monitor. You’ll be prompted with a list of the processes that need to be restarted. Note that you can restart your processes at any time, even during your organization’s next planned maintenance period. Though until all processes have been restarted, you’ll only see a limited set of metrics, for example CPU or memory consumption.

Installation parameters

The DynatraceOneAgent distributor package provides a number of Dynatrace-specific parameters that map directly to the following OneAgent installation parameters.

Learn more about customizing OneAgent installation on Linux and Windows.

Distributor parameter

Maps to OneAgent parameter

Default value

Description

SSM_DYNATRACE_URL

--set-server

environment specific

The address of the OneAgent communication endpoint, which is a Dynatrace component that OneAgent sends data to. Depending on your deployment, it can be a Dynatrace SaaS cluster or an ActiveGate. A Dynatrace Managed Cluster is currently not supported. Note: Make sure you add a trailing slash at the end of URL (for example, https://environment.live.dynatrace.com/).

SSM_DYNATRACE_HOST_GROUP

--set-host-group

unset

The name of a host group you want to assign the host to.

SSM_DYNATRACE_INFRA_ONLY deprecated 1

--set-infra-only

false

Activates Infrastructure Monitoring mode, in place of Full-Stack Monitoring mode. With this approach, you receive infrastructure-only health data, with no application or user performance data.

SSM_DYNATRACE_MONITORING_MODE 1

--set-monitoring-mode

fullstack

When set to infra-only, activates Infrastructure Monitoring mode, in place of Full-Stack Monitoring mode. With this approach, you receive infrastructure-only health data, with no application or user performance data.

SSM_DYNATRACE_APP_LOG_CONTENT_ACCESS

--set-app-log-content-access

true

When set to true, allows OneAgent to access log files for the purpose of Log Monitoring.

SSM_DYNATRACE_TOKEN_SECRET_ID 2

N/A

N/A

The PaaS token secret name or ARN in Secrets Manager, used to get the PaaS token value.

SSM_DYNATRACE_TOKEN_PARAMETER_NAME 2

N/A

N/A

The PaaS token parameter name in Parameter Store, used to get the PaaS token value.

SSM_DYNATRACE_TOKEN_REGION

N/A

N/A

Optional AWS region used to get a secret from a different region. If not set, the AWS CLI auto discovers the instance region. (This parameter is required if you're running AWS CLI v1, as it can't discover the instance region from EC2 IMDS).

SSM_DYNATRACE_TOKEN not-recommended

N/A

N/A

The PaaS token used to download the OneAgent installer. Using the SSM_DYNATRACE_TOKEN parameter is not secure because the PaaS token will be visible in the Run Command history. Use AWS Secrets Manager or AWS Systems Manager Parameter Store.

1

SSM_DYNATRACE_MONITORING_MODE replaces deprecated SSM_DYNATRACE_INFRA_ONLY.

2

Remember that SSM_DYNATRACE_TOKEN_PARAMETER_NAME and SSM_DYNATRACE_TOKEN_SECRET_ID are mutually exclusive. Choose either one.

Troubleshooting

Related topics