Install OneAgent using Ansible
Dynatrace provides an Ansible collection that you can use to orchestrate OneAgent deployment in your environment.
Requirements
- Ansible >= 2.15.0
- OneAgent version 1.199+
- Dynatrace version 1.204+
- Script access to OneAgent installer files
Dependencies
Windows
- pywinrm 0.4.1+
Download the Dynatrace Ansible collection
-
In Dynatrace Hub, select OneAgent.
-
Select Set up > Ansible collection to download the collection tarball. This is a safe archive hosted in your Dynatrace environment.
-
optional On Linux, you can verify the authenticity of the archive using the separately provided signature file:
- Select Signature to download the
sig
file. - Make sure the downloaded Ansible collection tarball and the signature file are stored in the same directory.
- Navigate to the directory where you saved the files and run the following command:
A successful verification results in the following output:wget https://ca.dynatrace.com/dt-root.cert.pem; openssl cms \-verify -binary \-in dynatrace-oneagent-ansible-1.0.0.20200101-060000.tar.gz.sig \-inform PEM \-content dynatrace-oneagent-ansible-1.0.0.20200101-060000.tar.gz \-CAfile dt-root.cert.pem >/dev/null--2020-09-25 12:40:47-- https://ca.dynatrace.com/dt-root.cert.pemResolving ca.dynatrace.com (ca.dynatrace.com)... 99.84.94.48, 99.84.94.69, 99.84.94.59, ...Connecting to ca.dynatrace.com (ca.dynatrace.com)|99.84.94.48|:443... connected.HTTP request sent, awaiting response... 200 OKLength: 2172 (2.1K) [application/x-pem-file]Saving to: ‘dt-root.cert.pem’dt-root.cert.pem 100%[========================>] 2.12K --.-KB/s in 0s2020-09-25 12:40:48 (102 MB/s) - ‘dt-root.cert.pem’ saved [2172/2172]Verification successful
- Select Signature to download the
Install the Dynatrace Ansible collection
-
Save the Dynatrace Ansible collection
Save the Ansible collection tarball to a directory on your Ansible control node. -
Install the Dynatrace Ansible collection
To install thedynatrace.oneagent
Ansible collection, navigate to the directory where you have saved the Ansible collection tarball and run the following command:ansible-galaxy collection install dynatrace-oneagent-ansible-1.0.0.20200101-060000.tar.gzThe collection consists of a single Ansible role, which deploys OneAgent using a dedicated configuration. The configuration ensures that the OneAgent service remains in a running state. For more information, see Using collections in Ansible documentation.
Configure the Dynatrace Ansible collection
The Ansible script requires access to the appropriate OneAgent installer files.
- If your Ansible control node has access to your Dynatrace environment, you can configure the script to download the installer files directly from the Dynatrace environment.
- Alternatively, you can download the appropriate installer files yourself—using the Dynatrace web UI—and upload them to the control node. This provides the script with local copies of the installers.
Option 1: Use direct download from Dynatrace environment
The script utilizes Deployment API to download the platform-specific installers to the managed nodes. You will need to specify the variables to supply the Ansible role with the information required to authenticate the API call in your environment:
-
oneagent_environment_url
:- SaaS:
https://{your-environment-id}.live.dynatrace.com
- Managed:
https://{your-domain}/e/{your-environment-id}
- SaaS:
-
oneagent_paas_token
-
The PaaS token of your environment
For example:
# Set environment variablesoneagent_environment_url: 'https://your-environment.live.dynatrace.com'oneagent_paas_token: 'abcdefjhij1234567890'
-
We recommend that you store both the PAAS-token and the environment-id securely, using encryption mechanisms such as Ansible Vault. For details, see Encrypting content with Ansible Vault.
Option 2: Use local installers
Use the Dynatrace web UI to download the required OneAgent installer files and then upload them to the control node. The Ansible script will then copy the installer files to the managed nodes during execution.
Use the oneagent_local_installer
variable to supply the Ansible role with the path of the installer file. For example:
oneagent_local_installer: /path/of/oneagent_linux_installer.sh
Note that Windows, Linux, and AIX require their dedicated installers. The original installer names, as downloaded from Dynatrace, include target platform designations. If you change the installer names, make sure the script can distinguish them.
If you don't specify a local installer, the script attempts to use the direct download method.
For sample usage, see the local_installer.yml
file in Examples.
Variables
The OneAgent Ansible role supports the following variables:
oneagent_environment_url
oneagent_local_installer
oneagent_installer_arch
x86
Windows:
x86
AIX:
ppc
oneagent_version
latest
oneagent_download_dir
$TEMP
or /tmp
Windows:
%TEMP%
or C:\Windows\Temp
oneagent_install_args
oneagent_platform_install_args
oneagent_preserve_installer
false
oneagent_package_state
present
present
or latest
to install. Specify absent
to uninstall.oneagent_reboot_host
false
oneagent_validate_certs
true
false
, allows to download OneAgent from a server with an insecure SSL certificate (for example, expired or self-signed).oneagent_reboot_timeout
Logging
Instead of being printed to STDOUT, the logs produced by Ansible can be collected into a single file located on the managed node. There are several ways to achieve this using Ansible configuration setting:
- Set the
ANSIBLE_LOG_PATH
environment variable to the path of the log file. - Specify the
log_path
variable in the[default]
section of Ansible's configuration settings file.
The verbosity of the logs can be controlled with the -v
command-line option.
Repeating the option multiple times increases the verbosity level up to the connection debugging level, which is achieved with -vvvv
.
Examples
The following example playbook:
- Downloads a OneAgent installer of a specific version (
oneagent_version
) and saves it to a custom directory (oneagent_download_dir
). - Uses the
vars_files
variable to point to a securecredentials.yml
file that stores your Environment ID and PaaS token. - Instructs the script to deploy OneAgent on the host groups called
linux_other
andlinux_arm
in your inventory - Instructs the script to use
x86
as the default architecture for thelinux_other
host group. Thelinux_arm
host group has its ownoneagent_installer_arch
parameter specified in the inventory file. - Uses the
oneagent_install_args
variable to specify the OneAgent installation parameters that assign the hosts to theMy.HostGroup_123-456
host group and to themy.network.zone
network zone. - Sets a different
USER
parameter using theoneagent_platform_install_args
parameter for each host group in the inventory.
---- name: Download OneAgent installer in specific version to a customdirectory with additional OneAgent install parameters. Both linux_otherand linux_arm have different user specified by platform args parameter.hosts: linux_other,linux_armcollections:- dynatrace.oneagentvars_files:- encrypted_credentials.ymlvars:oneagent_download_dir: /home/user1oneagent_version: 1.199.247.20200714-111723oneagent_install_args:- INSTALL_PATH=/opt/example- --set-host-group=My.HostGroup_123-456- --set-network-zone=my.network.zonetasks:- import_role:name: oneagent
You can find more example playbooks and inventory files in the examples
directory within the Ansible role. The directory contains the following playbooks:
local_installer.yml
— OneAgent installation using a local installer.advanced_config.yml
— OneAgent installation with a custom installation path and a download directory.oneagentctl_config.yml
— OneAgent configuration using theoneagentctl
command.
In addition, each directory contains an inventory file with a basic host configuration for playbooks.
For path issues when installing on Windows, review Path Formatting for Windows in Ansible documentation.