Merge pull request #80 from TheNetworkGuy/virtual_machines

Virtual machines

.gitignore

@@ -1,4 +1,5 @@
 *.log
+.venv
 config.py
 # Byte-compiled / optimized / DLL files
 __pycache__/

README.md

@@ -87,39 +87,59 @@ You can make the `zabbix_hostid` field hidden or read-only to prevent human inte
 
 This is optional and there is a use case for leaving it read-write in the UI to manually change the ID. For example to re-run a sync.
 
+## Virtual Machine (VM) Syncing
+In order to use VM syncing, make sure that the `zabbix_id` custom field is also present on Virtual machine objects in Netbox.
+
+Use the `config.py` file and set the `sync_vms` variable to `True`.
+
+You can set the `vm_hostgroup_format` variable to a customizable value for VM hostgroups. The default is `cluster_type/cluster/role`.
+
+To enable filtering for VM's, check the `nb_vm_filter` variable out. It works the same as with the device filter (see documentation under "Hostgroup layout"). Note that not all filtering capabilities and properties of devices are applicable to VM's and vice-versa. Check the Netbox API documentation to see which filtering options are available for each object type.
+
 ## Config file
 
 ### Hostgroup
-Setting the `create_hostgroups` variable to `False` requires manual hostgroup creation for devices in a new category.
+Setting the `create_hostgroups` variable to `False` requires manual hostgroup creation for devices in a new category. I would recommend setting this variable to `True` since leaving it on `False` results in a lot of manual work.
 
-The format can be set with the `hostgroup_format` variable.
+The format can be set with the `hostgroup_format` variable for devices and `vm_hostgroup_format` for devices.
 
-Any nested parent hostgroups will also be created automatically.
+Any nested parent hostgroups will also be created automatically. For instance the region `Berlin` with parent region `Germany` will create the hostgroup `Germany/Berlin`.
 
 Make sure that the Zabbix user has proper permissions to create hosts.
 The hostgroups are in a nested format. This means that proper permissions only need to be applied to the site name hostgroup and cascaded to any child hostgroups.
 
 #### Layout
 The default hostgroup layout is "site/manufacturer/device_role".
-
-**Variables**
-
 You can change this behaviour with the hostgroup_format variable. The following values can be used:
+
+**Both devices and virtual machines**
 |  name | description  |
 | ------------ | ------------ |
-|dev_location|The device location name|
-|dev_role|The device role name|
-|manufacturer|Manufacturer name|
-|region|The region name of the device|
+|role|Role name of a device or VM|
+|region|The region name|
 |site|Site name|
 |site_group|Site group name|
 |tenant|Tenant name|
 |tenant_group|Tenant group name|
+|platform|Software platform of a device or VM|
+|custom fields|See the section "Layout -> Custom Fields" to use custom fields as hostgroup variable|
+
+**Only for devices**
+|  name | description  |
+| ------------ | ------------ |
+|location|The device location name|
+|manufacturer|Device manufacturer name|
+
+**Only for VMs**
+|  name | description  |
+| ------------ | ------------ |
+|cluster|VM cluster name|
+|cluster_type|VM cluster type|
 
 
-You can specify the value like so, sperated by a "/":
+You can specify the value sperated by a "/" like so:
 ```
-hostgroup_format = "tenant/site/dev_location/dev_role"
+hostgroup_format = "tenant/site/dev_location/role"
 ```
 **Group traversal**
 
@@ -129,11 +149,18 @@ However, by setting `traverse_region` to `True` in `config.py` the script will r
 
 **Custom fields**
 
-You can also use the value of custom fields under the device object.
+You can use the value of custom fields for hostgroup generation. This allows more freedom and even allows a full static mapping instead of a dynamic rendered hostgroup name.
 
-This allows more freedom and even allows a full static mapping instead of a dynamic rendered hostgroup name.
+For instance a custom field with the name `mycustomfieldname` and type string has the following values for 2 devices:
 ```
-hostgroup_format = "site/mycustomfieldname"
+Device A has the value Train for custom field mycustomfieldname.
+Device B has the value Bus for custom field mycustomfieldname.
+Both devices are located in the site Paris.
+```
+With the hostgroup format `site/mycustomfieldname` the following hostgroups will be generated:
+```
+Device A: Paris/Train
+Device B: Paris/Bus
 ```
 **Empty variables or hostgroups**
 

config.py.example

@@ -3,7 +3,7 @@
 # coming from config context instead of a custom field.
 templates_config_context = False
 
-# Set to true to give config context templates a 
+# Set to true to give config context templates a
 # higher priority then custom field templates
 templates_config_context_overrule = False
 
@@ -21,6 +21,14 @@ create_hostgroups = True
 ## Create journal entries
 create_journal = False
 
+## Virtual machine sync
+# Set sync_vms to True in order to use this new feature
+# Use the hostgroup vm_hostgroup_format mapper for specific
+# hostgroup atributes of VM's such as cluster_type and cluster
+sync_vms = False
+# Check the README documentation for values to use in the VM hostgroup format.
+vm_hostgroup_format = "cluster_type/cluster/role"
+
 ## Proxy Sync
 # Set to true to enable removal of proxy's under hosts. Use with caution and make sure that you specified
 # all the required proxy's in the device config context before enabeling this option.
@@ -32,16 +40,16 @@ zabbix_device_removal = ["Decommissioning", "Inventory"]
 zabbix_device_disable = ["Offline", "Planned", "Staged", "Failed"]
 
 ## Hostgroup mapping
-# Available choices: dev_location, dev_role, manufacturer, region, site, site_group, tenant, tenant_group
+# See the README documentation for available options
 # You can also use CF (custom field) names under the device. The CF content will be used for the hostgroup generation.
 #
 # When using region in the group name, the default behaviour is to use name of the directly assigned region.
 # By setting traverse_regions to True the full path of all parent regions will be used in the hostgroup, e.g.:
 #
 # 'Global/Europe/Netherlands/Amsterdam' instead of just 'Amsterdam'.
 #
-# traverse_site_groups controls the same behaviour for any assigned site_groups.   
-hostgroup_format = "site/manufacturer/dev_role"
+# traverse_site_groups controls the same behaviour for any assigned site_groups.
+hostgroup_format = "site/manufacturer/role"
 traverse_regions = False
 traverse_site_groups = False
 
@@ -56,6 +64,8 @@ traverse_site_groups = False
 
 # Default device filter, only get devices which have a name in Netbox:
 nb_device_filter = {"name__n": "null"}
+# Default filter for VMs
+nb_vm_filter = {"name__n": "null"}
 
 ## Inventory
 # See https://www.zabbix.com/documentation/current/en/manual/config/hosts/inventory#building-inventory