From c6644ec1ae688d980f4d6fdb954cadf09fd07369 Mon Sep 17 00:00:00 2001 From: jeremystretch Date: Thu, 8 Sep 2022 10:00:53 -0400 Subject: [PATCH] Annotate upgrade paths in upgrade documentation --- docs/installation/3-netbox.md | 2 +- docs/installation/upgrading.md | 21 +++++++++++++++------ docs/media/installation/upgrade_paths.png | Bin 0 -> 9038 bytes 3 files changed, 16 insertions(+), 7 deletions(-) create mode 100644 docs/media/installation/upgrade_paths.png diff --git a/docs/installation/3-netbox.md b/docs/installation/3-netbox.md index eeb5e6f20..f42e28deb 100644 --- a/docs/installation/3-netbox.md +++ b/docs/installation/3-netbox.md @@ -7,7 +7,7 @@ This section of the documentation discusses installing and configuring the NetBo Begin by installing all system packages required by NetBox and its dependencies. !!! warning "Python 3.8 or later required" - NetBox v3.2 requires Python 3.8, 3.9, or 3.10. + NetBox requires Python 3.8, 3.9, or 3.10. === "Ubuntu" diff --git a/docs/installation/upgrading.md b/docs/installation/upgrading.md index deeec883a..802c13e49 100644 --- a/docs/installation/upgrading.md +++ b/docs/installation/upgrading.md @@ -1,10 +1,19 @@ # Upgrading to a New NetBox Release -## Review the Release Notes +Upgrading NetBox to a new version is pretty simple, however users are cautioned to always review the release notes and save a backup of their current deployment prior to beginning an upgrade. + +NetBox can generally be upgraded directly to any newer release with no interim steps, with the one exception being incrementing major versions. This can be done only from the most recent _minor_ release of the major version. For example, NetBox v2.11.8 can be upgraded to version 3.3.2 following the steps below. However, a deployment of NetBox v2.10.10 or earlier must first be upgraded to any v2.11 release, and then to any v3.x release. (This is to accommodate the consolidation of database schema migrations effected by a major version change). + +[![Upgrade paths](../media/installation/upgrade_paths.png)](../media/installation/upgrade_paths.png) + +!!! warning "Perform a Backup" + Always be sure to save a backup of your current NetBox deployment prior to starting the upgrade process. + +## 1. Review the Release Notes Prior to upgrading your NetBox instance, be sure to carefully review all [release notes](../release-notes/index.md) that have been published since your current version was released. Although the upgrade process typically does not involve additional work, certain releases may introduce breaking or backward-incompatible changes. These are called out in the release notes under the release in which the change went into effect. -## Update Dependencies to Required Versions +## 2. Update Dependencies to Required Versions NetBox v3.0 and later require the following: @@ -14,7 +23,7 @@ NetBox v3.0 and later require the following: | PostgreSQL | 10 | | Redis | 4.0 | -## Install the Latest Release +## 3. Install the Latest Release As with the initial installation, you can upgrade NetBox by either downloading the latest release package or by cloning the `master` branch of the git repository. @@ -87,7 +96,7 @@ sudo git pull origin master sudo git checkout v2.11.11 -## Run the Upgrade Script +## 4. Run the Upgrade Script Once the new code is in place, verify that any optional Python packages required by your deployment (e.g. `napalm` or `django-auth-ldap`) are listed in `local_requirements.txt`. Then, run the upgrade script: @@ -118,7 +127,7 @@ This script performs the following actions: been made to your local codebase and should be investigated. Never attempt to create new migrations unless you are intentionally modifying the database schema. -## Restart the NetBox Services +## 5. Restart the NetBox Services !!! warning If you are upgrading from an installation that does not use a Python virtual environment (any release prior to v2.7.9), you'll need to update the systemd service files to reference the new Python and gunicorn executables before restarting the services. These are located in `/opt/netbox/venv/bin/`. See the example service files in `/opt/netbox/contrib/` for reference. @@ -129,7 +138,7 @@ Finally, restart the gunicorn and RQ services: sudo systemctl restart netbox netbox-rq ``` -## Verify Housekeeping Scheduling +## 6. Verify Housekeeping Scheduling If upgrading from a release prior to NetBox v3.0, check that a cron task (or similar scheduled process) has been configured to run NetBox's nightly housekeeping command. A shell script which invokes this command is included at `contrib/netbox-housekeeping.sh`. It can be linked from your system's daily cron task directory, or included within the crontab directly. (If NetBox has been installed in a nonstandard path, be sure to update the system paths within this script first.) diff --git a/docs/media/installation/upgrade_paths.png b/docs/media/installation/upgrade_paths.png new file mode 100644 index 0000000000000000000000000000000000000000..494744b5826c9a13aab8ee14bc0620d26a84de7d GIT binary patch literal 9038 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 literal 0 HcmV?d00001