Install OneAgent using Ansible
Preview
Dynatrace provides an Ansible collection that you can use to orchestrate OneAgent deployment in your environment.
Prerequisites
- OneAgent version 1.199+
- Dynatrace version 1.204+
- PaaS token to download the collection
- Ansible 2.9.0+
- In case of deployment on a Windows platform,
pywinrm
version 0.4.1+. is required.pywinrm
is the Python client for the Windows Remote Management (WinRM) service. - Supported on Windows, Linux and AIX.
- OneAgent Ansible collection is released as a Preview.
Download 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 environment.
Optional On Linux, you can verify the authenticity of the archive using the detached 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:
The successful verification results in a following outputwget 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
Install collection
Save the collection
Save the collection tarball to a directory on your Ansible cluster.
Install collection
Navigate to the directory where you saved the collection tarball and run the following command:
ansible-galaxy collection install dynatrace-oneagent-ansible-1.0.0.20200101-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.
Configure collection
Tha 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:
-
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'
- The PaaS token of your environment
It's recommended to save credentials in a secure file, that can be called in your playbook using vars_files
property. See Examples.
Local installer
You can use the Dynatrace UI to download OneAgent and then upload it to a directory on the primary node. Use the local_installer
variable to point the script to the directory. For example,
oneagent_local_installer:
aix: /path/to/dynatrace-aix-installer.sh
linux: /path/to/dynatrace-linux-installer.sh
win32nt: /path/to/dynatrace-windows-installer.msi
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.
Variables
The following variables are available in the defaults/main/
file. If necessary, you can override them in your playbooks:
Name | Default | Required1 | Description |
---|---|---|---|
oneagent_environment_url |
unset | ✔️ | URL of the target Dynatrace environment (SaaS or Managed). |
oneagent_paas_token |
unset | ✔️ | The PaaS token retrieved from the "Deploy Dynatrace" installer page. |
oneagent_local_installer |
unset | ✔️ | Dictionary of paths to local installer, available keys are: win32nt , linux and aix . |
oneagent_verify_signature |
true |
Enables installer's signature verification after downloading it from the environment. Not supported on Windows. | |
oneagent_installer_arch |
Linux: x86 Windows: x86 AIX: ppc |
Specifies the 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 |
Installer's download directory. The directory must be available to the script. 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_preserve_installer |
false |
Preserves installers on secondary machines after deployment. | |
oneagent_package_state |
present |
OneAgent package state; use present or latest to make sure it's installed, or absent in order to uninstall. |
1 Depending on the way your script accesses the OneAgent installer, one of the two is required: oneagent_environment_url
plus oneagent_paas_token
, or oneagent_local_installer
.
Examples
This example playbook
- downloads the OneAgent installer in a specific version (
oneagent_version
) and saves it to a custom directory (oneagent_download_dir
) vars_files
property points to a securecredentials.yml
file that stores your Environment ID and PaaS token- instructs the script to deploy OneAgent to the
hosts
tagged aslinux_other
in your inventory - instructs the script to use the
ppcle
installer architecture - uses
oneagent_install_args
to pass the OneAgent installation parameters that assign the hosts to theMy.HostGroup_123-456
host group andmy.network.zone
network zone, and enable the Infrastructure Monitoring mode.
- name: Download OneAgent installer in specific version to a custom directory with additional OneAgent install parameters
hosts: linux_other
collections:
- dynatrace.oneagent
# File contains variables oneagent_environment_url and oneagent_paas_token that needs to be stored securely
vars_files:
- credentials.yml
vars:
oneagent_installer_arch: ppcle
oneagent_download_dir: /home/user1
oneagent_version: 1.199.247.20200714-111723
oneagent_install_args:
- –-set-host-group=My.HostGroup_123-456
- --set-network-zone=my.network.zone
- --set-infra-only=true
tasks:
- import_role:
name: oneagent
You can find more example playbooks in the examples
directory within the role. The directory contains the following playbooks:
local_installer.yml
- basic configuration with local installers.host_properties.yml
- showing the way of setting custom properties.advanced_config.yml
- showing advanced configuration as in example above.
Additionally, the example_inventory.yml
file contains basic hosts 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 than on a Linux system, see Path Formatting for Windows to avoid issues related to paths.