Plugins

Nornir is a pluggable system and only very basic ones are included with nornir 3, for a list of third party plugins visit nornir.tech

Registering plugins

Starting with nornir3 some plugins need to be registered in order to be used. In particular:

  • inventory plugins
  • transform functions
  • connection plugins
  • runners

To do so you can use entry points or programmatically.

Using entrypoints in your setup.py:

setup(
    # ...
    entry_points={
      "PATH": "NAME = path.to:Plugin",
    }
)

In your pyproject.toml if using poetry:

[tool.poetry.plugins."PATH"]
"NAME" = "path.to:Plugin"

Where PATH is:

  • nornir.plugins.inventory - for inventory plugins
  • nornir.plugins.transform_function - for transform functions
  • nornir.plugins.runners - for runners
  • nornir.plugins.connections - for connection plugins

Where NAME is the way you want to refer to it later on and path.to:Plugin the import path. For instance:

[tool.poetry.plugins."nornir.plugins.inventory"]
"inventory-name" = "path.to:InventoryPlugin"

To do it programmatically import the correct plugin register and use the register method. For instance:

from nornir.core.plugins.inventory import InventoryPluginRegister

from path.to import InventoryPlugin


InventoryPluginRegister.register("inventory-name", InventoryPlugin)

Connections

A connection plugin is a nornir plugin that allows nornir to manage connections with devices

Inventory

An inventory plugin is a nornir plugin that allows nornir to create an Inventory object from an external source

Included

class nornir.plugins.inventory.__init__.SimpleInventory(host_file: str = 'hosts.yaml', group_file: str = 'groups.yaml', defaults_file: str = 'defaults.yaml', encoding: str = 'utf-8')
load() → nornir.core.inventory.Inventory

Transform functions

A transform function is a plugin that manipulates the inventory independently from the inventory plugin used. Useful to extend data using the environment, a secret store or similar.

Runners

A runner is a plugin that dictates how to execute the tasks over the hosts

Included

class nornir.plugins.runners.__init__.SerialRunner

SerialRunner runs the task over each host one after the other without any parellelization

run(task: nornir.core.task.Task, hosts: List[nornir.core.inventory.Host]) → nornir.core.task.AggregatedResult
class nornir.plugins.runners.__init__.ThreadedRunner(num_workers: int = 20)

ThreadedRunner runs the task over each host using threads

Parameters:num_workers – number of threads to use
run(task: nornir.core.task.Task, hosts: List[nornir.core.inventory.Host]) → nornir.core.task.AggregatedResult

For more details about ThreadedRunner read the Execution Model.

Processors

A processor is a plugin that taps into certain events and allows the user to execute arbitrary code on those events.