Upgrading to nornir 2.x from 1.x

Changes in the inventory

Connection parameters

When specifying connection parameters, in nornir 1.x those parameters where specified with attributes like nornir_username, nornir_password, etc. All of those have been removed and now the only supported parameters are:

  • hostname

  • username

  • password

  • port (which replaces both nornir_ssh_port and nornir_network_api_port)

  • platform (which replaces both os and network_operating_system)

You can check the following how to for more details on how to use these parameters.

Custom inventory data

Any custom host or group data keys, other than core supported keys, must also be moved under a data subkey:

  1. ---
  2. host host1.cmh:
  3.   hostname: 127.0.0.1
  4.   username: vagrant
  5.   password: vagrant
  6.   platform: linux
  7.   groups:
  8.     - cmh
  9.   site: cmh  # example custom data

to:

  1. ---
  2. host1.cmh:
  3.   hostname: 127.0.0.1
  4.   username: vagrant
  5.   password: vagrant
  6.   platform: linux
  7.   groups:
  8.     - cmh
  9.   data:
  10.     site: cmh

See the inventory tutorial for more information on how to structure inventory data.

Changed to path importing InitNornir

In order to import InitNornir correctly you have to change the old path:

  1. from nornir.core import InitNornir

to:

  1. from nornir import InitNornir

Changes to the configuration

The format of the configuration has slightly changed. Some of the options that used to be under the root object, for instance num_workers, jinja_filters and raise_on_error are now under core and jinja2 sections. For details, go to the configuration section

Beware, that where top-level options have now been moved into new sections, if you were previously passing these options to InitNornir in code and other options via configuration file, you may notice a change in behaviour.

Changes to templates

In Nornir 1.x, all host data was made directly available as template variables. To avoid the potential for conflicts, nornir 2.x, host data is namespaced under the host variable.

Change from:

  1. My hostname is: {{ hostname }}

to:

  1. My hostname is: {{ host.hostname }}

Changes to transform functions

In nornir 2.x, a transform function passed in the inventory configuration to InitNonir must be serialisable (so it may not be a lambda). If you need to pass parameters to the transform function, use the new transform_function_options parameter.

Changes to Inventory plugins

The inventory plugin system has changed quite significantly and the base class is now nornir.core.deserializer.inventory.Inventory. Inventory plugins are also now based on Pydantic (https://github.com/samuelcolvin/pydantic) and so instances of the plugin class do not allow arbitrary class members. You may need to alter the way your inventory plugin works, particularly if you need to maintain state during initialisation.

To see some simple examples, look at the SimpleInventory and NetboxInventory plugins which ship with Nornir. The AnsibleInventory plugin is a complete example of a more complex system.