Installation

The modules and plugins need to be installed on the Ansible control node, often called the Ansible controller and Ansible needs to be configured so that the modules and plugins can be found by Ansible.

Installing the Ansible modules and plugins is a straight forward process. Copy the Ansible modules and plugins to a directory on the Ansible control node, let us assume /tmp/mandm. Later on these files are copied to the destination directories on the control node.

Requirements

The Ansible integration modules and plugins do not need anything beyond a standard Ansible installation. The minimum Ansible version is 2.7 and up and the required Python version is 2.7+ or 3.5+.

Ansible modules

The Ansible modules can than be placed in a number of directories, depending on your installation and requirements.

/usr/share/ansible/plugins/modules/

System wide installation, modules available to all users

~/.ansible/plugins/modules/

Modules available only to the current user, as the modules are installed in the users home-directory

/etc/ansible/library/

Local installation. As most Ansible installations use the /etc/ansible directory as the Ansible top-directory (as this is the default in an Ansible installation), this is probably the best installation option. When installing the modules in this directory, the Ansible library path needs to be set in the /etc/ansible/ansible.cfg file, pointing to the module directory.

library = /etc/ansible/library

After installing the Ansible modules a check can be made to determine if the modules are installed correctly. Run the command:

ansible-doc -l | grep '^mm_'

This should produce a list with all the Micetro Ansible modules.

Ansible lookup plugins

The set of Ansible Integration modules consists of multiple sets (lookup and inventory) and these should be installed in their own directories.

The lookup plugins can be installed in:

/usr/share/ansible/plugins/lookup

System wide installation, modules available to all users

~/.ansible/plugins/lookup

Plugins available only to the current user, as the plugins are installed in the users home-directory

/etc/ansible/plugins/lookup

Local installation. As most Ansible installations use the /etc/ansible directory as the Ansible top-directory (as this is the default in an Ansible installation) this is probably the best installation option. When installing the lookup plugins in this directory, the Ansible lookup path needs to be set in the /etc/ansible/ansible.cfg file, pointing to the lookup plugin directory.

lookup_plugins = /usr/share/ansible/plugins/lookup:\
                 /etc/ansible/plugins/lookup

To check if the modules are installed correctly and are available to Ansible, issue the command:

ansible-doc -t lookup -l | grep '^mm_'

Which should produce a list with all the Micetro Ansible lookup plugins.

Ansible inventory plugins

The inventory plugins can be installed in:

/usr/share/ansible/plugins/inventory

System wide installation, modules available to all users

~/.ansible/plugins/inventory

Plugins available only to the current user, as the plugins are installed in the users home-directory

/etc/ansible/plugins/inventory

Local installation. As most Ansible installations use the /etc/ansible directory as the Ansible top-directory (as this is the default in an Ansible installation) this is probably the best installation option. When installing the inventory plugins in this directory, the Ansible lookup path needs to be set in the /etc/ansible/ansible.cfg file, pointing to the lookup plugin directory.

inventory_plugins = /usr/share/ansible/plugins/inventory:\
                    /etc/ansible/plugins/inventory

To check if the modules are installed correctly and are available to Ansible, issue the command:

ansible-doc -t inventory -l | grep '^mm_'

Which should produce a list with all the Micetro Ansible inventory plugins.

The mm_inventory plugin also needs some extra configuration, see mm_inventory plugin for more information.

API user

As the Ansible modules and plugins connect to a Micetro installation, a connection between Ansible and Micetro needs to be made.

API user for Micetro

In Micetro a user needs to be defined that has all rights in Micetro (administrator) so it is able to perform all needed tasks. It is also possible to delegate only certain tasks to certain API users. Credential matrix gives an overview which rights a required for every module.

API Provider in Ansible

For the Ansible modules and plugins to function correctly a provider has to be defined. This provider consist of a user, password and connection url (mmurl) and this provider needs to be defined in the Ansible setup, either through Ansible Tower/AWX or in the Ansible directory.

As the modules and plugins can be used by all systems under Ansible control, it is advised to define the API provider for the all group. Create a file all in the /etc/ansible/group_vars directory, or the /etc/ansible/inventory/group_vars directory (if your inventory is a directory instead of a file) which contains something similar to:

1---
2provider:
3  mmurl: http://micetro.example.net
4  user: apiuser
5  password: apipasswd

Note

Encrypt the apipasswd with ansible-vault to prevent plaintext passwords in the Ansible tree.

An example to achieve this is:

printf "apipasswd"             | \
    ansible-vault              \
        encrypt_string         \
        --stdin-name="password"

Which results in:

password: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  3464653838326533616266653.....643434316266666430
  6139656636383537336365313.....336161393439666431
  3539313065656531313838356.....613861623135656634
  6332393063643531390a34366.....323631613034356565
  6138

If an Ansible vault with multiple vault ID’s is needed, please have a look at http://www.tonkersten.com/2019/07/151-ansible-with-multiple-vault-ids/ for more information.

The defined provider can be used in Ansible playbooks like:

Run ansible playbook for another host and delegate to the control node

- name: Claim IP address
  mm_claimip:
    state: present
    ipaddress: 172.16.12.14
    provider: "{{ provider }}"
  delegate_to: localhost

The reason for the delegate_to: localhost option, is that all commands can be performed on the Ansible control node. So, it is possible to protect the Micetro API to only accept commands from the Ansible control node and not from everywhere. This can also be achieved by creating a playbook that has localhost as the hosts-setting and is specific for the interaction with Micetro.

Run ansible playbook on the Ansible Control node

---
- name: host connection example
  hosts: localhost
  connection: local
  become: false

  tasks:
    - name: Claim IP address
      mm_claimip:
        state: present
        ipaddress: 172.16.12.14
        provider: "{{ provider }}"

Ansible configuration example

Beneath is an example Ansible configuration file (ansible.cfg) with the assumption that all Micetro plugins and modules are installed in the /etc/ansible directory. Some lines end with a backslash \, which indicates that the following should be appended, but these are split for code clarity.

 1# ==============================================
 2[defaults]
 3remote_tmp              = $HOME/.ansible/tmp
 4inventory               = inventory
 5pattern                 = *
 6forks                   = 5
 7poll_interval           = 15
 8ask_pass                = False
 9remote_port             = 22
10remote_user             = ansible
11gathering               = implicit
12host_key_checking       = False
13interpreter_python      = auto_silent
14force_valid_group_names = true
15retry_files_enabled     = False
16callback_whitelist      = minimal, dense, oneline
17stdout_callback         = default
18nocows                  = 0
19library                 = /etc/ansible/library
20action_plugins          = /usr/share/ansible_plugins/action_plugins
21callback_plugins        = /etc/ansible/plugins/callback_plugins
22connection_plugins      = /usr/share/ansible_plugins/connection_plugins
23filter_plugins          = /usr/share/ansible_plugins/filter_plugins
24vars_plugins            = /usr/share/ansible_plugins/vars_plugins
25inventory_plugins       = /usr/share/ansible_plugins/inventory_plugins:\
26                          /etc/ansible/plugins/inventory
27lookup_plugins          = /usr/share/ansible_plugins/lookup_plugins:\
28                          /etc/ansible/plugins/lookup
29
30[inventory]
31enable_plugins   = mm_inventory, host_list, auto
32cache            = no
33cache_plugin     = pickle
34cache_prefix     = mm_inv
35cache_timeout    = 60
36cache_connection = /tmp/mm_inventory_cache
37
38[privilege_escalation]
39become          = False
40become_method   = sudo
41become_user     = root
42become_ask_pass = False