Install OneAgent using Ansible
Dynatrace provides an Ansible collection that you can use to orchestrate OneAgent deployment in your environment.
Requirements
- Ansible >= 2.9.0, < 2.10.0
- OneAgent version 1.199+
- Dynatrace version 1.204+
- Script access to OneAgent installer files
Dependencies
- pywinrm 0.4.1+
Download the Dynatrace Ansible collection
-
Select Deploy Dynatrace from the navigation menu and then select Start installation.
-
Select 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.pem Resolving 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 OK Length: 2172 (2.1K) [application/x-pem-file] Saving to: ‘dt-root.cert.pem’ dt-root.cert.pem 100%[========================>] 2.12K --.-KB/s in 0s 2020-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.gz
The 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 variables oneagent_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:
Name | Default | Description |
---|---|---|
oneagent_environment_url | unset | The URL of the target Dynatrace environment (SaaS or Managed) |
oneagent_paas_token | unset | The PaaS token retrieved from the Deploy Dynatrace page |
oneagent_local_installer | unset | The path of the OneAgent installer stored on the control node |
oneagent_installer_arch | Linux: x86 Windows: x86 AIX: ppc | The OneAgent installer architecture |
oneagent_version | latest | The required version of the OneAgent in 1.199.247.20200714-111723 format |
oneagent_download_dir | Linux/AIX: $TEMP or /tmp Windows: %TEMP% or C:\Windows\Temp | The installer download directory—for Linux and AIX, the directory must not contain spaces. |
oneagent_install_args | unset | Dynatrace OneAgent installation parameters defined as a list of items |
oneagent_platform_install_args | unset | Additional list of platform-specific installation parameters, appended to `oneagent_install_args' when run on the respective platform |
oneagent_preserve_installer | false | Option to preserve the installer on the managed node after OneAgent installation |
oneagent_package_state | present | Desired OneAgent package state—specify present or latest to install. Specify absent to uninstall. |
oneagent_reboot_host | false | Option to reboot the managed node after OneAgent installation |
oneagent_validate_certs | true | Option to require certificates—if set to false , allows to download OneAgent from a server with an insecure SSL certificate (for example, expired or self-signed). |
oneagent_reboot_timeout | 3600 | Timeout, in seconds, for rebooting the managed node |
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 custom
directory with additional OneAgent install parameters. Both linux_other
and linux_arm have different user specified by platform args parameter.
hosts: linux_other,linux_arm
collections:
- dynatrace.oneagent
vars_files:
- encrypted_credentials.yml
vars:
oneagent_download_dir: /home/user1
oneagent_version: 1.199.247.20200714-111723
oneagent_install_args:
- INSTALL_PATH=/opt/example
- --set-host-group=My.HostGroup_123-456
- --set-network-zone=my.network.zone
tasks:
- 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.