Documentation is now available for the Fall 2020 Update release!

Managing Agents with Ansible

Describes how to deploy, install, uninstall, migrate and update agents on target resources with Ansible.

Leave Feedback

Introduction

Ansible is a simple and easy-to-use configuration management tool. Designed for multi-tier application deployment, this configuration management and provisioning tool uses SSH to connect to servers and run the configured tasks. 

Prerequisites

  • An Ansible server - where Ansible is installed on one of the servers.
  • SSH installed on all the target resources and the resources must communicate with the Ansible server.
  • Public keys of all the target resources are shared with the Ansible server. Log into target devices on the Ansible server to share.
  • The OpsRamp URL is allowed on the Ansible server. This allows you to download all the latest agent packages.
  • The resource user must have sudo permissions.

Downloading Ansible

Ansible is available for download from OpsRamp.

To download Ansible and extract files:

  1. Download OpsRamp Ansible from OpsRamp. To download, on OpsRamp Setup, navigate to Downloads > Agent and click Download for Ansible Agent Deployments.
  2. Copy downloaded repository to /etc/ansible/roles/ or /etc/ansible/ and extract.
  3. Navigate to the opsrampagent folder to run playbooks.

Installing agents using Ansible

If a device already has an existing agent, you can either reinstall or installation process skips such devices.

Scenarios for installation: 

  • Scenario 1: You have multiple devices. Some of the devices already have agent installed and you want to skip agent installation. Some needs agent installation.
  • Scenario 2: You have multiple devices. Some of the devices already have agent installed and you want to reinstall agent. Some devices need agent installation.

Before you install an agent with Ansible

Before using either of the scenarios for installation, ensure to add device details.

Add all the details about devices in /etc/ansible/hosts inventory in the following format.

[Category] 
<device IP> ansible_user=<user> ansible_password=<userpassword>

For example:

   [OpsrampAgents]
   10.10.10.10 ansible_user=root ansible_password=password123

Installing the latest agent

Scenario 1

  • You have multiple devices.
  • Some of the resources already have agent installed and you want to skip agent installation.
  • Some resources needs agent installation.

Solution:
You can run a command that helps you install agents only on those devices that do not have agent installed and skips installation those devices that already have agent installed.

Run the following command:

ansible-playbook agent-install-uninstall.yml -e “hostlist=<devicelist>”  -f <number of forks>`

Example

ansible-playbook agent-install-uninstall.yml -e “hostlist=OpsrampAgents” -f 10

Scenario 2:

  • You have multiple devices.
  • Some of the devices already have agent installed and you want to reinstall agent.
  • Some devices need agent installation.

Solution:
Use the command that installs agent on devices that do not have agent installed and also performs re-installation on those devices that have an agent already installed. The existing agent is uninstalled and the latest agent version is installed.

Run the following command:

ansible-playbook agent-install-uninstall.yml -e “hostlist=<hostlist/category>”  -e “reinstall=yes” -f <number of forks>`

For example:

ansible-playbook agent-install-uninstall.yml -e “hostlist=OpsrampAgents”  -e “reinstall=yes” -f 10

Uninstalling agents from target resources

This section describes how to uninstall agents from all target resources.

To uninstall:

  1. Add all the devices details in the inventory file: /etc/ansible/hosts using the following format:
    Syntax:

    [Category]
    <device IP> ansible_user=<user> ansible_password=<userpassword>
    

    Example:

    [OpsrampAgents\] 
    10.10.10.10 ansible\_user=root ansible\_password=password123
    
  2. Run the following command:

     ansible-playbook agent-install-uninstall.yml -e “hostlist=<devicelist>” -e “executionType=uninstall" -f <number of forks>.
    

    For example:

    ansible-playbook agent-install-uninstall.yml -e “hostlist=OpsrampAgents” -e    “executionType=uninstall" -f 10
    
    

Migrating agents

You can migrate agents on target devices from proxy to direct and vice versa.

Before you migrate an agent

Use the following syntax to specify resource details to the inventory file:

 [Category]  
 <device IP> ansible_user=<user> ansible_password=<userpassword>

Example: bash OpsrampAgents 10.10.10.10 ansible_user=root ansible_password=password123

Migrating proxy agents to direct agents

The ansible-playbook agentmigration.yml command is used to migrate proxy agents to direct agents.

  • To migrate Agents from direct to proxy or proxy to proxy, provide valid migrationType and proxyServer fields.
  • If valid migrationType is not provided, OpsRamp playbook simply exits without any action on target devices.
  • This information applies to migrating agents from one proxy to another.

The following Ansible syntax is required for migrating from proxy agents to direct agents:

ansible-playbook agentmigration.yml -e “hostlist=<devicelist>” -e “migrationType=direct”`

Ansible example: 

ansible-playbook agentmigration.yml -e “hostlist=OpsrampAgents” -e “migrationType=direct”

Migrating direct agents to proxy agents

Direct agents can be migrated to proxy agents with or without authentication.

Migrating without authentication

Run the following command to migrate direct Agents to proxy Agents:

ansible-playbook agentmigration.yml -e "hostlist=<devicelist>" -e "migrationType=proxy" -e "proxyServer=<proxyIP/ProxyServer>" -e "proxyPort=<port number>" -e "proxyProto=<http/https>" -f <number of forks>

For example:

ansible-playbook agentmigration.yml -e "hostlist=OpsrampAgents" -e "migrationType=proxy" -e "proxyServer=10.32.32.32" -e "proxyPort=3128" -e "proxyProto=http" -f 10

Migrating with authentication

Run the following command to migrate direct Agents to proxy Agents:

ansible-playbook agentmigration.yml -e "hostlist=<devicelist>" -e "migrationType=proxy" -e "proxyServer=<proxyIP/ProxyServer>" -e "proxyPort=<port number>" -e "proxyProto=http/https>" -e "proxyUser=<user name>" -e 'proxyPassword=<user password>' -f <number of forks>

For example:

ansible-playbook agentmigration.yml -e "hostlist=OpsrampAgents" -e "migrationType=proxy" -e "proxyServer=10.32.32.32" -e "proxyPort=3128" -e "proxyProto=http" -e "proxyUser=user name" -e 'proxyPassword=password' -f 10

Updating agents

You can update agents on all target devices. As a prerequisite, first add the following syntax to the inventory file:

[Category] 
<device IP> ansible_user=<user> ansible_password=<userpassword>

For example:

[OpsrampAgents]
10.10.10.10 ansible_user=root ansible_password=password123

Run the following command to update agents on target devices:

ansible-playbook agentupdate.yml -e "hostlist=<devicelist>" -f <number of forks>

For example:

ansible-playbook agentupdate.yml -e "hostlist=OpsrampAgents" -f 10

Basic commands

Agent commands using Ansible Vault/Encryption process:

If you want to use encrypted inventory files for the different procedures, then include the flag –ask-vault in the respective command. The command provides the credentials.

For information about how to secure inventory file using encryption visit ansible website.

Sample commands with encrypted inventory file

If you want to  use encrypted inventory files for the different procedures, then include the flag --ask-vault in the respective command. The command provides the credentials.

Installation commands

ansible-playbook agent-install-uninstall.yml -e "hostlist=<devicelist>"  -e "reinstall=yes" -f <number of forks> --ask-vault
ansible-playbook agent-install-uninstall.yml -e "hostlist=<devicelist>"  -f <number of forks> --ask-vault

Uninstallation commands

ansible-playbook agent-install-uninstall.yml -e "hostlist=<devicelist>" -e "executionType=uninstall" -f <number of forks> --ask-vault

Migration commands

  • Proxy to Direct
ansible-playbook agentmigration.yml -e "hostlist=<devicelist>" -e "migrationType=direct" --ask-vault
  • Direct to Proxy
ansible-playbook agentmigration.yml -e "hostlist=<devicelist>" -e "migrationType=proxy" -e "proxyServer=<proxyIP/ProxyServer>" -e "proxyPort=<port number>" -e "proxyProto=http/https>" -e "proxyUser=<user name>" -e 'proxyPassword=<user password>' -f <number of forks> --ask-vault
ansible-playbook agentmigration.yml -e "hostlist=<devicelist>" -e "migrationType=proxy" -e "proxyServer=<proxyIP/ProxyServer>" -e "proxyPort=<port number>" -e "proxyProto=<http/https>" -f <number of forks> --ask-vault

Update commands

ansible-playbook agentupdate.yml -e "hostlist=<devicelist>" -f <number of forks> --ask-vault

External references