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 Gateway contains a Nornir Module Execution Engine that supports the discovery, decoration, and execution of Nornir modules. Gateway 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 Gateway 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 Gateway. To do this, Gateway interacts with two Nornir components:

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

Nornir is installed and configured on the relevant Gateway 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 Gateway to use Nornir

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

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

Edit the Gateway configuration file

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

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

$
systemctl restart automation-gateway

$
systemctl status automation-gateway

Example Nornir configuration in the Gateway 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 Gateway.
18
nornir_module_path:
19
  # Default location for custom content per the setup script
20
  - '/usr/share/nornir/modules'

Module decoration

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

The decoration of Nornir modules within Gateway 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 Gateway.

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

Decorate the discovered Nornir module

Now that you have integrated Nornir with Gateway, you can use Gateway 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 Gateway 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 Gateway. Executing a module can be done using the Gateway UI or by a separate application. Modules are executed on the node on which the Gateway 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 Gateway 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 Gateway inventory. Similarly, the groups parameter is an array of Nornir group names that are present in the Gateway 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.