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:

  1. setup(
  2. # ...
  3. entry_points={
  4. "PATH": "NAME = path.to:Plugin",
  5. }
  6. )

In your pyproject.toml if using poetry:

  1. [tool.poetry.plugins."PATH"]
  2. "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:

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

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

  1. from nornir.core.plugins.inventory import InventoryPluginRegister
  2. from path.to import InventoryPlugin
  3. 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’)

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

class nornir.plugins.runners.__init__.ThreadedRunner(num_workers: int = 20)

ThreadedRunner runs the task over each host using threads

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.