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

• 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
ansible-prereqs	installs/updates required ansible packages on controller
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

• Ansible >= 2.9.5

Host Inventory

Create an inventory file with the appropriate groups and variables defined. An example inventory can be found in examples/inventory/hosts.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 supplementary 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 supplementary groups are not managed locally (AD, LDAP etc)
polaris_home	No		home directory for polaris user
polaris_agent_dir	No	/opt/polaris/agent	installation directory 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

Install/Update Ansible prerequisites on controller

If access to the internet is through a proxy, set http_proxy and https_proxy vars in the inventory file. Below are the domains from where prerequisites will be downloaded from. Your proxy must allow access to these domains.

• galaxy.ansible.com
• ansible-galaxy-ng.s3.dualstack.<region>.amazonaws.com
  • where regions are list in https://docs.aws.amazon.com/general/latest/gr/s3.html (opens new window)

To install or update required ansible prerequisites:

ansible-playbook -i /path/to/your/inventory/hosts.yaml playbooks/ansible-prereqs.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 defined by variable known_hosts_file.

ansible-playbook -i /path/to/your/inventory/hosts.yaml playbooks/build-known-hosts.yaml

To use a known_hosts file from the non-standard location ~/.ssh/known_hosts, set environment variable ANSIBLE_SSH_ARGS:

export ANSIBLE_SSH_ARGS="-o UserKnownHostsFile=/path/to/your/known_hosts"

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 supplementary 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
  • supplementary 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/
• push agent systemd drop-ins from {{polaris_assets_path}}/systemd/myrmex-ad.service.d/
• 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, required systemd drop-in units and associated assets under {{polaris_assets_path}}/config/agent.

• An example configuration is provided at {{polaris_assets_path}}/config/agent/myrmex-ad.template.conf. Copy it to {{polaris_assets_path}}/config/agent/myrmex-ad.conf and modify according to your environment.
• An example systemd drop-in unit that sets HTTP[S]_PROXY environment variables for the agent service is provided in examples/assets/systemd/myrmex-ad.service.d/. Copy it to {{polaris_assets_path}}/systemd/myrmex-ad.service.d/ and modify according to your environment if required.

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 (Not required for polaris cloud integrations):

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 following 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