Inventory

The Inventory is arguably the most important piece of nornir. Let’s see how it works. To begin with the inventory is comprised of hosts, groups and defaults.

In this tutorial we are using the SimpleInventory plugin. This inventory plugin stores all the relevant data in three files. Let’s start by checking them:

  1. [2]:
  1. # hosts file
  2. %highlight_file inventory/hosts.yaml
  1. [2]:
  1.   1---
  2.   2host1.cmh:
  3.   3    hostname: 127.0.0.1
  4.   4    port: 2201
  5.   5    username: vagrant
  6.   6    password: vagrant
  7.   7    platform: linux
  8.   8    groups:
  9.   9        - cmh
  10.  10    data:
  11.  11        site: cmh
  12.  12        role: host
  13.  13        type: host
  14.  14        nested_data:
  15.  15            a_dict:
  16.  16                a: 1
  17.  17                b: 2
  18.  18            a_list: [1, 2]
  19.  19            a_string: "asdasd"
  20.  20
  21.  21host2.cmh:
  22.  22    hostname: 127.0.0.1
  23.  23    port: 2202
  24.  24    username: vagrant
  25.  25    password: vagrant
  26.  26    platform: linux
  27.  27    groups:
  28.  28        - cmh
  29.  29    data:
  30.  30        site: cmh
  31.  31        role: host
  32.  32        type: host
  33.  33        nested_data:
  34.  34            a_dict:
  35.  35                b: 2
  36.  36                c: 3
  37.  37            a_list: [1, 2]
  38.  38            a_string: "qwe"
  39.  39
  40.  40spine00.cmh:
  41.  41    hostname: 127.0.0.1
  42.  42    username: vagrant
  43.  43    password: vagrant
  44.  44    port: 12444
  45.  45    platform: eos
  46.  46    groups:
  47.  47        - cmh
  48.  48    data:
  49.  49        site: cmh
  50.  50        role: spine
  51.  51        type: network_device
  52.  52
  53.  53spine01.cmh:
  54.  54    hostname: 127.0.0.1
  55.  55    username: vagrant
  56.  56    password: ""
  57.  57    platform: junos
  58.  58    port: 12204
  59.  59    groups:
  60.  60        - cmh
  61.  61    data:
  62.  62        site: cmh
  63.  63        role: spine
  64.  64        type: network_device
  65.  65
  66.  66leaf00.cmh:
  67.  67    hostname: 127.0.0.1
  68.  68    username: vagrant
  69.  69    password: vagrant
  70.  70    port: 12443
  71.  71    platform: eos
  72.  72    groups:
  73.  73        - cmh
  74.  74    data:
  75.  75        site: cmh
  76.  76        role: leaf
  77.  77        type: network_device
  78.  78        asn: 65100
  79.  79
  80.  80leaf01.cmh:
  81.  81    hostname: 127.0.0.1
  82.  82    username: vagrant
  83.  83    password: ""
  84.  84    port: 12203
  85.  85    platform: junos
  86.  86    groups:
  87.  87        - cmh
  88.  88    data:
  89.  89        site: cmh
  90.  90        role: leaf
  91.  91        type: network_device
  92.  92        asn: 65101
  93.  93
  94.  94host1.bma:
  95.  95    groups:
  96.  96        - bma
  97.  97    platform: linux
  98.  98    data:
  99.  99        site: bma
  100. 100        role: host
  101. 101        type: host
  102. 102
  103. 103host2.bma:
  104. 104    groups:
  105. 105        - bma
  106. 106    platform: linux
  107. 107    data:
  108. 108        site: bma
  109. 109        role: host
  110. 110        type: host
  111. 111
  112. 112spine00.bma:
  113. 113    hostname: 127.0.0.1
  114. 114    username: vagrant
  115. 115    password: vagrant
  116. 116    port: 12444
  117. 117    platform: eos
  118. 118    groups:
  119. 119        - bma
  120. 120    data:
  121. 121        site: bma
  122. 122        role: spine
  123. 123        type: network_device
  124. 124
  125. 125spine01.bma:
  126. 126    hostname: 127.0.0.1
  127. 127    username: vagrant
  128. 128    password: ""
  129. 129    port: 12204
  130. 130    platform: junos
  131. 131    groups:
  132. 132        - bma
  133. 133    data:
  134. 134        site: bma
  135. 135        role: spine
  136. 136        type: network_device
  137. 137
  138. 138leaf00.bma:
  139. 139    hostname: 127.0.0.1
  140. 140    username: vagrant
  141. 141    password: vagrant
  142. 142    port: 12443
  143. 143    platform: eos
  144. 144    groups:
  145. 145        - bma
  146. 146    data:
  147. 147        site: bma
  148. 148        role: leaf
  149. 149        type: network_device
  150. 150
  151. 151leaf01.bma:
  152. 152    hostname: 127.0.0.1
  153. 153    username: vagrant
  154. 154    password: wrong_password
  155. 155    port: 12203
  156. 156    platform: junos
  157. 157    groups:
  158. 158        - bma
  159. 159    data:
  160. 160        site: bma
  161. 161        role: leaf
  162. 162        type: network_device

The hosts file is basically a map where the outermost key is the name of the host and then a Host object. You can see the schema of the object by executing:

  1. [3]:
  1. from nornir.core.inventory import Host
  2. import json
  3. print(json.dumps(Host.schema(), indent=4))
  1. {
  2.     "name": "str",
  3.     "connection_options": {
  4.         "$connection_type": {
  5.             "extras": {
  6.                 "$key": "$value"
  7.             },
  8.             "hostname": "str",
  9.             "port": "int",
  10.             "username": "str",
  11.             "password": "str",
  12.             "platform": "str"
  13.         }
  14.     },
  15.     "groups": [
  16.         "$group_name"
  17.     ],
  18.     "data": {
  19.         "$key": "$value"
  20.     },
  21.     "hostname": "str",
  22.     "port": "int",
  23.     "username": "str",
  24.     "password": "str",
  25.     "platform": "str"
  26. }

The groups_file follows the same rules as the hosts_file.

  1. [4]:
  1. # groups file
  2. %highlight_file inventory/groups.yaml
  1. [4]:
  1.  1---
  2.  2global:
  3.  3    data:
  4.  4        domain: global.local
  5.  5        asn: 1
  6.  6
  7.  7eu:
  8.  8    data:
  9.  9        asn: 65100
  10. 10
  11. 11bma:
  12. 12    groups:
  13. 13        - eu
  14. 14        - global
  15. 15
  16. 16cmh:
  17. 17    data:
  18. 18        asn: 65000
  19. 19        vlans:
  20. 20          100: frontend
  21. 21          200: backend

Finally, the defaults file has the same schema as the Host we described before but without outer keys to denote individual elements. We will see how the data in the groups and defaults file is used later on in this tutorial.

  1. [5]:
  1. # defaults file
  2. %highlight_file inventory/defaults.yaml
  1. [5]:
  1. 1---
  2. 2data:
  3. 3    domain: acme.local

Accessing the inventory

You can access the inventory with the inventory attribute:

  1. [6]:
  1. from nornir import InitNornir
  2. nr = InitNornir(config_file="config.yaml")
  4. print(nr.inventory.hosts)
  1. {'host1.cmh': Host: host1.cmh, 'host2.cmh': Host: host2.cmh, 'spine00.cmh': Host: spine00.cmh, 'spine01.cmh': Host: spine01.cmh, 'leaf00.cmh': Host: leaf00.cmh, 'leaf01.cmh': Host: leaf01.cmh, 'host1.bma': Host: host1.bma, 'host2.bma': Host: host2.bma, 'spine00.bma': Host: spine00.bma, 'spine01.bma': Host: spine01.bma, 'leaf00.bma': Host: leaf00.bma, 'leaf01.bma': Host: leaf01.bma}

The inventory has two dict-like attributes hosts and groups that you can use to access the hosts and groups respectively:

  1. [7]:
  1. nr.inventory.hosts
  1. [7]:
  1. {'host1.cmh': Host: host1.cmh,
  2.  'host2.cmh': Host: host2.cmh,
  3.  'spine00.cmh': Host: spine00.cmh,
  4.  'spine01.cmh': Host: spine01.cmh,
  5.  'leaf00.cmh': Host: leaf00.cmh,
  6.  'leaf01.cmh': Host: leaf01.cmh,
  7.  'host1.bma': Host: host1.bma,
  8.  'host2.bma': Host: host2.bma,
  9.  'spine00.bma': Host: spine00.bma,
  10.  'spine01.bma': Host: spine01.bma,
  11.  'leaf00.bma': Host: leaf00.bma,
  12.  'leaf01.bma': Host: leaf01.bma}
  1. [8]:
  1. nr.inventory.groups
  1. [8]:
  1. {'global': Group: global,
  2.  'eu': Group: eu,
  3.  'bma': Group: bma,
  4.  'cmh': Group: cmh}
  1. [9]:
  1. nr.inventory.hosts["leaf01.bma"]
  1. [9]:
  1. Host: leaf01.bma

Hosts and groups are also dict-like objects:

  1. [10]:
  1. host = nr.inventory.hosts["leaf01.bma"]
  2. host.keys()
  1. [10]:
  1. dict_keys(['site', 'role', 'type', 'asn', 'domain'])
  1. [11]:
  1. host["site"]
  1. [11]:
  1. 'bma'

Inheritance model

Let’s see how the inheritance models works by example. Let’s start by looking again at the groups file:

  1. [12]:
  1. # groups file
  2. %highlight_file inventory/groups.yaml
  1. [12]:
  1.  1---
  2.  2global:
  3.  3    data:
  4.  4        domain: global.local
  5.  5        asn: 1
  6.  6
  7.  7eu:
  8.  8    data:
  9.  9        asn: 65100
  10. 10
  11. 11bma:
  12. 12    groups:
  13. 13        - eu
  14. 14        - global
  15. 15
  16. 16cmh:
  17. 17    data:
  18. 18        asn: 65000
  19. 19        vlans:
  20. 20          100: frontend
  21. 21          200: backend

The host leaf01.bma belongs to the group bma which in turn belongs to the groups eu and global. The host spine00.cmh belongs to the group cmh which doesn’t belong to any other group.

Data resolution works by iterating recursively over all the parent groups and trying to see if that parent group (or any of it’s parents) contains the data. For instance:

  1. [13]:
  1. leaf01_bma = nr.inventory.hosts["leaf01.bma"]
  2. leaf01_bma["domain"]  # comes from the group `global`
  1. [13]:
  1. 'global.local'
  1. [14]:
  1. leaf01_bma["asn"]  # comes from group `eu`
  1. [14]:
  1. 65100

Values in defaults will be returned if neither the host nor the parents have a specific value for it.

  1. [15]:
  1. leaf01_cmh = nr.inventory.hosts["leaf01.cmh"]
  2. leaf01_cmh["domain"]  # comes from defaults
  1. [15]:
  1. 'acme.local'

If nornir can’t resolve the data you should get a KeyError as usual:

  1. [16]:
  1. try:
  2.     leaf01_cmh["non_existent"]
  3. except KeyError as e:
  4.     print(f"Couldn't find key: {e}")
  1. Couldn't find key: 'non_existent'

You can also try to access data without recursive resolution by using the data attribute. For example, if we try to access leaf01_cmh.data["domain"] we should get an error as the host itself doesn’t have that data:

  1. [17]:
  1. try:
  2.     leaf01_cmh.data["domain"]
  3. except KeyError as e:
  4.     print(f"Couldn't find key: {e}")
  1. Couldn't find key: 'domain'

Filtering the inventory

So far we have seen that nr.inventory.hosts and nr.inventory.groups are dict-like objects that we can use to iterate over all the hosts and groups or to access any particular one directly. Now we are going to see how we can do some fancy filtering that will enable us to operate on groups of hosts based on their properties.

The simpler way of filtering hosts is by <key, value> pairs. For instance:

  1. [18]:
  1. nr.filter(site="cmh").inventory.hosts.keys()
  1. [18]:
  1. dict_keys(['host1.cmh', 'host2.cmh', 'spine00.cmh', 'spine01.cmh', 'leaf00.cmh', 'leaf01.cmh'])

You can also filter using multiple <key, value> pairs:

  1. [19]:
  1. nr.filter(site="cmh", role="spine").inventory.hosts.keys()
  1. [19]:
  1. dict_keys(['spine00.cmh', 'spine01.cmh'])

Filter is cumulative:

  1. [20]:
  1. nr.filter(site="cmh").filter(role="spine").inventory.hosts.keys()
  1. [20]:
  1. dict_keys(['spine00.cmh', 'spine01.cmh'])

Or:

  1. [21]:
  1. cmh = nr.filter(site="cmh")
  2. cmh.filter(role="spine").inventory.hosts.keys()
  1. [21]:
  1. dict_keys(['spine00.cmh', 'spine01.cmh'])
  1. [22]:
  1. cmh.filter(role="leaf").inventory.hosts.keys()
  1. [22]:
  1. dict_keys(['leaf00.cmh', 'leaf01.cmh'])

You can also grab the children of a group:

  1. [23]:
  1. nr.inventory.children_of_group("eu")
  1. [23]:
  1. {Host: host1.bma,
  2.  Host: host2.bma,
  3.  Host: leaf00.bma,
  4.  Host: leaf01.bma,
  5.  Host: spine00.bma,
  6.  Host: spine01.bma}

Advanced filtering

Sometimes you need more fancy filtering. For those cases you have two options:

  1. Use a filter function.

  2. Use a filter object.

Filter functions

The filter_func parameter let’s you run your own code to filter the hosts. The function signature is as simple as my_func(host) where host is an object of type Host and it has to return either True or False to indicate if you want to host or not.

  1. [24]:
  1. def has_long_name(host):
  2.     return len(host.name) == 11
  4. nr.filter(filter_func=has_long_name).inventory.hosts.keys()
  1. [24]:
  1. dict_keys(['spine00.cmh', 'spine01.cmh', 'spine00.bma', 'spine01.bma'])
  1. [25]:
  1. # Or a lambda function
  2. nr.filter(filter_func=lambda h: len(h.name) == 9).inventory.hosts.keys()
  1. [25]:
  1. dict_keys(['host1.cmh', 'host2.cmh', 'host1.bma', 'host2.bma'])

Filter Object

You can also use a filter objects to incrementally create a complex query objects. Let’s see how it works by example:

  1. [26]:
  1. # first you need to import the F object
  2. from nornir.core.filter import F
  1. [27]:
  1. # hosts in group cmh
  2. cmh = nr.filter(F(groups__contains="cmh"))
  3. print(cmh.inventory.hosts.keys())
  1. dict_keys(['host1.cmh', 'host2.cmh', 'spine00.cmh', 'spine01.cmh', 'leaf00.cmh', 'leaf01.cmh'])
  1. [28]:
  1. # devices running either linux or eos
  2. linux_or_eos = nr.filter(F(platform="linux") | F(platform="eos"))
  3. print(linux_or_eos.inventory.hosts.keys())
  1. dict_keys(['host1.cmh', 'host2.cmh', 'spine00.cmh', 'leaf00.cmh', 'host1.bma', 'host2.bma', 'spine00.bma', 'leaf00.bma'])
  1. [29]:
  1. # spines in cmh
  2. cmh_and_spine = nr.filter(F(groups__contains="cmh") & F(role="spine"))
  3. print(cmh_and_spine.inventory.hosts.keys())
  1. dict_keys(['spine00.cmh', 'spine01.cmh'])
  1. [30]:
  1. # cmh devices that are not spines
  2. cmh_and_not_spine = nr.filter(F(groups__contains="cmh") & ~F(role="spine"))
  3. print(cmh_and_not_spine.inventory.hosts.keys())
  1. dict_keys(['host1.cmh', 'host2.cmh', 'leaf00.cmh', 'leaf01.cmh'])

You can also access nested data and even check if dicts/lists/strings contains elements. Again, let’s see by example:

  1. [31]:
  1. nested_string_asd = nr.filter(F(nested_data__a_string__contains="asd"))
  2. print(nested_string_asd.inventory.hosts.keys())
  1. dict_keys(['host1.cmh'])
  1. [32]:
  1. a_dict_element_equals = nr.filter(F(nested_data__a_dict__c=3))
  2. print(a_dict_element_equals.inventory.hosts.keys())
  1. dict_keys(['host2.cmh'])
  1. [33]:
  1. a_list_contains = nr.filter(F(nested_data__a_list__contains=2))
  2. print(a_list_contains.inventory.hosts.keys())
  1. dict_keys(['host1.cmh', 'host2.cmh'])

You can basically access any nested data by separating the elements in the path with two underscores __. Then you can use __contains to check if an element exists or if a string has a particular substring.