Ansible Automation
- Last Updated 5/24/2023, 3:10:50 PM UTC
- About 6 min read
As your Polaris agent fleet grows it become time consuming and error prone to individually manage each agent. This guide will show you how to automate all agent management tasks through ansible
playbooks.
Before you begin
Because of Ansible bug #40827 (opens new window) make sure you unset local env variables
http_proxy
,https_proxy
,no_proxy
before running any of the polaris playbooks.Your local account
ssh-agent
must be runningcat << 'EOF' >> ~/.bash_profile export SSH_AUTH_SOCK=~/.ssh/ssh-agent.$HOSTNAME.sock ssh-add -l 2>/dev/null >/dev/null if [ $? -ge 2 ]; then echo "starting ssh-agent" rm -f $SSH_AUTH_SOCK ssh-agent -a "$SSH_AUTH_SOCK" >/dev/null fi EOF . ~/.bash_profile
SSH private key must be in ssh-agent keyring before running playbooks
# check if in keyring ssh-add -l # add if not in keyring ssh-add -t 30m ~/.ssh/[id_your_key]
# Ansible user
Create user ansible
or equivalent on your ansible controller node that will be responsible for running the automation playbooks
Privilege Escalation
Some playbooks require privilege escalation (sudo
) on the target hosts. Ansible requires that privilege escalation is unrestricted and passwordless, i.e. allowing only specific commands in sudoers
will not work. This means that your user id on target hosts must be a sudoer
with effective access as below:
your_id ALL=(ALL) NOPASSWD: ALL
# Playbooks
Get the playbooks from git repo https://github.com/arisant/polaris-ansible.git
.
git clone https://github.com/arisant/polaris-ansible.git
# Plays
Play | Description |
---|---|
build-known-hosts | uses ssh-keyscan to update a known_hosts file from the hosts in your inventory |
pull-releases | downloads or updates the latest polaris software into polaris_assets_path |
agent-deploy | installs or updates myrmex agent, configurations, agent user group memberships |
agent-reinstall | reinstalls the agent service |
agent-status | collects the current agent service status from all hosts |
agent-start | starts agents |
agent-restart | bounces started agents |
agent-stop | stops agents |
agent-version | collects agent versions from all hosts |
agent-join-controller | joins agents to polaris controller for non-cloud environments |
systemd-config-ad | configures a polaris myrmex-ad systemd service via drop-in configurations |
systemd-config-sd | configures a polaris myrmex-sd systemd service via drop-in configurations |
systemd-config-ts | configures a polaris myrmex-ts systemd service via drop-in configurations |
# Requirements
On the controller node:
- Ansible >= 2.9.5
# Host Inventory
Create an inventory file with the appropriate groups and variables defined. An example inventory can be found in inventory/hosts.example.yaml
.
# Variables
Variable | Required | Default | Description |
---|---|---|---|
polaris_hosts | No | polaris_mon | ansible inventory host group name target for agent playbooks |
polaris_sd_hosts | No | polaris_sd | ansible inventory host group name target for server playbooks |
polaris_ts_hosts | No | polaris_ts | ansible inventory host group name target for timeseries server playbooks |
known_hosts_file | Yes | known_hosts file maintained by build-known-hosts | |
polaris_assets_path | Yes | directory on the controller node where polaris assets are staged | |
polaris_user | No | polaris | user name for the polaris agent or server |
polaris_group | No | polaris | primary group for the polaris agent or server |
polaris_groups | No | comma separated supplimentary groups for polaris agent user | |
polaris_uid | No | user id for the polaris agent or server | |
polaris_gid | No | primary gid for the polaris agent or server | |
polaris_uses_local_account | No | true | set to false if the polaris account is not managed locally (AD, LDAP etc) |
polaris_uses_local_groups | No | true | set to false if the polaris primary groups and supplimentary groups are not managed locally (AD, LDAP etc) |
polaris_home | No | home directory for polaris user | |
polaris_agent_dir | No | /opt/polaris/agent | installation diractory for polaris agent. Should not be on an NFS mount |
http_proxy | No | http proxy settings | |
https_proxy | No | https proxy settings |
# Inventory Groups
The default group that the plays apply to is polaris_mon
. If you need to use a different group or target a specific subset of polaris hosts set the variable polaris_hosts
to an appropriate value.
For example to update the agent only on UAT hosts:
ansible-playbook -e 'polaris_hosts=polaris_mon_uat' -i /path/to/your/inventory/hosts.yaml playbooks/agent-deploy.yaml
# Build your known_hosts database
If you trust the current state of your target hosts, use build-known-hosts
to create or update the known hosts database.
The known_hosts
file to write to is defiend by variable known_hosts_file
.
ansible-playbook -i /path/to/your/inventory/hosts.yaml playbooks/build-known-hosts.yaml
# Download software components
To download the latest releases for polaris software, create directory polaris_assets_path
and:
ansible-playbook -i /path/to/your/inventory/hosts.yaml playbooks/pull-releases.yaml
# Deploy agents
This playbook will:
- create
polaris
primary group ifpolaris_uses_local_groups
is true - create
polaris
user ifpolaris_uses_local_account
is true- the user will be added to supplimentary groups specified by
polaris_groups
- the user will be added to supplimentary groups specified by
- update
polaris
user ifpolaris_uses_local_account
orpolaris_uses_local_groups
is true- group change as specified by
polaris_group
- supplimentary groups specified by
polaris_groups
will be added topolaris
user. Existing group memberships are not modified
- group change as specified by
- install or update an agent and associated service
- push agent configurations from
{{polaris_assets_path}}/config/agent/
- start the agent service on agent creation
- bounce running agent services on software updates, configuration changes or user/group-membership modifications
Before you run this playbook make sure that you create the agent configuration and associated assets under {{polaris_assets_path}}/config/agent
. An example configuration is provided at {{polaris_assets_path}}/config/agent/myrmex-ad.template.conf
.
ansible-playbook -i /path/to/your/inventory/hosts.yaml playbooks/agent-deploy.yaml
# Join agents to polaris control
To join polaris agents to the controller (This play will be skipped if agents are connected to polaris cloud):
ansible-playbook -i /path/to/your/inventory/hosts.yaml playbooks/agent-join-controller.yaml
# Reinstall agent service
Run this playbook when there's an myrmex-ad
upgrade that requires changes to the unix service.
ansible-playbook -i /path/to/your/inventory/hosts.yaml playbooks/agent-reinstall.yaml
# Get agent version
To collect the agent version from all polaris hosts:
ansible-playbook -i /path/to/your/inventory/hosts.yaml playbooks/agent-version.yaml
# Introspect and control the state of agent services
View agent service status:
ansible-playbook -i /path/to/your/inventory/hosts.yaml playbooks/agent-status.yaml
Start agent service:
ansible-playbook -i /path/to/your/inventory/hosts.yaml playbooks/agent-start.yaml
Stop agent service:
ansible-playbook -i /path/to/your/inventory/hosts.yaml playbooks/agent-stop.yaml
Bounce agent service (only started agents are affected):
ansible-playbook -i /path/to/your/inventory/hosts.yaml playbooks/agent-restart.yaml
# Configure systemd services with drop-in configurations
myrmex-sd
, myrmex-ad
and myrmex-ts
systemd services can be configured with drop-in configurations.
The drop-in configurations for each service are defined in the followoing directories:
{{polaris_assets_path}}/systemd/myrmex-sd.service.d/
{{polaris_assets_path}}/systemd/myrmex-ad.service.d/
{{polaris_assets_path}}/systemd/myrmex-ts.service.d/
The hosts on which the configuration will be applied are defined by the following inventory groups:
polaris_sd_hosts
for polaris server hostspolaris_ts_hosts
for polaris time series server hostspolaris_hosts
for polaris agents
To update the drop-in configurations for myrmex-sd
ansible-playbook -i /path/to/your/inventory/hosts.yaml playbooks/systemd-config-sd.yaml
To update the drop-in configurations for myrmex-ad
ansible-playbook -i /path/to/your/inventory/hosts.yaml playbooks/systemd-config-ad.yaml
To update the drop-in configurations for myrmex-ts
ansible-playbook -i /path/to/your/inventory/hosts.yaml playbooks/systemd-config-ts.yaml