Upgrade Graylog

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.
Plan to maintain version compatibility with MongoDB and your chosen search backend, i.e. Data Node or OpenSearch.

Highlights

The following highlights provide a summary of the key takeaways from this article:

Always read the release notes for your target version to understand breaking changes and new requirements.
Review the incremental upgrade path before upgrading from older versions of Graylog to avoid breaking changes.
Always back up Graylog, MongoDB, and Data Node (or OpenSearch) data before starting the upgrade process.
Ensure version compatibility is maintained by consulting the Compatibility Matrix.
If you are using Data Node as your search backend, upgrade Graylog first, then Data Node, ensuring both are on the same release version.
System dependencies, like MongoDB and OpenSearch (if used) must be upgraded before upgrading Graylog.
Rolling upgrades are generally recommended, but non-rolling restart upgrades are also supported.
Refer to the upgrade guides specific to your operating system or Docker environment for step-by-step instructions.

Upgrading Process

Upgrading your Graylog environment 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 upgrading the Graylog and Data Node services. For step-by-step instructions, see the Upgrade Guides.

Hint: This process generally assumes you are performing an upgrade to a direct deployment of Graylog and Data Node on a supported Linux-based system. For information on upgrading Graylog in a container, see Upgrade in Docker.

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, 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.
Upgrade the Graylog service first and then the Data Node service by updating the repository packages to the target version on all nodes. Both Graylog and Data Node must be on the same Graylog release version.

Upgrade with Self-Managed OpenSearch

If you are using Graylog with self-managed OpenSearch instead of Data Node and wish to upgrade your OpenSearch service, you will need to upgrade OpenSearch before you upgrade Graylog. Ensure that your target version of OpenSearch is compatible with your desired version of Graylog. For information on upgrading OpenSearch, see the OpenSearch documentation.

Upgrade Methods

When upgrading Graylog, consider which upgrade method is preferable for your environment and uptime requirements.

Rolling Upgrade

A rolling upgrade allows for upgrading a Graylog cluster with minimal service disruption by updating one node at a time. During this process, each node is individually taken offline, upgraded, and restarted while the remaining nodes continue to handle traffic. This ensures that log ingestion and access to the web interface remain available throughout the upgrade. Rolling upgrades are well-suited for production environments where high availability is essential. The process requires careful coordination to ensure compatibility between nodes running different versions during the upgrade window, but it provides the benefit of maintaining continuous service.

Hint: Except where necessary, rolling upgrades are preferred, and the individual upgrade guides provide instructions for this approach.

Non-Rolling Restart Upgrade

A non-rolling restart upgrade involves shutting down all nodes before upgrading the nodes and bringing the cluster back online. This method is relatively straightforward to execute in smaller environments or during scheduled maintenance windows; however, it results in a service interruption, meaning log ingestion and access to the Graylog interface will be unavailable during the upgrade process. Restart upgrades are sometimes preferred in non-critical or test environments where downtime is acceptable and operational complexity needs to be minimized.

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.2. 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.2

Hint: For multi-node environments, this means updating ALL nodes in the cluster to the same version before proceeding to the next. As in the example above, in an upgrade from version 4.3 to version 6.2, you would upgrade all nodes from 4.1 to 5.0, then from 5.0 to 6.0, and finally 6.0 to 6.2.

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.

Hint: If you are using Graylog with self-managed OpenSearch, OpenSearch is also a system dependency. Therefore, OpenSearch must be upgraded incrementally to match at least the minimally supported version for each Graylog version.

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.

Release Notes for Breaking Changes

The following release notes should be read carefully before you start the upgrade process. Breaking changes and dependency requirements are documented in those notes.

Hint: The upgrade notes are always written as if you are upgrading from one stable release prior.