Ansible Configuration for .Net Agent MSI

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

The following sections provide the example use cases for the .Net Agent MSI Ansible role.

Important

Agent upgrade using this Ansible role does not retain the previous .Net Agent MSI configurations. It overrides the existing configuration with the configuration you specify in the role. If configuration details are not specified in the role, a default minimal configuration is used.
Ensure that you back up all important configurations before running this role.
.Net Agent MSI rollback is not supported in the following scenarios:

- If .Net Agent MSI was never installed on the machine or the previous .Net Agent MSI installation is not managed by this role
- If the rollback is already performed. Rollback to only one previous version is supported

Install .Net Agent MSI

Example 1: Ansible® role used to install .Net Agent MSI with the following basic features:

Installs the latest .Net Agent
Auto generates the Controller application name
Instruments all IIS applications. You must restart IIS after installation.

In this playbook, the parameters to communicate with the Controller are included from vars/args.yaml.

---
- name: .Net Agent MSI Minimal Configuration
  hosts: windows
  tasks:
    - name: Include variables for the controller settings
      # Include all yaml files under the vars directory
      ansible.builtin.include_vars:
        dir: vars
        extensions:
          - 'yaml'
          - 'yml'

    - ansible.builtin.include_role:
        name: appdynamics.agents.dotnet_msi

YML

Example 2: Ansible role used to install .Net Agent MSI with the following extended features:

Installs the .Net Agent version 22.12.0
Defines a specific Controller application name. You specify a controller application name that the role utilizes during configuration.
Instruments only specific IIS applications with or without default tier and node names. You must restart IIS after installation.
Instrument standalone applications with or without default tier and node names. You must restart the standalone applications after installation.

In the below playbooks, the parameters to communicate with the controller are defined in the playbook.

---
- name: .Net Agent MSI Extended Configuration
  hosts: windows
  tasks:
    - ansible.builtin.include_role:
        name: appdynamics.agents.dotnet_msi
      vars:
        agent_version: '22.12.0'
        # Your controller details
        controller_host_name: 'something.saas.appdynamics.com'
        controller_port: '443'
        enable_ssl: 'true'
        controller_account_name: 'customer1'
        controller_account_access_key: '123456'
        application_name: 'DotNetAgent_Application'

        monitor_all_IIS_apps: 'false'

        iis_applications:
            # instrument a web application 'PaymentService' under a web site 'Default Web Site'
          - site: 'Default Web Site'
            path: '/PaymentService'
            # default tier: 'site/path'
            # default node: 'host-tier'

            # instrument an entire web site 'BillingWebSite'
          - site: 'BillingWebSite'
            tier_name: 'BillingWebSiteTier'
            node_name: 'BillingWebSiteNode'

        standalone_applications:
            # instrument any execution of a standalone aplication 'login.exe'
          - executable: 'login.exe'
            # default tier: 'executable'
            # default node: 'host-tier'

            # instrument a standalone aplication 'checker.exe' with a specific set of command line arguments
          - executable: 'checker.exe'
            command_line: '-arg1 value1 -flag1'
            tier_name: 'CheckerTier'
            node_name: 'CheckedNode'

YML

.Net Agent Variables

Variable	Description	Possible Values	Required	Default
`custom_ad_setup_file`	Defines a local path to the custom installation configuration file on the Ansible control node. It can be a static file or a dynamic Jinja template.	System path	N
`custom_config`	Defines a local path to the custom `config.xml` static file on the Ansible controlling node. It takes precedence over other configuration settings.	System path	N
`enable_tls12`	Enable Controller SSL TLS1.2 connection.	[`true`, `false`]	N	`false`
`iis_applications`	List of IIS applications to monitor. It can be useful if `monitor_all_IIS_apps`=`false` or custom tier and node names are required for an application. See .NET Agent Configuration Properties.		N
`iis_application.site`	Name of the IIS website.		Y (for each IIS application if `iis_applications` is defined)
`iis_application.path`	Path to the IIS web application relative to the IIS website. The path must begin with '/'. If the path is missing the default value '/' indicates that all applications under the website are instrumented.		N	'/'
`iis_application.tier_name`	Controller Tier Name for the IIS application.		N	`iis_application.site/iis_application.path` (if the path is defined or `iis_application.site`
`iis_application.node_name`	Controller Node Name for the IIS application.		N	`hostname-iis_application.tier_name`
`monitor_all_IIS_apps`	Enable monitoring of all IIS applications.	[`true`, `false`]	N	`true`
`restart_app`	Set to `true` to restart the IIS if it is installed on the system. However, the role will not restart the standalone applications added or removed from instrumentation. All the applications added or removed from instrumentation must be restarted for agent changes to take effect.	[`true`, `false`]	N	`false`
`standalone_applications`	List of .Net standalone applications to monitor. See .NET Agent Configuration Properties.		N
`standalone_application.executable`	Name of the executable file for the standalone application (with or without extension).		Y (for each standalone application if `standalone_applications` is defined)
`standalone_application.command_line`	Command line arguments for the executable to limit the monitoring to a specific execution of the application.		N
`standalone_application.tier_name`	Controller Tier Name for standalone application.		N	`standalone_application.executable`
`standalone_application.node_name`	Controller Node Name for standalone application.		N	`hostname-standalone_application.tier_name`

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

Set .Net Agent MSI Environment Variables

You can use the ansible.windows.win_environment Ansible module to set .Net Agent MSI environment variables. The following example defines the APPDYNAMICS_AGENT_UNIQUE_HOST_ID environment variable on the system where the Agent will be installed. For more information, see Modify environment variables on Windows hosts.

---
- name: .Net Agent MSI Test Play
  hosts: windows
  tasks:
    - name: Include variables for the controller settings
      # Include all yaml files under the vars directory
      ansible.builtin.include_vars:
        dir: vars
        extensions:
          - 'yaml'
          - 'yml'

    - ansible.windows.win_environment:
        state: present
        name: 'APPDYNAMICS_AGENT_UNIQUE_HOST_ID'
        value: '{{ ansible_hostname }}' # can be jinja template like in this example or a static `value` if needed
        level: machine

    - ansible.builtin.include_role:
        name: appdynamics.agents.dotnet_msi

YML

Install and Upgrade .Net Agent MSI on a Certain Tier/Node

.Net Agent MSI performs a global machine-wise installation. You can not install different versions of the agent on the machine. Also, all applications on a machine are instrumented using the same version of the agent

To update the Agent on a specific Windows machine, create the Ansible inventory file and run the playbook on the desired hosts. For more information, see How to build your inventory.

---
# updating agent version on certain windows machines only
- name: .Net Agent MSI Test Play
 hosts: windows_region_1 # a group 'windows_region_1' should be defined in ansible inventory and lisy all desired machines
 tasks:
   - ansible.builtin.include_role:
       name: appdynamics.agents.dotnet_msi
       vars:
         agent_version: '22.12.0' # or providing custom_config or any other changes to the configuration

YML

To update the list of instrumented applications within a machine, add or remove the desired application from the role configuration and rerun the playbook.

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