NetBox Branching

NetBox is the world's leading source of truth for network infrastructure, featuring an extensive and complex data model. But sometimes it can be challenging to orchestrate changes, especially when working within a large team. This plugin introduces a new paradigm for NetBox to help overcome these challenges: branching.

If you're familiar with git or similar version control systems, the concept of branching should be familiar. Essentially, this plugin allows you to make copies of NetBox's data model and alter them independently. Your changes will be reflected only within the branch you're working on, until you decide to merge your branch into the main data model.

This allows you and your colleagues to stage changes within isolated environments and avoid interfering with one another's work or pushing changes to the network prematurely. Each branch can be synchronized as needed to keep up to date with external changes, and merged when needed.

Features

• Users can create new branches and switch between them seamlessly while navigating the web UI.

• Each branch exists in isolation from its peers: Changes made within one branch won't affect any other branches.

• Standard NetBox permissions are employed to control which users can perform branch operations.

• Branches can be created, synchronized, merged, reverted, archived, and deleted through the REST API.

• No external dependencies! This plugin requires only a supported version of NetBox (see COMPATIBILITY.md for the current matrix) and a conventional PostgreSQL database.

Terminology

• Main is shorthand for the primary NetBox state. Any changes made outside the context of a specific branch are made here.

• The creation, modification, or deletion of an object is a change.

• A branch is an independent copy of the NetBox data model which diverges from main at a set point in time. Any changes to main after that time will not be reflected in the branch. Likewise, changes made within the branch will not be reflected in main.

• Branches are provisioned automatically upon creation. The initial state of a branch is identical to the state of main at the time it was provisioned.

• Changes in main can be synchronized at any time into a branch. Branches are independent of one another: changes must be synchronized into each branch individually. This ensures complete isolation among branches.

• When NetBox is upgraded, branches must be migrated to apply the same database migrations to each branch schema before they can be used again.

• Once the work within a branch has been completed, it can be merged into main. Once a branch has been merged, it is generally no longer used.

• Merged changes can be reverted provided the branch has not yet been archived or deleted. This effectively replays the changes in reverse order to undo the relevant changes.

• A merged branch can be archived to deprovision its PostgreSQL schema while retaining the branch's metadata for future reference. Archived branches cannot be reverted.

Workflow

The first step is to create a new branch. Upon creation, a background job is automatically queued to provision a dedicated PostgreSQL schema for the branch. When provisioning is complete, the branch's status is updated to "ready."

The full set of branch states and the transitions between them is documented under Branch: Status.

Users can now activate the branch and begin making changes within it. These changes will be contained to the branch, and will not impact main. Likewise, any changes to main will not be reflected in the branch until it has been synchronized by a user. A branch may be synchronized repeatedly to keep it up to date with main over time.

tip

If you would like to share the work you've done in a branch with a colleague, you cannot just copy the URL you're currently viewing. Instead, if you have activated a branch other than main, you will find a Share button on each object detail view page. Clicking Share will copy a shareable URL that you can send to others.

Once work in the branch has been completed, it can be merged into main.

In the event a branch should not have been merged, it can be reverted. Previously merged changes to main will be unwound and the branch will be restored to its pre-merge state. The branch is again marked as ready for additional changes, if needed, and can be merged again.

Plugin Installation

1. Database Preparation

Before installing this plugin, ensure that the PostgreSQL user as which NetBox authenticates has permission to create new schemas in the database. This can be achieved by issuing the following command in the PostgreSQL shell (substituting $database and $user with their respective values):

GRANT CREATE ON DATABASE $database TO $user;

2. Virtual Environment

The plugin can be installed from PyPI. First, activate the Python virtual environment used by NetBox (which is typically located at /opt/netbox/venv/):

source /opt/netbox/venv/bin/activate

note

You may need to modify the source command above if your virtual environment has been installed in a different location.

3. Python Package

Use pip to install the Python package:

pip install netboxlabs-netbox-branching

4. Enable Plugin

Add netbox_branching to the PLUGINS list in configuration.py.

PLUGINS = [
    # ...
    'netbox_branching',
]

note

If there are no plugins already installed, you might need to create this parameter. If so, be sure to define PLUGINS as a list containing the plugin name as above, rather than just the name.

5. Configuration

Wrap your DATABASES configuration parameter with DynamicSchemaDict in configuration.py, as shown below:

from netbox_branching.utilities import DynamicSchemaDict

DATABASES = DynamicSchemaDict({
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'netbox',
        'USER': 'netbox',
        ...
    }
})

Additionally, declare DATABASE_ROUTERS to employ the plugin's custom database router to support branching:

DATABASE_ROUTERS = [
    'netbox_branching.database.BranchAwareRouter',
]

The plugin validates both of these settings on startup; NetBox will fail to start with an ImproperlyConfigured error if either is missing.

Optional plugin-specific settings are configured under the PLUGINS_CONFIG dictionary; see the Configuration page for the full list of supported parameters.

6. Database Migrations

Run the included database migrations:

cd /opt/netbox/netbox
./manage.py migrate

7. Restart NetBox

Restart the NetBox services to load the plugin:

sudo systemctl restart netbox netbox-rq

Known Limitations

There are currently a few limitations to the functionality provided by this plugin that are worth highlighting. We hope to address these in future releases.

• Branches must be migrated after a NetBox minor version upgrade. Database migrations introduced by a minor version upgrade (e.g. v4.4 → v4.5) are not applied to branch schemas automatically. After upgrading, existing branches will be marked with the Pending Migrations status until they are migrated using the Migrate action. Upgrading between patch releases (e.g. v4.4.0 → v4.4.1) does not require this step. Where possible, merging or removing open branches before a minor upgrade is still the simpler path.

• Open branches will not reflect newly installed plugins. Any branches created before installing a new plugin will not be updated to support its models. Note, however, that installing a new plugin will generally not impede the use of existing branches. Users are encouraged to install all necessary plugins prior to creating branches. (This also applies to database migrations introduced by upgrading a plugin.)

• Multi-table inheritance is not supported. Models that use Django's multi-table inheritance cannot be branched. See the Plugin Development Guide for details.