This section of the documentation provides guidance on upgrading to recent versions of Graylog. If you are upgrading from an older version, be sure to begin by reading about the incremental upgrade path. Additionally, there are guides for upgrading Graylog for both direct deployments and containerized deployments.
Prerequisites
Before proceeding, ensure that the following prerequisites are met:
-
You must be a Graylog administrator in order to perform a system upgrade.
-
You must be on a supported operating system or recent Docker version for containerized deployments.
-
It is essential to maintain version compatibility for all system dependencies.
Approach to Upgrading Graylog
Upgrading Graylog is a measured process that, at a high level, requires planning for your target version and backing up your data. Generally, we recommend you follow this approach to upgrade Graylog.
-
Review the release notes for your desired version of Graylog to check for any breaking changes.
-
Verify your system and version compatibility by reviewing the Compatibility Matrix. If you are performing an upgrade from an older Graylog version, please review the following section on the incremental upgrade process.
-
Back up your MongoDB, Data Node, and Graylog data, including log messages, metadata, and configuration settings. See Backup and Restore Best Practices for more information.
-
If necessary, satisfy the prerequisites of a minimum required MongoDB version before upgrading Graylog according to the compatibility matrix.
Hint: If you are using Graylog with self-managed OpenSearch, you also need to upgrade your version of OpenSearch to maintain Graylog compatibility. -
Stop the Graylog service.
-
Perform the upgrade by updating the repository package to the target version.
Incremental Upgrade
When upgrading across multiple major versions of Graylog (i.e. 4.x to 5.x to 6.x), it is essential to perform the upgrade incrementally. The recommended process is to first upgrade to the next major version of Graylog, then continue to upgrade to each subsequent major version before finally upgrading to the most recent release package.
Incremental Upgrade Path Example
You can see an example of this strategy if we look at performing an upgrade from Graylog 4.3 to Graylog 6.1. If you follow an incremental upgrade path as recommended, upgrading the Graylog service would proceed as follows:
Graylog 4.3 > Graylog 5.0 > Graylog 6.0 > Graylog 6.1.
Version Compatibility of System Dependencies
System dependencies, like MongoDB, should be updated as needed to match the new Graylog version during the incremental upgrade process. You must upgrade each system dependency to at least its minimum required version to match each new version of Graylog; however, we recommend you upgrade system dependencies to the latest supported version whenever possible. Upgrading system dependencies must be done before upgrading Graylog.
Version Compatibility Example
As in the incremental upgrade path example above, moving from Graylog 4.3 to Graylog 5.0 would mean upgrading MongoDB to at least version 5.0.7 before updating to Graylog 5.0. Additionally, Graylog 6.0 introduces support for MongoDB 7.0. So, let’s assume this example upgrade process looks something like this:
-
Upgrade MongoDB from 5.0 to 5.0.7.
-
Upgrade Graylog from 4.3 to 5.0.
-
Upgrade Graylog from 5.0 to 6.0.
-
Upgrade MongoDB from 5.0.7 to 7.0.
-
Upgrade Graylog from 6.0 to 6.1.
Multi-Node Clusters
For clusters that contain multiple Data Node and Graylog nodes, like the standardized Conventional cluster design, the upgrade process must be performed on each node sequentially to upgrade the entire cluster. We generally recommend beginning on the leader node first before upgrading the follower nodes.
Upgrade OS Packages
When upgrading from an earlier version of Graylog, follow the previously used installation method (e.g. operating system package) using the new version numbers. We provide the following upgrade guides to use with compatible operating systems with step-by-step instructions on upgrading Graylog for both DEB and RPM-based systems:
Upgrade in Docker
To upgrade Graylog in a Docker container, you must essentially update the container to pull the latest images of Graylog, Data Node, and MongoDB. For more information on this process, seeUpgrade Graylog in Docker.
