Nornir

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)

---
inventory:
    plugin: SimpleInventory
    options:
        host_file: "/usr/share/nornir/hosts.yml"
        group_file: "/usr/share/nornir/groups.yml"
        defaults_file: "/usr/share/nornir/defaults.yml"
runner:
    plugin: threaded
    options:
        num_workers: 100

Nornir Hosts File (hosts.yml)

---
ios_host:
    hostname: 172.20.100.203
    platform: 'ios'
    username: {USERNAME}
    password: {PASSWORD}
    groups:
      - ios_group

Nornir Groups File (groups.yml)

---
ios_group:
    platform: 'ios'

Nornir Netmiko Module (send_command.py)

#!/usr/bin/env python3
import sys
from nornir import InitNornir
from nornir_utils.plugins.functions import print_result
from nornir_netmiko.tasks import netmiko_send_command

command = sys.argv[0]

nr = InitNornir(config_file="/usr/share/nornir/config.yml")

results = nr.run(netmiko_send_command, command_string=command)

print_result(results)

Configuring 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.

Editing 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:

1. Open the IAG properties.yml file in a text editor. For example, if using VIM, issue the following command.

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

2. Locate the Nornir section of the configuration file. This is denoted by the # Nornir # header.

3. Configure the following properties:

   • Set the value of nornir_enabled to true.
   • Set the value of nornir_config_file to the path of the Nornir configuration file.
   • Set the value of nornir_module_path to the path of the Nornir module directory.

4. Save your changes to the properties.yml file and exit the text editor.

5. Restart the IAG service with the following command.

   systemctl restart automation-gateway
   

6. Verify that the IAG service has restarted successfully by issuing this command.

     systemctl status automation-gateway
   

Example Nornir Configuration in the IAG Properties File (properties.yml)

##########
# Nornir #
##########

# A boolean flag that enables Nornir support (default=False if absent/misconfigured).
nornir_enabled: true

# Path to the Nornir configuration file.
# A valid file will allows the use of Nornir External inventory.
nornir_config_file: '/usr/share/nornir/config.yml'

# Discovery behavior for Nornir modules. Determines whether or not to
# recursively search the directories found in the 'nornir_module_path' parameter, or
# to only search those directories and no deeper. (default=True if absent/misconfigured)
nornir_module_recursive: true

# Path(s) to the Nornir modules that should be discovered by Automation Gateway.
nornir_module_path:
  # Default location for custom content per the setup script
  - '/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, users 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.

Decorating 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 a user to send commands to inventory devices for execution.

Starting from the IAG dashboard:

1. Select Nornir from the side navigation menu to open Nornir.

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

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

   Figure 1: Module Decoration (send_command.py)

   

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

   Default Module Parameters

   {
   	"properties": {
   		"argument_list": {
   			"type": "array",
   			"description": "Array of arguments to be passed to the nornir module",
   			"items": {
   				"type": "string"
   			}
   		},
   		"env_vars": {
   			"type": "object",
   			"description": "Object containing environment variables to be passed to nornir module",
   			"properties": {
   				"env_list": {
   					"type": "array",
   					"description": "Array of environment variable 'name=value' pairs for nornir module",
   					"items": {
   						"type": "string"
   					}
   				}
   			}
   		}
   	},
   	"script_argument_order": [
   		"argument_list"
   	]
   }
   

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

   Decorated Module Parameters

   {
   	"schema": {
   		"properties": {
   			"command": {
   				"type": "string",
   				"description": "command to run remotely"
   			}
   		},
   		"script_argument_order": [
   			"command"
   		],
   		"title": "send_command.py",
   		"type": "object"
   	}
   }
   

6. 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.

Executing 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. Click the Hosts field to search a list of all hosts defined in the Nornir inventory. Select IOS1.

2. Enter the 'show version' IOS command into the command field.

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

   Figure 2: Executing a Command