Ansible UAMS Client Role

The Ansible UAMS Client Role helps you install and set up the UAMS Client.

Setup

Requirements

• If you're using Windows, the ansible.windows collection is needed. You can install it on your controller with this command:

ansible-galaxy collection install ansible.windows

Installation

To install the UAMS Client role from Ansible Galaxy, run:

ansible-galaxy install solarwinds.uamsclient

To set up UAMS Client on your hosts, you must add access token, role, and swo url to your playbook under the environment section. It’s best to use a variable for the access token to keep it secure, instead of showing it as plain text.

You can also set an HTTPS proxy with the UAMS_HTTPS_PROXY environment variable, directing it to your proxy server. Note that this proxy will only affect connections made by the UAMS Client and its plugins. Make sure to set up your local machine’s HTTPS proxy too, so that Ansible can access it during installation.

Here’s an example:

  environment:
    UAMS_ACCESS_TOKEN: "YOUR_SWO_ACCESS_TOKEN"
    UAMS_METADATA: "ROLE"
    SWO_URL: "https://swo-url"
    UAMS_HTTPS_PROXY: "https://your-proxy" # optional
    UAMS_OVERRIDE_HOSTNAME: "custom_hostname" # optional

Check out the example playbook we use for CI testing.

Override Hostname

You can use the optional UAMS_OVERRIDE_HOSTNAME variable to customize the Agent name, which defaults to the hostname. Assign values from your inventory file as shown:

# Inventory file

[test_servers]
192.168.0.123 ansible_user=user override_hostname=web_server1
192.168.0.124 ansible_user=user override_hostname=web_server2

# Playbook file

  environment:
    UAMS_OVERRIDE_HOSTNAME: "DEV_{{ override_hostname }}"

Uninstallation

To uninstall the UAMS Client from your hosts, run the playbook with the uninstall tag. Example:

ansible-playbook -i inventory playbook.yml --tags uninstall

Refer to the example playbook we use for CI testing.

Adding DBO Plugin to UAMS Client

Overview

This Ansible role installs and configures the DBO plugin for the UAMS Client. To install the DBO plugin, run the following command:

ansible-playbook -i inventory playbook.yml --tags dbo

This will carry out the tasks for the dbo tag, installing and setting up the DBO plugin as defined in your inventory or variables files. Ensure your inventory and/or secrets are correctly set up before you run the playbook.

Configuration

To use the DBO plugin, you need to define the required variables in your Ansible inventory or secrets file. Here's what they look like: Also, you'll need a token with full access to work with the API for installing DBO plugins:

uams_full_access_token: "<full_access_token>"
dbo_plugin:
  - databaseType: "mongo"
    name: "mongodb profiler on dev-amd64-mu listening on 10.0.2.2:27018"
    host: "10.0.2.2"
    port: "27018"
    user: "myUser"
    password: "<password>"
    packetCaptureEnabled: false
    metricsCaptureMethod: "profiler"

Ways to Provide Variables

1. Inventory File: Place the dbo_plugin and uams_full_access_token variables directly in your inventory file.
2. Group or Host Variables
3. Ansible Vault: Recommended for sensitive info like passwords. Create an encrypted file for your secrets:

Encrypt this file using:

ansible-vault encrypt path/to/secrets.yml

Then include it in your playbook or inventory file:

vars_files:
  - path/to/secrets.yml

Role Variables

Variable	Description
uams_local_pkg_path	Where the installation package is stored (default: /tmp/uams)
uams_local_pkg_path_windows	Location to store the installation package on Windows (default: TEMP env variable)
uams_remove_installer	Whether to remove the installation package (default: true)

AWX

You can also use the UAMS Client role in an AWX setup. Here are the important points to consider:

1. AWX needs to be set up to download roles from Ansible Galaxy. In AWX version 0.30.0, enable this in Settings > Jobs (Enable Role Download) and set Ansible Galaxy credentials at the organization level. Your project repository should have a roles/requirements.yml for required roles (see example below).
2. Provide values for access token, role, and swo url from the AWX interface.
3. The playbook must specify a hosts: value that matches the hosts group or individual host in the AWX inventory.
4. Enabling Privilege escalation in the job template might cause issues for tasks directed at localhost because the sudo command may be missing in the execution container.

Example AWX Setup

Playbook

---
- name: Install UAMS client
  hosts: uams-hosts

  environment:
    UAMS_ACCESS_TOKEN: "{{ uams_access_token }}"
    UAMS_METADATA: "{{ uams_metadata }}"
    SWO_URL: "{{ swo_url }}"

  roles:
    - role: solarwinds.uamsclient

roles/requirements.yml

If you don’t specify a version, the latest version will be installed.

roles:
  - src: solarwinds.uamsclient
    version: 1.8.0