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 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	All OneAgent supported versions	x86-64,
Amazon Linux	All OneAgent supported versions	x86-64, ARM64 (AArch64¹)
Ubuntu	16.04, 18.04	x86-64, ARM64 (AArch64¹)
Red Hat Enterprise Linux	8.x	x86-64
SUSE Enterprise Linux	15.x	x86-64, ARM64 (AArch64¹)
¹ 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.

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

Open the AWS Systems Manager console.
In the navigation pane, select Distributor.
On the Distributor page, select Third party and select the DynatraceOneAgent package.
Select the installation mode. You can install or update the DynatraceOneAgent package one time or schedule the installation. For detailed information on installing the Distributor packages, see AWS Systems Manager Distributor documentation.
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. There are two options to provide a PaaS token.
- Via a centralized cloud password management system, such as AWS Secrets Manager or Parameter Store recommended
  Provide a PaaS token via AWS Secrets Manager
  1. Add additional permissions.
  2. Create a secret of type Other type of secret, and its value should be in plain text without any braces of double quotes.
  3. Reference the secret from Parameter Store. The secret name is constructed from /aws/reference/secretsmanager/ and secret_id—see the example below.
    
    json
    { "SSM_DYNATRACE_URL" : "https://environment.live.dynatrace.com/", "SSM_DYNATRACE_TOKEN_SECRET_NAME" : "/aws/reference/secretsmanager/dynatrace_paas_token", }
  Provide a PaaS token via Parameter Store
  1. Create a parameter of type SecureString.
  2. Provide a parameter name.
    
    json
    { "SSM_DYNATRACE_URL" : "https://environment.live.dynatrace.com/", "SSM_DYNATRACE_TOKEN_SECRET_NAME" : "dynatrace_paas_token", }
- SSM_DYNATRACE_TOKEN parameter
  
  Using the SSM_DYNATRACE_TOKEN parameter is not secure because the PaaS token will be visible in the Run Command history. To prevent security issues, deny the ssm:ListCommands permission before providing the PaaS token.
```
json
{
"SSM_DYNATRACE_URL" : "https://environment.live.dynatrace.com/",
"SSM_DYNATRACE_TOKEN" : "abcdefghij123456",
}
```
Example: Additional arguments in Systems Manager Run Command

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.

Example: successful installation output

plaintext
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

Switch to Dynatrace and select Deployment status from the navigation menu. Search for recently connected EC2 hosts to verify the result of the installation.

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. Dynatrace Managed Cluster is currently not supported. Note: Make sure you add trailing slash at the end of URL, for example `https://environment.live.dynatrace.com/`.
`SSM_DYNATRACE_TOKEN_SECRET_NAME`	N/A	N/A	The PaaS token key name in AWS Secrets Manager or Parameter Store, used to get the PaaS token value
`SSM_DYNATRACE_TOKEN`	N/A	N/A	The PaaS token used to download OneAgent installer.
`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`	`--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_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.

Troubleshooting

My package installation fails with 'You need to specify 'Additional Arguments' error

If your DynatraceOneAGentdistributor package installation fails with the following error:

plaintext
----------ERROR-------
install errors: failed to run commands: exit status 1
Failed to install package; install status Failed

Make sure that the Dynatrace-specific Additional Arguments you provided when installing the package are in a correct format and are using a valid JSON syntax.
If you're sure that your installation parameters are correct, make sure the AWS Systems Manager Agent installed on your EC2 instance is at the version 2.3.1569.0 or later. We successfully tested the distributor package with this version. It is recommended that you automate the process of keeping SSM Agent up-to-date on your instances. For more information, see Automate updates to SSM Agent.

My package installation fails with 'ERROR: wrong Dynatrace URL'

Make sure the URL you added for the SSM_DYNATRACE_URL argument has a trailing slash, for example https://environment.live.dynatrace.com/.

My package installation fails with 'ERROR: Can't retrieve Dynatrace PaaS token from secret store'

Check if the secret name is correct.
Make sure that the EC2 instance has permissions to access AWS Secrets Manager or Parameter Store.