Why a multi-node Graylog upgrade needs a written sequence
A multi-node Graylog upgrade needs a written sequence because the cluster has several moving parts that depend on each other, and logs keep arriving while they change. A typical cluster combines Graylog server nodes, a MongoDB replica set for configuration and metadata, and either Graylog Data Node or self-managed OpenSearch for log storage. The supported path is to back up everything, upgrade the dependencies that Graylog relies on, bring every Graylog node to the same release, and then move the search backend. Each step has to be confirmed before the next one starts, which is why the plan should exist on paper before the first node is touched.
The reasons for planning are concrete. Each Graylog release has a compatibility range for MongoDB and OpenSearch, and the Graylog compatibility matrix lists the range for the 7.0 to 7.2 line, so the reader should check the database versions in the cluster against that table before deciding the order. Deprecations also force the timeline: use of OpenSearch 1.x has been deprecated since Graylog 7.0 and is scheduled for removal in Graylog 8.0, so a cluster still on 1.x has a dated migration ahead of it. The Graylog upgrade documentation is the reference for each step, and the current documentation covers version 7.2. Confirm the 7.2.0 tag date against the release page before you cite it in change records, since the date the project shows on its tags page is the one to rely on.
What changes across the upgrade path and what each change requires
This table lists the version, backend and search-platform changes that affect a multi-node Graylog upgrade, with the action each one requires. Read each row as a question to answer before the upgrade window opens, and confirm every row against the release notes for your target version.
| Change | Impact on the cluster | Action needed |
|---|---|---|
| MongoDB 7.x up to 8.2.x for Graylog 7.0 to 7.2 | Graylog 7.0 to 7.2 support MongoDB 7.x up to 8.2.x, so the configuration database must sit inside that range before Graylog is upgraded. | Confirm the current MongoDB version against the compatibility matrix, then plan MongoDB steps and a replica set upgrade order first. |
| OpenSearch 1.1.x up to 3.7.x support | Graylog 7.0 to 7.2 support OpenSearch from 1.1.x up to 3.7.x, so a search backend outside that range must move before or with the Graylog step. | Check the running OpenSearch version and the exact range listed for your target Graylog release. |
| Graylog Security needs OpenSearch 2.0 or later | Clusters running Graylog Security depend on a newer OpenSearch baseline than Graylog Open alone, which can change the backend upgrade sequence. | Confirm your edition and the OpenSearch version it requires, and schedule any backend upgrade ahead of the Graylog step. |
| OpenSearch 1.x deprecation | Use of OpenSearch 1.x has been deprecated since Graylog 7.0 and is planned for removal in Graylog 8.0, so a cluster still on 1.x carries a future upgrade obligation. | Record every node still on OpenSearch 1.x and plan a move to a supported backend before Graylog 8.0 is adopted. |
| Data Node as the recommended search backend | Graylog recommends Data Node as the search backend, and Data Node is upgraded after Graylog so both components run the same release. | Decide whether to migrate to Data Node as part of the project, and sequence Data Node after the Graylog nodes in the runbook. |
| Rolling restart for Data Node OpenSearch in 7.2.0 | Graylog 7.2.0 added a rolling restart feature and endpoint for Data Node's OpenSearch, which can change how restarts are coordinated across Data Nodes. | Use the feature only after confirming its behavior in the 7.2.0 changelog, and test it on a non-production cluster first. |
How to choose the target version and the supported upgrade path
Choose the target release before anyone touches a node. The compatibility matrix in the Graylog documentation is the controlling source: it lists which MongoDB and OpenSearch ranges each Graylog line supports, and it shows where Graylog Security needs a newer OpenSearch than Graylog Open. Read the row for your target and then check every component you run against it: Graylog server, MongoDB, Data Node or OpenSearch, the JVM, and any plugins or Enterprise or Security features you license. Record the result in the change plan. A component outside its supported range is a stop condition, not a warning to accept during the window.
Read the Graylog changelog for every release between your current version and the target, not only the final one. Breaking changes, removed features and new defaults are listed per release, and a jump that skips a release can hide a change you need to plan for. Confirm release dates on the tags page of the Graylog server repository rather than assuming them from memory or from documentation pages, because the current documentation may already describe a newer line than the one you are moving to. Ask your vendor or implementation partner to confirm the exact versions in your environment before the plan is approved.
Mark which steps cross a major version boundary, since those carry the largest prerequisite changes, such as runtime requirements, database minimums and API or parsing changes that a sibling upgrade guide covers in detail. A minor step within one major line usually needs the same checks with fewer surprises. If your path crosses more than one major line, decide whether each intermediate release is installed and verified in turn. Stepwise paths are slower but make it possible to roll back to a known state at each stage, which matters more on a multi-node cluster than on a single server.
What to back up and inventory before the first node changes
Every upgrade step depends on a known rollback point and a clear picture of what the cluster runs today. The cards below cover the backups, the inventory, the test environment and the journal and disk checks that should be finished before the maintenance window opens. Work through them in order, because a gap in one usually shows up as a failure in the next.
Full backup of every data store
Back up the Graylog configuration, MongoDB and the Data Node or OpenSearch data before anything changes, as the Graylog upgrade documentation requires. The configuration and server.conf files on each Graylog node belong in the same snapshot set, so a rollback restores the matching settings. Confirm that you can restore each backup to a scratch host, not just that the backup job reported success.
MongoDB backup and replica set state
MongoDB holds configuration, users, streams, pipelines and dashboards, so it is the store whose loss hurts most. Record the replica set status and confirm a primary is elected and all members are healthy before taking the dump or snapshot. Keep the backup from the same window as the other stores so the configuration and the index metadata line up.
Data Node or OpenSearch snapshot
Log data lives in the search backend, and a failed upgrade can leave indices unreadable. Register a snapshot repository on storage outside the cluster, then take a snapshot of all indices and verify its state is complete. Note the index set names and the snapshot name in the change record so the restore path is clear during an incident.
Inventory of inputs, content and code
List every input, its node assignment, and whether it is running, plus each installed plugin, pipeline, content pack, stream, dashboard and event definition. Add any custom scripts or in-house plugins that call the API, since they break first when an API changes. Export the content where Graylog allows it, so you can compare the same objects after the upgrade.
Test environment that mirrors the cluster
Build a non-production copy with the same node count, MongoDB replica set shape, Data Node layout and load balancer, then run the upgrade there first. Use a copy of the production configuration with secrets replaced, and send it representative traffic so the journal and processing behave as they will in production. Record every step that needed a manual fix, since those become runbook items.
Journal and disk headroom
Each Graylog node buffers incoming messages in its message journal while a node is down or restarting, so confirm the journal is draining and has room before the window opens. Check free disk on the journal and index volumes against the sizing guidance, which advises giving the journal 3 to 5 times daily ingest on SSDs. Ask your team to confirm the journal size on each node, because a full journal stops inputs.
The upgrade sequence, with checks and rollback points at each stage
The sequence moves a multi-node Graylog cluster from one release to the next in a fixed order, so every component stays within its supported version range and inputs keep buffering safely while each phase completes. Each phase closes with a check and a rollback point the operations team can act on.
Back up Graylog, MongoDB and the search backend
Before any change, the operations team takes a backup of Graylog configuration, MongoDB and the Data Node or OpenSearch data, as Graylog's upgrade documentation requires. Confirm the backup can be restored by testing it in a non-production environment, and record the current versions of every node. The step is done when the restore test succeeds and the version inventory is saved with the change record. This is the first rollback point: if nothing has been changed yet, the cluster stays as it was.
Check prerequisites and upgrade MongoDB and OpenSearch
Compare the current MongoDB and OpenSearch versions with the compatibility matrix for the target Graylog release. Where the target requires a newer database or search version, upgrade it first, one node at a time, following the vendor's replica set or cluster guidance. Confirm that the MongoDB replica set has a healthy primary and that the search cluster reports green before moving on. The rollback point here is the pre-upgrade backup: restoring it means reverting the database tier to the version recorded in step one, then confirming Graylog nodes still connect.
Remove follower nodes from leader role and upgrade them
Set is_leader to false on each follower Graylog node in the configuration, restart it, and confirm it is no longer acting as the leader. Stop the Graylog service on that node, install the target package or image, and start it again. Check that the node joins the cluster, reports the target version and that its journal is accepting messages. Upgrade one follower at a time so the remaining nodes continue processing. The checkpoint is a node that is running the target version and appears healthy in the system overview, with no new errors in its server log.
Upgrade the remaining nodes to the same version
Repeat the follower procedure on every remaining Graylog node, including the leader last, so that all Graylog nodes run the same release. Do not start the next phase while any node still reports the previous version. Confirm the leader role moves back to the intended node and that only one node reports itself as leader. Check the cluster's node list and the Graylog web interface on each node. Once every node shows the same version, the Graylog tier is consistent and this is the second rollback point. Rolling back a single node means reinstalling the prior package and restoring its configuration, which is only safe while the other nodes remain on the same previous release.
Verify inputs and journal drain before the next phase
Before upgrading Data Node, confirm that every input is running and that the message journal is draining rather than growing. Compare the journal utilization and throughput with the readings taken before the upgrade, and check that the input count and error counts are unchanged. Search for recent messages from a known source to confirm end-to-end flow. If the journal keeps growing, pause and investigate before continuing, because the journal is the buffer that protects inputs while the search backend is unavailable. The step closes when inputs run cleanly and the journal has returned to its normal range.
Upgrade Data Node after Graylog
Upgrade the Data Node cluster once all Graylog nodes run the target release, so that both components end on the same version. Work through the Data Node nodes according to the vendor's guidance for the release, and confirm cluster health after each node rejoins. For Graylog 7.2 and later, the rolling restart feature for Data Node's OpenSearch can help manage restarts, as described in the changelog. Confirm that all Data Node nodes report the target version and that shards are allocated. The rollback point is again the backup from step one, and restoring Data Node data requires the same version range the backup was taken from.
Confirm post-upgrade health and close the change
Run the post-upgrade checks: all Graylog and Data Node instances report the target version, the MongoDB replica set and search cluster are healthy, inputs are running, the journal is draining, and search and dashboards return current results. Review event definitions and alert notifications to confirm they still fire. Record the final version inventory and check results in the change record, and keep the pre-upgrade backup until the team has agreed the retention period for it. The change is complete when the checks pass and the record is signed off by the operations owner.
Keeping inputs flowing through the message journal
The message journal is what keeps log intake running while a Graylog node is out of service. When a node is stopped for its upgrade, the inputs bound to it can still accept messages, and those messages are written to the node's journal on disk until the Graylog process can process them again. Before the first restart, confirm that each node has enough journal capacity for the outage you plan. The Graylog system architecture guidance advises giving the message journal 3 to 5 times daily ingest on SSDs, so a journal sized for a short restart may fill during a longer maintenance window. Ask your team to check the journal size and the current disk usage on every node, and agree on a maximum outage per node before the change window opens.
The load balancer is the other half of keeping intake steady. The multi-node guidance places a load balancer in front of the Graylog nodes, so you can remove the node being upgraded from rotation and send new traffic to the nodes still on the running release. Confirm that the health check on the load balancer marks the node as down when its Graylog service stops, and that inputs reaching the cluster through the balancer are not pinned to the node you are taking out. After each node returns, check the journal in the node's system overview or metrics, and confirm that the uncommitted message count falls toward zero before you move on. A journal that stays full or grows after restart points to a processing or output problem that should be resolved before the next node is upgraded.
How to test the upgrade and roll back if a phase fails
A rehearsal in a staging cluster is the only place to find the breaking changes in your own configuration before production sees them. The staging cluster should match production in Graylog, MongoDB and Data Node or OpenSearch versions, node count, inputs, pipelines and plugins, and it should hold a data volume close to production so that index rotation, journal behavior and restart times are representative. Run the full sequence in the same order you plan for production, including the backup step.
- Match the topology: Use the same number of Graylog server nodes, MongoDB members and Data Node members, with the same load balancer in front.
- Load realistic data: Replay or copy a representative slice of traffic so the journal and indices behave as they would under production load.
- Record the steps: Write down every command, timing and deviation so the production runbook is a tested document, not a plan.
- Test the restore: Restore the staging backups onto a separate system to confirm they are usable before relying on them.
- Repeat after changes: Rerun the rehearsal if versions, plugins or pipeline rules change after the first run.
Before you sign off, confirm with your vendor or partner which configuration changes the target release requires, and check the official upgrade notes for that version.",
Each phase, whether MongoDB, OpenSearch or Data Node, Graylog server nodes or inputs, should end with a defined check. The purpose is to confirm the cluster is healthy and that the next phase is safe to start. Treat a failed check as a stop condition, not a warning to revisit later. Keep the checks identical between staging and production so results are comparable.
- Search: Run saved searches over a known time range and compare counts against the pre-upgrade baseline.
- Dashboards: Open the main dashboards and confirm widgets load and return data.
- Event definitions: Confirm definitions are enabled, evaluate on schedule and that notifications still reach their destinations.
- Inputs: Verify each input is running on every node and that the message journal is draining rather than growing.
- API clients: Run the scripts and integrations that call the Graylog API, since they can break on changed endpoints or token defaults even when the UI works.
Record the baseline before the first phase starts, so each later check has something concrete to compare against.",
Rollback depends on the backups taken before the first change. Those backups are the recovery point. If you did not capture Graylog configuration, MongoDB data and Data Node or OpenSearch indices before starting, you may not be able to return to the previous state cleanly. Confirm the backup contents and restore procedure for each component before the upgrade window opens.
- Restore the database first: Bring MongoDB back to its pre-upgrade data and check that the replica set is healthy before starting Graylog.
- Restore the search backend: Restore Data Node or OpenSearch data from the snapshot or backup taken before the change.
- Reinstall the previous versions: Reinstall the Graylog packages or images at the earlier version, then confirm all nodes are on the same release again.
- Replay the journal state: Check how buffered messages in the journal are handled after a restore so you do not duplicate or lose data without knowing it.
- Confirm the restore with checks: Repeat the same search, dashboard, event and input checks used for verification.
Ask your team to confirm which backup format and restore steps apply to your environment before the window.",
Not every failure requires a full rollback. The decision depends on which phase failed, whether the failure is contained to one node and whether the cluster can keep ingesting safely. Define these thresholds in advance, with named people who can make the call during the change window. Unplanned decisions under pressure are where data loss and extended outages usually start.
- Stop on database errors: If MongoDB will not reach a healthy replica set state, stop and resolve it before touching Graylog.
- Isolate a failing node: If one Graylog node fails verification, remove it from the load balancer and check whether the rest of the cluster is stable.
- Watch the journal: If the journal fills faster than it drains, pause further phases and protect ingestion.
- Escalate on API breakage: If automation fails, decide whether to fix the client or roll back, based on business impact.
- Document the decision: Record the failed check, the time and the action taken for your change record and any later review.
Agree these criteria with your operations and security owners before the change window starts.
What makes a Graylog cluster upgrade take longer
The table compares the factors that stretch a multi-node Graylog upgrade, from node counts and data volume to plugins, backend choice and change windows. Read each row as a question to answer about your own cluster before you set a schedule. The main takeaway is that the rehearsal and the custom code inventory usually decide the timeline more than the packages themselves.
| Effort driver | Why it changes the work | How to keep it under control |
|---|---|---|
| Graylog and MongoDB node count | Each Graylog node must reach the same version before the next step, and MongoDB members are upgraded in replica set order, so more members mean more sequential restarts and health checks. | Confirm the node layout against the multi-node guide before scheduling, and plan one node at a time with the journal draining between steps. |
| Data size and index count | Larger indices take longer to snapshot for the mandatory backup, and more indices increase what must be verified after the upgrade. | Measure total stored data and index count in your environment, and confirm backup and restore time with your storage team. |
| Custom plugins and API scripts | In-house plugins and automation built against the API may need code changes, rebuilds or retesting before the cluster can move. | Inventory every plugin, script and API client, and check each against the upgrade notes for the target release. |
| Enterprise or Security features in use | Features such as data lake archive restore, correlation or SIEM content depend on licensed components whose versions and configuration must line up with the upgrade. | List which licensed features are enabled and confirm with Graylog which versions support them. |
| OpenSearch or Data Node backend | Self-managed OpenSearch has its own version compatibility range and a deprecation schedule for 1.x, while Data Node is upgraded after Graylog so both run the same release. | Identify the current backend and version, then confirm the target release's compatibility matrix before planning. |
| Change freeze and maintenance windows | Frozen periods and short approved windows limit how many steps fit in one change, and a stalled step can push the rest of the cluster into a partial state. | Agree the window length, rollback limits and approval chain in writing, and split the work into steps that can each finish inside one window. |
| Need for a staged rehearsal | A rehearsal on a copy of production data exposes parsing, API and plugin failures before they reach users, and it adds time up front. | Build a non-production cluster from a recent backup, run the full sequence, and record every step that needed correction. |
Questions buyers ask before upgrading a Graylog cluster
What drives the cost of upgrading a multi-node Graylog cluster?
The main cost drivers are the number of Graylog, MongoDB and Data Node or OpenSearch nodes, how many versions you cross, and how much of your configuration depends on APIs, plugins and parsing rules that change between releases. Each upgrade step adds planning, backup verification, test runs and rollback preparation. Cost is one-time for the upgrade itself, while any support retainer that follows recurs. Ask for a quote that lists each node group, each version step, the backup and rollback approach, the test scope and who performs each task.
Can our own team upgrade a Graylog cluster without a partner?
Yes, many teams do, provided they have someone who can read the Graylog upgrade documentation, operate MongoDB and OpenSearch or Data Node, and test their own searches, dashboards, event definitions and inputs after each step. The usual gap is not the package commands but the verification: confirming every node runs the same version, the journal drains, and automation built on the API still works. A partner can plan the sequence, run the work in your environment and document the evidence, which suits teams without spare capacity during a change window.
What does the upgrade need from our staff and environment?
Plan for access to every Graylog, MongoDB, Data Node or OpenSearch host, a load balancer you can drain nodes from, and a staging copy of the cluster for rehearsal. You also need a named owner for log sources and dashboards who can confirm results, and someone who can approve a change window. Confirm backup storage is separate from the cluster, has room for the full data set, and that restores have been tested. Also check which dependencies, such as Java or operating system packages, your version requires.
How long does a multi-node Graylog upgrade take?
No fixed figure is given here because duration depends on the versions being crossed, cluster size, data volume, the number of plugins and custom integrations, and how long backups and journal drains take in your environment. A scoped plan breaks the work into node groups and version steps and shows which steps can be rehearsed in advance. Ask for a written timeline that lists each step, its entry and exit checks, and the change windows it requires, and compare it with the Graylog upgrade documentation for your target release.
Do inputs stop while we upgrade Graylog?
Inputs can keep receiving data during a rolling upgrade if the cluster has enough nodes to carry the load while one node at a time restarts, and if the message journal holds incoming messages during the restart. Graylog's journal buffers messages on disk, so the key checks are journal size relative to daily ingest, the time each node is offline, and whether senders retry on connection loss. Some steps, such as schema or backend changes, may need a planned pause. Confirm the exact behavior for your target release before the change window.
How does Graylog licensing change the upgrade scope?
Graylog Open is licensed under the Server Side Public License version 1 (SSPL-1.0), which is not an OSI-approved open source license, while Graylog Enterprise and Graylog Security are commercial editions. According to the Graylog pricing page, Enterprise starts at 15,000 US dollars per year and Security at 18,000 US dollars per year, each with a minimum of 10 GB per day or 100 Graylog Compute Units, and licensing is based on processed data with no per-user or per-device fees. If you use Enterprise or Security features such as the data lake, correlation engine or SIEM content, the upgrade must cover those components and their compatibility. Confirm your edition and feature list before writing the scope.
Should we upgrade to the latest Graylog release or a step at a time?
The answer depends on your current version and what the release notes and compatibility matrix require between your version and the target. Crossing several versions at once can hide breaking changes in APIs, parsing or database prerequisites, so each step may need its own test pass. Ask for a written plan that names the intermediate versions, the MongoDB and OpenSearch or Data Node requirements at each, and the checks that must pass before the next step starts.
How DeployOpen scopes, delivers and supports a Graylog upgrade
DeployOpen plans a multi-node Graylog upgrade as a written, fixed-scope engagement, starting from your current versions and the documented prerequisites for your target release. The work runs inside your own infrastructure, with backups, staged node order and journal checks agreed before any change is made.
How we scope
- Inventory current Graylog, MongoDB, Data Node or OpenSearch, and Java versions across every node.
- Map the target release's documented breaking changes against your inputs, pipelines, API clients and plugins.
- Agree in writing the node order, rollback points, maintenance windows and acceptance checks before work starts.
How we build
- Rehearse the upgrade sequence in a non-production copy of the cluster before touching production nodes.
- Confirm backups of Graylog, MongoDB and Data Node or OpenSearch data are restorable before the first step.
- Upgrade each tier in order, confirm every node reports the same version, and watch journal depth between steps.
How we hand over
- Deliver a runbook listing each step, its verification command, and the rollback procedure for that step.
- Document the final version state, changed configuration keys, and any API or parsing changes your teams must act on.
- Walk your operations staff through post-upgrade health checks and confirm inputs are flowing before closing the engagement.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer after the fixed-scope upgrade is complete.
- Plan the next minor release step with the same staged method, including the stepwise checks your version path requires.
- Confirm with your team which support terms, response expectations and maintenance windows apply before signing a retainer.
