Skip to main content

Upgrade NetBox

Introduction

This guide will walk you through the process of upgrading NetBox, including a suggested pre-staging strategy. The approach we take to upgrading NetBox is as follows:

  1. Upgrade to the final patch of the current release, e.g. from 3.7.4 to 3.7.8
  2. Upgrade to the final patch version of the next major release, e.g. from 3.7.8 to 4.0.11

The official NetBox upgrade strategy can be found here: netbox/docs/installation/upgrading.md at develop ยท netbox-community/netbox (github.com)

This feature is a work-in-progress. There are many other considerations to take into account, such as plugin configurations and customizations, as well as sequencing.

Upgrade Playbooks and Templates

Within the NetBox Deploy view in Semaphore, you'll see these playbooks.

  • NetBox Upgrade Check Path - checks the current running version with the mapping table to suggest the next version.
  • NetBox Upgrade to Next Suitable Version - this will take the result from the "Check Path" playbook and perform an upgrade.

image.png

Checking the Upgrade Path

The following screenshot shows that NetBox 3.7.8 has been detected, and based on the upgrade path mapping table, the next suggested version is 4.0.11.

image.png

When the playbook runs it checks a mapping table that is structured like this. The logic is:

  1. If current_version and patch are the different, then upgrade to the next patch in the same release
  2. If current_version and patch are the same, then upgrade to next_major
netbox_upgrade_paths:
  3.7.0:
    patch: 3.7.8
    next_major: 4.0.11
  3.7.1:
    patch: 3.7.8
    next_major: 4.0.11
  3.7.2:
    patch: 3.7.8
    next_major: 4.0.11
  3.7.3:
    patch: 3.7.8
    next_major: 4.0.11
  3.7.4:
    patch: 3.7.8
    next_major: 4.0.11
  3.7.5:
    patch: 3.7.8
    next_major: 4.0.11
  3.7.6:
    patch: 3.7.8
    next_major: 4.0.11
  3.7.7:
    patch: 3.7.8
    next_major: 4.0.11
  3.7.8:
    patch: 3.7.8
    next_major: 4.0.11
  4.0.0:
    patch: 4.0.11
    next_major: 4.1.0

In a production environment you should not upgrade past the final release in the last release. For example, once 4.0.0 was released, 3.7.8 was considered the final stable release. Once 4.1.0 was released, we would consider 4.0.11 stable, and so on.

Running the Upgrade

Here you can see that the suggested upgrade version from the mapping table has been passed to the netbox-deploy playbook to facilitate the upgrade.

image.png

You must take a full backup before starting the upgrade. If possible, we would suggest stopping all services on the server and taking a snapshot (disk image) before proceeding.

Ensure you check compatibility with any plugins that you have installed and have a clear upgrade path for them.

Ensure you check breaking changes in the NetBox Release notes that could impact you, for example, if you have integrated your systems using the NetBox Rest API, endpoints do change from time-to-time, which could break your integrations.

Have a clear test plan.

Pre-Stage Your Upgrades

It's fast and simple to spin up a staging NetBox instance for testing. A "belt and braces" approach to an upgrade is as follows:

  1. Install Semaphore
  2. Install NetBox, ensuring that you match the NetBox version
  3. Backup your current production NetBox instance
  4. Restore to the new staging NetBox instance
  5. Test the upgrade process in safety!
Back to top