InventoryFun

Function to interact with in memory Nornir Inventory data.

InventoryFun Sample Usage

Sample code to invoke InventoryFun function to create new host:

from nornir_salt.plugins.functions import InventoryFun

host_data = {
    "name": "IOL3",
    "hostname": "192.168.217.99",
    "platform": "ios",
    "groups": ["lab", "bma"],
    "connection_options": {
        "napalm": {
            "port": 2022,
            "extras": {
                "foo": "bar"
            }
        }
    }
}

res = InventoryFun(nr, call="create_host", **host_data)
# or res = InventoryFun(nr, "create_host", **host_data)

Sample code to invoke InventoryFun function to update existing host:

from nornir_salt.plugins.functions import InventoryFun

host_data = {
    "name": "IOL2",
    "hostname": "192.168.217.99",
    "platform": "ios_xe",
    "username": "new_username",
    "password": "new_password",
    "port": 123,
    "groups": ["lab", "bma"],
    "data": {
        "made_by": "humans",
    },
    "connection_options": {
        "napalm": {
            "port": 2022,
            "extras": {
                "foo": "bar1"
            }
        }
    }
}

res = InventoryFun(nr, call="update_host", groups_action="append", **host_data)
# or res = InventoryFun(nr, "update_host", groups_action="append", **host_data)

Sample code to invoke InventoryFun function to delete existing host:

from nornir_salt.plugins.functions import InventoryFun

res = InventoryFun(nr, call="delete_host", name="IOL2")
# or res = InventoryFun(nr, "delete_host", name="IOL2")

Sample code to invoke InventoryFun function to bulk load from list:

from nornir_salt.plugins.functions import InventoryFun

data = [
    {
        "call": "create_host",
        "name": "IOL3",
        "hostname": "192.168.217.99",
        "platform": "ios",
        "groups": ["lab", "bma"],
    },
    {
        "call": "delete_host",
        "name": "IOL2",
    },
    {
        "call": "update_host",
        "name": "IOL1",
        "hostname": "1.2.3.4",
        "platform": "ios_xe",
        "groups": ["bma"],
        "groups_action": "remove"
    },
    {
        "call": "create",
        "name": "IOL4",
        "hostname": "192.168.217.4",
        "platform": "iosxr",
        "groups": ["lab"],
    },
]

res = InventoryFun(nr, call="load", data=data)
# or res = InventoryFun(nr, "load", data=data)

InventoryFun Reference

nornir_salt.plugins.functions.InventoryFun.InventoryFun(nr, call, **kwargs)

Dispatcher function to execute one of call functions.

Parameters

nr – (obj) Nornir object
call – (str) name of function to call
kwargs – (dict) arguments to pass on to call function

Returns

call function results

Supported call function values:

create_host or create - calls _create_host, creates new host or replaces existing host object
read_host or read - calls _read_host, read host inventory content
update_host or update - calls _update_host, non recursively update host attributes
delete_host or delete - calls _delete_host, deletes host object from Nornir Inventory
load - calls _load, to simplify calling multiple functions
read_inventory - calls _read_inventory, read inventory content for groups, default and hosts
read_host_data - calls _read_host_data to return host’s data under provided path keys
list_hosts - calls _list_hosts, return a list of inventory’s host names
list_hosts_platforms - calls _list_hosts_platforms, return a dictionary of hosts’ platforms
update_defaults - calls _update_defaults, non recursively update defaults attributes

Call Functions Reference

nornir_salt.plugins.functions.InventoryFun._create_host(nr, name, groups=None, connection_options=None, **kwargs)

Function to add new host in inventory or replace existing host.

Parameters

nr – (obj) Nornir object
name – (str) host name
groups – (list) list of host’s parent group names
connection_options – (dict) connection options dictionary
kwargs – (dict) host base attributes such as hostname, port, username, password, platform, data

Returns

True on success

If group given in groups list does not exist, no error raised, it simply skipped.

nornir_salt.plugins.functions.InventoryFun._read_host(nr, **kwargs)

Function to return inventory content for host(s) using FFun function to filter hosts.

Parameters

nr – (obj) Nornir object
kwargs – (dict) arguments to use with FFun function to filter hosts

Returns

(dict) host(s) inventory dictionary keyed by host name(s)

nornir_salt.plugins.functions.InventoryFun._read_inventory(nr, **kwargs)

Function to return inventory content using FFun function to filter hosts.

Parameters

nr – (obj) Nornir object
kwargs – (dict) arguments to use with FFun function to filter hosts

Returns

(dict) inventory dictionary with groups, defaults and hosts

nornir_salt.plugins.functions.InventoryFun._read_host_data(nr, keys, default=None, **kwargs)

Function to return hosts data under certain keys.

Parameters

nr – (obj) Nornir object
keys – list of strings each string a a dot seprated path to data
default – default value to return if key path item not present in host’s data

Returns

dictionary keyed by host name with databeing a dictionary keyed by paths

For example if host has this data:

hosts:
  nrp1:
    data:
      config:
        interfaces:
          Lo0:
            description: foobar
         bgp:
           asn: 1234

if keys=["config.interfaces.Lo0", "config.bgp", "ntp.config"] this function will return:

{
    "nrp1": {
        "config.interfaces.Lo0": {"description": "foobar"},
        "config.bgp": {"asn": 1234},
        "ntp.config": None
    }
}

Warning

This function does not support retrievieng individual list items, each item in keys path should refer to a data dictionary key.

nornir_salt.plugins.functions.InventoryFun._update_host(nr, name, groups=None, connection_options=None, data=None, groups_action='append', **kwargs)

Function to update host’s inventory.

Parameters

nr – (obj) Nornir object
name – (str) host name
groups – (list) list of host’s parent group names
groups_action – (str) what to do with groups - append (default), insert (prepend) or remove
connection_options – (dict) connection options dictionary
data – (dict) dictionary with host’s data
kwargs – (dict) host base attributes such as hostname, port, username, password, platform

Returns

True on success

data and connection_options replace existing values for top keys similar to dictionary update method, no recursive merge performed.

If group given in groups list does not exist, no error raised, it simply skipped.

nornir_salt.plugins.functions.InventoryFun._delete_host(nr, name)

Function to delete host from inventory.

Parameters

nr – (obj) Nornir object
name – (str or list) host name or a list of host names to delete

Returns

True on success

nornir_salt.plugins.functions.InventoryFun._load(nr, data)

Accept a list of items, where each item executed sequentially to perform one of the operations to create, update or delete.

Parameters

data – (list) list of dictionary items to work with
nr – (obj) Nornir Object

Each list dictionary item should contain call key holding the name of function to call, rest of the dictionary used as a **kwargs with specidfied call function.

nornir_salt.plugins.functions.InventoryFun._list_hosts(nr, **kwargs)

Function to return a list of host names contained in inventory.

Supports filtering using FFun function.

Parameters

nr – (obj) Nornir object
kwargs – (dict) FFun function arguments to filter hosts

Returns

(list) list of host names

nornir_salt.plugins.functions.InventoryFun._list_hosts_platforms(nr, **kwargs)

Function to return a dictionary keyed by host names containing platforms details.

Supports filtering using FFun function.

Parameters

nr – (obj) Nornir object
kwargs – (dict) FFun function arguments to filter hosts

Returns

(list) list of host names

nornir_salt.plugins.functions.InventoryFun._update_defaults(nr, connection_options: Optional[dict] = None, data: Optional[dict] = None, password: str = Ellipsis, platform: str = Ellipsis, port: int = Ellipsis, username: str = Ellipsis, **kwargs) → bool

Function to update defaults inventory.

Parameters

nr – (obj) Nornir object
connection_options – (dict) dictionary with defaults’s connection options data to update. Should be keyed by connection name with value being a dictionary of connection attributes - hostname, port, username, password, platform and extras dictionary
data – (dict) dictionary with defaults’s data to update
kwargs – (dict) additional key-value pairs to add into defaults data

Returns

True on success

Replaces existing values for top keys similar to dictionary update method, no recursive merge performed.