Nornir integration

Nornir is an automation framework written in Python for use in the development of applications that manage network devices. Nornir has its own inventory system for dealing with host information. It also handles the dispatching of tasks to your devices and provides a common framework to write plugins.

Itential Automation Gateway (IAG) contains a Nornir Module Execution Engine that supports the discovery, decoration, and execution of Nornir modules. IAG also provides support for managing Nornir device inventory files and plugins.

Prerequisites

Before proceeding, ensure that the following prerequisites are met:

• Familiarity with Nornir is recommended. For more information, refer to the Nornir documentation.
• Nornir should be installed and configured on the IAG server that it will be connected to.

Example Nornir components

In the examples presented throughout this guide, Nornir functionality is extended by integrating it with IAG. To do this, IAG interacts with two Nornir components:

• The Nornir inventory (via its configuration file)
• Nornir modules

Nornir is installed and configured on the relevant IAG server. The following files are present:

• Nornir Configuration
• Nornir Hosts
• Nornir Groups
• Nornir Netmiko Module

Nornir configuration file (config.yml)

1
---
2
inventory:
3
    plugin: SimpleInventory
4
    options:
5
        host_file: "/usr/share/nornir/hosts.yml"
6
        group_file: "/usr/share/nornir/groups.yml"
7
        defaults_file: "/usr/share/nornir/defaults.yml"
8
runner:
9
    plugin: threaded
10
    options:
11
        num_workers: 100

Nornir hosts file (hosts.yml)

1
---
2
ios_host:
3
    hostname: 172.20.100.203
4
    platform: 'ios'
5
    username: USERNAME_PLACEHOLDER
6
    password: PASSWORD_PLACEHOLDER
7
    groups:
8
      - ios_group

Nornir groups file (groups.yml)

1
---
2
ios_group:
3
    platform: 'ios'

Nornir Netmiko module (send_command.py)

1
#!/usr/bin/env python3
2
import sys
3
from nornir import InitNornir
4
from nornir_utils.plugins.functions import print_result
5
from nornir_netmiko.tasks import netmiko_send_command
6
7
command = sys.argv[0]
8
9
nr = InitNornir(config_file="/usr/share/nornir/config.yml")
10
11
results = nr.run(netmiko_send_command, command_string=command)
12
13
print_result(results)

Configure IAG to use Nornir

To use Nornir with IAG, several properties must first be configured in the IAG properties.yml file.

The IAG service must be restarted for changes to the properties.yml file to take effect.

Edit the IAG configuration file

In the previous example, you confirmed that the required Nornir components are present on the IAG server. Now, you can configure IAG to use these components:

$
vim /opt/automation-gateway/conf/properties.yml

$
systemctl restart automation-gateway

$
systemctl status automation-gateway

Example Nornir configuration in the IAG properties file (properties.yml)

1
##########
2
# Nornir #
3
##########
4
5
# A boolean flag that enables Nornir support (default=False if absent/misconfigured).
6
nornir_enabled: true
7
8
# Path to the Nornir configuration file.
9
# A valid file will allows the use of Nornir External inventory.
10
nornir_config_file: '/usr/share/nornir/config.yml'
11
12
# Discovery behavior for Nornir modules. Determines whether or not to
13
# recursively search the directories found in the 'nornir_module_path' parameter, or
14
# to only search those directories and no deeper. (default=True if absent/misconfigured)
15
nornir_module_recursive: true
16
17
# Path(s) to the Nornir modules that should be discovered by Automation Gateway.
18
nornir_module_path:
19
  # Default location for custom content per the setup script
20
  - '/usr/share/nornir/modules'

Module decoration

After IAG has been configured to use Nornir, it will automatically discover any modules present in the designated directory. Discovered modules can be decorated in IAG.

The decoration of Nornir modules within IAG is similar to that of Ansible playbooks. However, instead of decorating the variables within a playbook, you decorate the command line arguments and environment variables used to execute a Nornir module. The decorated parameters are then passed as arguments to the APIs that execute the module. A permanent copy of each module’s decoration is stored in a local database that is maintained by IAG.

The same features and functionality provided by IAG for decorating proprietary scripts are available for decorating Nornir modules. See the Script execution engine section of the IAG guide for complete instructions on module decoration.

Decorate the discovered Nornir module

Now that you have integrated Nornir with IAG, you can use IAG to decorate Nornir modules. In this example, you will decorate the send_command.py module detailed earlier. This module allows you to send commands to inventory devices for execution.

Starting from the IAG dashboard:

1

Open Nornir

Select Nornir from the side navigation menu to open Nornir.

2

Open the Modules menu

Select Modules from the side navigation menu. An accordion menu that lists all discovered Nornir modules expands.

3

Select the module

Select send_command.py from the accordion menu to open the module for decoration.

4

Open the parameter editor

On the Parameters tab, click the Edit (pencil) icon. A text editor opens that displays a JSON representation of the available module parameters.

1
{
2
  "properties": {
3
    "argument_list": {
4
      "type": "array",
5
      "description": "Array of arguments to be passed to the nornir module",
6
      "items": {
7
        "type": "string"
8
      }
9
    },
10
    "env_vars": {
11
      "type": "object",
12
      "description": "Object containing environment variables to be passed to nornir module",
13
      "properties": {
14
        "env_list": {
15
          "type": "array",
16
          "description": "Array of environment variable 'name=value' pairs for nornir module",
17
          "items": {
18
            "type": "string"
19
          }
20
        }
21
      }
22
    }
23
  },
24
  "script_argument_order": [
25
    "argument_list"
26
  ]
27
}

5

Edit the module parameters

Edit the JSON as follows. The module will now have a single parameter, “command”.

1
{
2
  "schema": {
3
    "properties": {
4
      "command": {
5
        "type": "string",
6
        "description": "command to run remotely"
7
      }
8
    },
9
    "script_argument_order": [
10
      "command"
11
    ],
12
    "title": "send_command.py",
13
    "type": "object"
14
  }
15
}

6

Save your changes

Click Save to retain your changes.

Execution

Nornir modules are executed by issuing a POST <hostname:port>/nornir/<module_name>/execute call to IAG. Executing a module can be done using the IAG UI or by a separate application. Modules are executed on the node on which the IAG server is running.

The desired arguments and environment variables that match the Nornir module’s schema are included as execution parameters. The execution parameters are passed to the module as if they were being entered by the user on the command line. Part of the module’s execution logic is to parse the contents of the command line accordingly.

By default, modules are executed from the home directory of the user that owns the IAG server process. To change the default execution directory, add the working_dir key to the module’s schema outside the properties object. The value of working_dir can be an absolute or a relative directory path.

Hosts and groups support

The Nornir module execution API contains support for the hosts and groups parameters. The hosts parameter is an array of Nornir device names that are members of the IAG inventory. Similarly, the groups parameter is an array of Nornir group names that are present in the IAG inventory.

When the hosts or groups parameters are present and their contents are validated, the Nornir Module Execution Engine will pass the contents to the Nornir module as a comma-separated list using the command line arguments --hosts and --groups. The Nornir module itself is responsible for parsing the contents of the --hosts and --groups arguments.

Results

The following fields are contained within the results object returned after execution of the module.

Execute the discovered Nornir module

After decorating the send_command.py module, you are ready to execute it against the Cisco IOS device present in the Nornir inventory, ios_host.

Starting from the Execute tab of the send_command.py module:

1

Select the host

Click the Hosts field to search a list of all hosts defined in the Nornir inventory. Select IOS1.

2

Enter the command

Enter the ‘show version’ IOS command into the command field.

3

Execute the command

Click the Play button to execute the command against IOS1. The results of the command will be returned in JSON format.