# 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`

<p class="callout info">The official NetBox upgrade strategy can be found here: [netbox/docs/installation/upgrading.md at develop · netbox-community/netbox (github.com)](https://github.com/netbox-community/netbox/blob/develop/docs/installation/upgrading.md)</p>

<p class="callout warning">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.</p>

### 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](https://docs.netos.io/uploads/images/gallery/2024-09/scaled-1680-/DppUnx16QZeKRlCS-image.png)](https://docs.netos.io/uploads/images/gallery/2024-09/DppUnx16QZeKRlCS-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](https://docs.netos.io/uploads/images/gallery/2024-09/scaled-1680-/r7POsdI4tVftAd9f-image.png)](https://docs.netos.io/uploads/images/gallery/2024-09/r7POsdI4tVftAd9f-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`

```yaml
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
```

<p class="callout warning">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.</p>

#### 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](https://docs.netos.io/uploads/images/gallery/2024-09/scaled-1680-/X9FOmLW5G2XvevSC-image.png)](https://docs.netos.io/uploads/images/gallery/2024-09/X9FOmLW5G2XvevSC-image.png)

<p class="callout danger">You must take a [full backup](https://docs.netos.io/books/semaphore-netbox/page/netbox-backup-guide) before starting the upgrade. If possible, we would suggest stopping all services on the server and taking a snapshot (disk image) before proceeding.</p>

<p class="callout danger">Ensure you check compatibility with any plugins that you have installed and have a [clear upgrade path for them](https://docs.netos.io/books/semaphore-netbox/page/deploy-netbox-community-plugins).</p>

<p class="callout danger">Ensure you check breaking changes in the [NetBox Release notes](https://github.com/netbox-community/netbox/releases) that could impact you, for example, if you have integrated your systems using the [NetBox Rest API](https://netbox.readthedocs.io/en/stable/integrations/rest-api/), endpoints do change from time-to-time, which could break your integrations.</p>

<p class="callout danger">Have a clear test plan.</p>

### 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](https://docs.netos.io/books/semaphore-netops/page/deploy-semaphore-netos-projects)
2. [Install NetBox, ensuring that you match the NetBox version](https://docs.netos.io/books/semaphore-netbox/page/install-netbox)
3. [Backup your current production NetBox instance](https://docs.netos.io/books/semaphore-netbox/page/netbox-backup-guide)
4. [Restore to the new staging NetBox instance](https://docs.netos.io/books/semaphore-netbox/page/netbox-restoration-guide)
5. Test the upgrade process in safety!