Dynatrace provides an Ansible collection that you can use to orchestrate OneAgent deployment in your environment.
- OneAgent version 1.199+
- Dynatrace version 1.204+
- PaaS token to download the collection
- Ansible version 2.9.x
- Supported on Windows, Linux and AIX.
- For deployment on a Windows platform, scripts support both SSH and WinRM protocols. For WinRM,
pywinrmversion 0.4.1+ is required.
pywinrmis the Python client for the Windows Remote Management (WinRM) service.
- OneAgent Ansible collection is released as a Preview.
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 environment. Place the resulting artifact in your Ansible control node.
optional On Linux, you can verify the authenticity of the archive using the detached signature file.
- Select Signature to download the
- 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:
The successful verification results in a following output
wget https://ca.dynatrace.com/dt-root.cert.pem; openssl cms \ -verify -binary \ -in dynatrace-oneagent-ansible-126.96.36.19900101-060000.tar.gz.sig \ -inform PEM \ -content dynatrace-oneagent-ansible-188.8.131.5200101-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)... 184.108.40.206, 220.127.116.11, 18.104.22.168, ... Connecting to ca.dynatrace.com (ca.dynatrace.com)|22.214.171.124|: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
Save the collection
Save the collection tarball to a directory on your Ansible cluster.
Navigate to the directory where you saved the collection tarball and run the following command:
ansible-galaxy collection install dynatrace-oneagent-ansible-126.96.36.19900101-060000.tar.gz
This will install
dynatrace.oneagent collection that consist of a single role that deploys OneAgent using dedicated configuration and ensuring the OneAgent service maintains a running state. For more information, see Using collections in Ansible documentation.
The Ansible script requires access to the OneAgent installer. Depeneding on whether your Ansible cluster has access to your Dynatrace environment, you can either
- configure the script to download the installer directly from your Dynatrace environment,
- download it yourself and upload it to the primary node.
Direct download from your environment
The script utilizes Deployment API to download a platform-specific installer to the target machine. You will need to specify the variables to supply the role with information required to authenticate the API call in your environment:
- The PaaS token of your environment
# Set environment variables oneagent_environment_url: 'https://your-environment.live.dynatrace.com' oneagent_paas_token: 'abcdefjhij1234567890'
It's recommended to save credentials in a secure file, that can be called in your playbook using
vars_files property. See Examples.
You can use the Dynatrace UI to download OneAgent and then upload it to a directory on the primary node. Use the
oneagent_local_installer variable to point the script to the directory. For example,
The script copies the installer to target machines during execution.
Note that Windows, Linux, and AIX require their dedicated installers. Original installer names indicate the target platform. If you need to change the installer names, make sure the script can distinguish them.
If you don't specify the installer, the script attempts to use the direct download.
For sample usage, see the
local_installer.yml file in Examples.
The following variables are available in the
defaults/main/ file. If necessary, you can override them in your playbooks:
||unset||URL of the target Dynatrace environment (SaaS or Managed).|
||unset||The PaaS token retrieved from the Deploy Dynatrace page.|
||unset||The Path to OneAgent installer stored on the main node.|
|Specifies the installer architecture.|
||The required version of the OneAgent in 188.8.131.5200714-111723 format.|
|Installer's download directory. For Linux and AIX, the directory must not contain spaces.|
||unset||Dynatrace OneAgent installation parameters defined as a list of items.|
||unset||Additional list of platform-specific installation parameters, appended to `oneagent_install_args' when run on a respective platform|
||Preserves installers on secondary machines after deployment.|
||OneAgent package state; use
||Reboot the secondary machine after OneAgent installation.|
||If set to
||3600||Set the timeout for rebooting secondary machine in seconds.|
Set up Windows hosts
Deployment on Windows requires setting up WinRM listener or OpenSSH. For instructions, see Setting up a Windows Host in Ansible documentation.
This example playbook
- downloads the OneAgent installer in a specific version (
oneagent_version) and saves it to a custom directory (
vars_filesproperty points to a secure
credentials.ymlfile that stores your Environment ID and PaaS token
- instructs the script to deploy OneAgent to the host groups called
linux_armin in your inventory
- instructs the script to use x86 as the default architecture for
linux_otherhost group. The
linux_armhost group has its own
oneagent_installer_archparameter specified in the inventory file.
oneagent_install_argsto pass the OneAgent installation parameters that assign the hosts to the
My.HostGroup_123-456host group and
my.network.zonenetwork zone, and enable the Infrastructure Monitoring mode.
- sets a different
oneagent_platform_install_argsfor 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 # credentials.yml file contains oneagent_environment_url and # oneagent_paas_token variables that needs to be stored securely vars_files: - credentials.yml vars: oneagent_installer_arch: x86 oneagent_download_dir: /home/user1 oneagent_version: 184.108.40.20600714-111723 oneagent_install_args: - INSTALL_PATH=/opt/example - GROUP=example_group - --set-host-name=new_host_name - --set-host-tag=new_tag - --set-host-property=property1 - --set-host-property=other=property tasks: - import_role: name: oneagent
You can find more example playbooks and inventory files in the
examples directory within the role. The directory contains the following playbooks:
local_installer.yml— basic configuration with local installers.
advanced_config.yml— showing advanced configuration as in example above.
oneagentctl_config.yml— showing bare configuration using
Additionally, each directory contains an inventory file with basic host configuration for playbooks.
Note: For multi-platform Windows, Linux or AIX deployment, you must specify the
become: true option for proper machines group in the inventory file. On Windows,
become: true option is not supported.
Since Windows paths are different from those on Linux systems, see Path Formatting for Windows to avoid issues related to paths.