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 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, pywinrm version 0.4.1+ is required. pywinrm is the Python client for the Windows Remote Management (WinRM) service.
• OneAgent Ansible collection is released as a Preview.

Download collection

Install collection

ansible-galaxy collection install dynatrace-oneagent-ansible-1.0.0.20200101-060000.tar.gz

Configure collection

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:

• oneagent_environment_url:

  • SaaS: https://{your-environment-id}.live.dynatrace.com
  • Managed: https://{your-domain}/e/{your-environment-id}

• 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'
  

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 oneagent_local_installer variable to point the script to the directory. For example,

oneagent_local_installer: /path/to/linux_installer.sh

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.

Variables

The following variables are available in the defaults/main/ file. If necessary, you can override them in your playbooks:

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.

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 secure credentials.yml file that stores your Environment ID and PaaS token
• instructs the script to deploy OneAgent to the host groups called linux_other and linux_arm in in your inventory
• instructs the script to use x86 as the default architecture for linux_other host group. The linux_arm host group has its own oneagent_installer_arch parameter specified in the inventory file.
• uses oneagent_install_args to pass the OneAgent installation parameters that assign the hosts to the My.HostGroup_123-456 host group and my.network.zone network zone, and enable the Infrastructure Monitoring mode.
• sets a different USER parameter using oneagent_platform_install_args 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
  # 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: 1.199.247.20200714-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 oneagentctl command-line interface.

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.