Skip to main content

Deploy NetBox Community Plugins

This feature is a work-in-progress. Testing has been completed deploying the plugins in the screenshot to NetBox 3.7.8, and NetBox 4.0.11, and also upgrading NetBox, and then re-deploying using this tool.

Introduction

Deploy, manage, and upgrade NetBox community plugins from within Semaphore:

image.png

You can queue up tasks (providing concurrency=1 in the Semaphore project/dashboard settings, in order to avoid having multiple tasks running at the same time):

image.png

Plugin Mapping Tables

Version Selection

Similar to the mapping logic during the NetBox installation process, each plugin has a defined mapping table that maps the plugin version to the supported NetBox version. For example, in this playbook, the logic is as follows:

  1. Get the current NetBox version from the NetBox API /api/status/
  2. Query the plugin-specific mapping table, in this case for netbox_topology_views
  3. Check the NetBox Version to Plugin Version mapping, and if there is a match, proceed with the installation.

Here you can see that we are running NetBox 3.7.8 and that the playbook has detected that the suitable plugin version is 3.9.0.

image.png

The script then proceeds to download the plugin (to /netos/working-dir/netbox-plugins) and install it.

image.png

If a match isn't found, i.e. the plugin is not supported on that version of NetBox (according to the mapping table) the installation will fail like this:

image.png

Mapping File Example

Each plugin has a mapping file similar to this in the netos-netbox repository. They are manually constructed based on the individual plugin recommendations to ensure that for each NetBox version the latest plugin is installed.

The git_url, version_prefix, and file_type variables are used to construct the URL to pull the plugin from the repo, as URL structures vary between plugins.

netbox_topology_views:
  name: "NetBox Topology Views"
  description: "A NetBox plugin that provides a graphical topology view for devices in NetBox."
  git_url: "https://github.com/netbox-community/netbox-topology-views"
  version_prefix: "v"
  file_type: "zip"
  version_mapping:
    - netbox_version: "4.1.0"
      plugin_version: "4.1.0"

    - netbox_version: "4.0.0"
      plugin_version: "4.0.0"

    - netbox_version: "3.7.8"
      plugin_version: "3.9.0"

Every NetBox version is mapped to a specific plugin version based on the plugin documentation.

Updating Configuration.py

Plugins must be registered in configuration.py, for example; PLUGINS = ['netbox_topology_views']. The playbook will check if the plugin name is included, and if not, add it.

If there is an issue with the plugin, it can cause NetBox to fail to start, i.e. you'll get an NGINX 502 error. If this happens you can use the Health Check script to see if there is anything obvious in the logs. You can also Disable NetBox Plugins to remove the plugin entry from configuration.py.

Post Installation

After running the playbooks in the screenshot at the top of this guide, we can see that the plugins have been installed in NetBox:

image.png

Add New Plugins to Semaphore

The process for adding a plugin to deploy through Semaphore is as follows:

  1. The respective templates must be configured in Semaphore, pointing to the correct playbooks, i.e. netbox-plugin-deploy.yml and netbox-plugin-disable.yml
  2. Within the template, the tag must align with the plugin name, i.e. --tags=netbox_topology_views
  3. The plugin name must be added to netbox-plugin-deploy.yml and netbox-plugin-disable.yml
  4. The mapping file must be configured, e.g. in Ansible /mappings/netbox-plugins/netbox_topology_views.yml

image.png

Some plugins, i.e. netbox_data_flows, caused issues with the venv, and broke the installation of other plugins. Further investigation is required.

To Do

  • Define the optimal sequencing, i.e. upgrade plugin, then NetBox, then migrate, etc.
  • Knit everything together, e.g. upgrading NetBox along with 7 different plugins
  • Ensuring a critical mass of mapping tables and data to make it useful
  • Adding / supporting external/local/private plugins
  • Create combined playbooks / checks to test the installation of all NetBox plugins on all NetBox versions
Back to top