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 running

  cat << '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 if polaris_uses_local_groups is true
• create polaris user if polaris_uses_local_account is true
  • the user will be added to supplimentary groups specified by polaris_groups
• update polaris user if polaris_uses_local_account or polaris_uses_local_groups is true
  • group change as specified by polaris_group
  • supplimentary groups specified by polaris_groups will be added to polaris user. Existing group memberships are not modified
• 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 hosts
• polaris_ts_hosts for polaris time series server hosts
• polaris_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