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:
- Download OpsRamp Ansible from OpsRamp. To download, on OpsRamp Setup, navigate to Downloads > Agent and click Download for Ansible Agent Deployments.
- Copy downloaded repository to
/etc/ansible/roles/
or/etc/ansible/
and extract. - 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.
Note
- By default OpsRamp playbook tries to deploy Agents on all the available servers in the inventory file without reinstalling the existing Agents.
- If you do not specify the hostlist category, by default playbook tries to install Agents on all the available devices list in the inventory file. This playbook deploys Agents on the target devices.
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:
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
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
andproxyServer
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
Note
- 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.
- Same instructions applies to migrating Agents from one proxy to another.
- By default Ansible recipe considers http as proxyProto if protocol is not configured.
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