Ansible

This document contains references to the Ansible® documentation. AppDynamics does not own any rights and assumes no responsibility for the accuracy or completeness of such third-party documentation.

The AppDynamics Ansible Collection installs and configures AppDynamics agents. You can automatically download all the supported agents from the Ansible Galaxy to the Ansible® control node. If you are using the on-prem version, download the agents from the local repository. This makes it easy to retrieve and upgrade agents.

For a description of available deployment options, see Common Role Variables.

The AppDynamics Ansible Collection is built to support (immutable) infrastructure as code deployment, where agents are upgraded with basic configuration. Hence, the collection does not consider any manual configuration changes on the target servers.

Custom agent configurations are supported only if these configurations are written to an Ansible role. The AppDynamics Ansible Collection will overwrite any local or pre-existing configuration with the variables that are defined in the playbook. Therefore, we strongly recommend that you convert any custom agent configuration into an Ansible role to ensure consistency of deployments and configurations across your estate.

The following diagram explains the workflow:

Download AppDynamics Agents from the AppDynamics Download portal or custom endpoint

Download the AppDynamics Ansible Collection from galaxy.ansible.com. 

(Optional) Download the agent binaries from the custom endpoint if maintaining a file server.

Configure the agents using playbook. See Playbooks.

The Control Node, which comprises of file server and playbooks, pushes the configuration to the managed nodes.

Requirements

• Requires Ansible >=2.12.0

• Supports most Debian and RHEL-based Linux distributions, and Windows

  

  The AppDynamics Ansible Collection supports auto-instrumentation of JBoss(Wildfly) and Tomcat, on Linux only.

• Windows OS requires Powershell >=  5.0
• Network/firewall access to download AppDynamics agents from https://download-files.appdynamics.com and https://download.appdynamics.com on the Ansible control node
• jq is required on the Ansible control node. It is recommended that you install it manually (this requires sudo access), or run the install_jq.yaml playbook in the playbook folder. For example: ansible-playbook install_jq.yaml --ask-become-pass -e 'ansible_python_interpreter=/usr/bin/python'
• lxml is required if you need to enable enhanced agent logging (DEBUG, TRACE, and so on). We recommend that you install it manually on the Ansible control node using pip3 install lxml, or run the install_lxml.yaml playbook in the playbook folder
• Download the Agent playbook based on the application

Important

• If multiple agents are restarted simultaneously after installation, it can cause performance issues on Controller. We recommend restarting the applications in a phased manner.
• If you are downloading agents from AppDynamics Downloads Portal, we recommend using a fork value of 20. You can use a custom download path for a higher fork value. See Custom Download Path.

Install the AppDynamics Collection

1. Use the following command on your Ansible control node to install the AppDynamics Collection from Ansible Galaxy. Do not add -force if you are installing it for the very first time.

   ansible-galaxy collection install --force appdynamics.agents

   CODE

2. (Optional) If you are using a local file server as a custom endpoint use the following command:

   ansible-galaxy collection install ./appdynamics-agents-<version>.tar.gz

   CODE

3. Create a playbook (for example, customer-playbook.yml) with configuration to install and deploy AppDynamics agents in the managed machines using the ansible-playbook command.

   Example

   $ ansible-playbook customer-playbook.yml

   CODE

4. (Optional) Configure the ansible.cfg file with the following command to log the agent installation status.
    

   [defaults]
   callbacks_enabled=  appdynamics.agents.appd_agent_status

   CODE

The tools for managing agents do not impact extensions deployed or installed outside the agent install directory. For Machine agents, the tools for managing agents ensure that Machine Agent extensions are re-deployed after an upgrade. If you are uncertain about the potential impact of the extensions that you may be using, contact your Account Manager or Customer Success Manager. You can also use our support portal.

Playbooks

The playbooks folder in the AppDynamics Ansible Collections contains example playbooks for each agent type.
You can use the example playbooks in the collection installation folder.

The playbooks/vars directories contain constant variables such as enable_ssl, controller_port, etc. You can either include YAML files in the playbook as shown in the following Java example, or overwrite the variables in the playbooks.

Check the precedence rules of Ansible, before continuing the installation.

When you install the AppDynamics Collection, you can use the following agents:

Custom Agent Download Path

This is not applicable to .Net Agent MSI.

If you do not want playbooks to download the agent files from the official AppDynamics Downloads portal, you can use the following variable in playbooks to install the agents from your preferred location.

Common Role Variables

Variable	Description	Applicable Agents
agent_action	To perform an upgrade, install, rollback, or uninstall.	All
agent_dir_permission.user	To assign user file permissions for the Java Agent on Linux. The user and group selected must already exist on the host if create_appdynamics_user is set to No.	Java
agent_dir_permission.group	To assign group file permissions for the Java Agent on Linux. The user and group selected must already exist on the host if create_appdynamics_user is set to No.	Java
agent_log_level	The log level for the agent. The valid options are — info, trace, debug, warn, error, fatal, all, and off. This setting is applied to all the loggers named in the agent_loggers list.	Java, Machine, PHP
agent_loggers	To set the log level on the list of loggers. The logger names vary from agent to agent. The default is set to *, com.singularity, com. Update this variable with loggers specific to the target agent. See log4j files in the /conf/logging directory.	Java, Machine
agents_to_set_loggers_for	The list of agents to apply the log-level changes. For example, to set the log level of all deployed agents to info, initialize the variable to java. This variable should not be set when using the logger role as part of agent deployments. The agent_type variable will be used to determine how the log level needs to be adjusted during the installation.	Java, Machine
agent_type	The AppDynamics agent type. For example, java.	All
agent_version	The AppDynamics agent version. The value can be latest or an agent version, for example, 23.2.0. AppDynamics uses calendar versioning. For example, if a Java Agent is released in February of 2023, its version will be 23.2.0.	All
appdynamics_user	AppDynamics functional user name. The default is appdynamics.	Java, Machine
application_name	The application name. This variable is mandatory for all the java roles.	All
controller_account_name	The AppDynamics Controller account name.	All
controller_account_access_key	The access key for the Controller account. This should be placed in the vault.	All
controller_host_name	The Controller hostname. Do not include http(s).	All
controller_port	The Controller port.	All
create_appdynamics_user	To create AppDynamics functional user on Linux.	Java, Machine
dir	The base directory for agent files. Default: /tmp/appd/	All
enable_proxy	Set to true to apply agent proxy settings to the agent configuration. Assign the proxy_host and proxy_port variables.	Java, .Net
enable_ssl	Indicate if SSL is enabled in the Controller or not.	All
init_and_validate_agent_variables	This variable controls running the common role initialization (which sets download URLs and Controller parameters). When using the logger role in isolations (that is not as part of agent installation) the value should be false.	Java, Machine
keep_backup	Use when agent_action is uninstall. Set to true to keep the agent backup files after uninstalling. Default value is false.	Apache, Java, Machine, Node.js, PHP, Python
linux_install_root	Use this to configure the folder where all installed agent and backup files reside. For example, for Java agent, <linux_install_root>/java-agent and <linux_install_root>/backup/java-agent is created. The default value is /opt/appdynamics for Linux.	Apache, Java, Machine, Node.js, PHP, Python
linux_custom_agent_install_path	Use this to specify the Agent installation path and override the default installation path which is the root directory (see linux_install_root). The agent backup resides in the root directory and is not configured by this variable. The agent files are installed in this directory. Do not specify this path to store the files of linux_install_root.	Apache, Java, Machine, Node.js, PHP
max_agent_backup_count	Maximum allowed backups per agent. The default value is one.	Java
node_name	The AppDynamics node name for java roles.	Apache, Java, Machine, Node.js, PHP, Python
proxy_host	Host name/IP address of the proxy to route agent data.	Java, .Net
proxy_port	Host port number of the proxy to route agent data.	Java, .Net
tier_name	The AppDynamics tier name. This variable is mandatory for all the java roles.	Apache, Java, Machine, Node.js, PHP, Python
windows_install_root	Similar to linux_install_root, to be used on Windows hosts. The default value is C:/appdynamics.	Apache, Java, Machine, Node.js, PHP, Python
windows_custom_agent_install_path	Similar to linux_custom_agent_install_path, to be used on  Windows hosts.	Apache, Java, Machine, Node.js, PHP, Python

To get started, select your agent:

Ansible® is a registered trademark of Red Hat, Inc. in the United States and other countries.