Why the Graylog 6 to 7 upgrade needs a plan before the first package change
A running Graylog 6.x stack that ingests production logs and feeds alerts, dashboards and automation is not a routine package bump. The move to Graylog 7 is a planned major-version change with runtime, database and API prerequisites that must be met before any server is touched. Teams that treat it as an apt or yum upgrade tend to discover the blockers mid-change, when inputs are backing up and the cluster is half on each version.
The Graylog 7.0 upgrade notes set the first gates. Graylog requires Java 21 on every server node, and MongoDB must be at least 7.0. MongoDB cannot jump straight to the target release: it must be upgraded one release at a time, so the database plan is a sequence of its own, with a backup and a health check between steps. The notes also allow skipping the preflight check with skip_preflight_checks = true, but they do not recommend it, and a clean preflight run should be part of the change record. Confirm the current Java and MongoDB versions on each node before scheduling the window, because a node that fails a prerequisite can block the whole cluster.
The current Graylog documentation covers version 7.2, so the team should first confirm which 7.x release it is targeting and read the upgrade notes for that release, not only the 7.0 notes. Check the Graylog 7.0 upgrade notes against your own inventory of automation, since the API changes in that release affect scripts and integrations, not just the server. Record the target version, the Java and MongoDB baselines and the owner of each prerequisite before the first package change.
Which Graylog 7.0 changes affect your deployment
This table maps each change in the Graylog 7.0 upgrade notes to what it affects and what your team must do before or during the upgrade. Read it against your current Graylog 6.x setup: rows marked by a check or cross are not used here, so focus on the action column for any change that touches your servers, scripts or API clients. The main takeaway is that the API and runtime changes break things silently if nobody inventories them first.
| Change in 7.0 | What it affects | Action needed |
|---|---|---|
| Java 21 runtime | Graylog server nodes and any host where the Graylog server runs | Confirm every Graylog node has Java 21 installed and that the service starts on it in a test environment before upgrading production. |
| MongoDB 7.0 minimum | Configuration and metadata database used by all Graylog nodes | Check your current MongoDB version. If it is below 7.0, plan the MongoDB upgrade before the Graylog upgrade. |
| MongoDB upgraded one release at a time | Replica set members and the upgrade sequence | Map each version step, take a backup before each step, and confirm the replica set is healthy between steps. |
| skip_preflight_checks = true | Upgrade gate on the Graylog server configuration | Leave the preflight check enabled. The upgrade notes say skipping it is possible but not recommended, so treat any skip as a documented exception. |
| Only admins can create new API tokens | Users and service accounts that create tokens for automation | List every script and integration that creates tokens, and move token creation to an admin-owned process. |
| New API tokens expire after 30 days by default | Long-running scripts, monitoring and CI jobs that use API tokens | Plan token rotation or an explicit expiry setting for each automation, so jobs do not fail on an expired token. |
| Entity creation APIs take a CreateEntityRequest parameter | Automation that creates streams, dashboards, event definitions, notifications and other entities | Update each client to send the new request structure and test every creation call in a non-production environment. Existing clients break until updated. |
| Data Warehouse renamed Data Lake | API endpoint paths, permissions and MongoDB collection names | Update endpoint paths in scripts, review role permissions that reference the old name, and check any backup or migration tooling that touches the renamed collections. |
| Kafka broker minimum version | Deployments that use Kafka as a message source or buffer | Confirm the broker version against the Graylog compatibility matrix for 7.0 before upgrading. Do not rely on a version range from memory. |
| OpenSearch 1.x deprecated, removal in Graylog 8.0 | Log storage backends still running OpenSearch 1.x | Confirm your OpenSearch version against the compatibility matrix. Plan a move to a supported version now, since the upgrade notes say 1.x removal is planned for Graylog 8.0. |
What to inventory and back up before touching Graylog 7
Graylog 7.0 changes the API contract, the runtime and the database floor at the same time, so a failed upgrade is hard to roll back cleanly. The six items below give you a restore point, a list of what will break, and a test run that proves the backend can carry the new release before production changes.
Full MongoDB and configuration backup
MongoDB holds Graylog configuration, users, streams, dashboards, event definitions and other entities, so it is the restore point for everything except indexed log data. Take a consistent MongoDB backup and copy the server configuration file, typically server.conf, from every Graylog node. Store both off the cluster and confirm a restore works on a scratch host. Be aware that a database that has already been moved to a newer MongoDB version may not restore to an older one, so keep the pre-upgrade copy until the cutover is verified.
Inventory of API clients and scripts
Graylog 7.0 changes entity creation APIs for streams, dashboards, event definitions, notifications and other entities so that they take a CreateEntityRequest parameter. Existing automation that posts plain entity bodies will fail. List every cron job, CI pipeline, Terraform or Ansible task, SOAR playbook and internal tool that calls these endpoints, record the owner and the request format each one sends, and test each one against a 7.0 staging node before the cutover date.
In-house plugins and token holders
Custom plugins compiled against earlier Graylog releases need review, and the upgrade notes also change API token behavior. Only administrators can create new API tokens in 7.0, and new tokens expire after 30 days by default. Identify which service accounts depend on tokens created by non-admin users, which tokens are long-lived, and which integrations will stop authenticating when a 30-day expiry arrives. Plan a rotation schedule and a named owner for each token.
Data Warehouse reference list
The Data Warehouse feature is renamed Data Lake in 7.0, and the rename covers API endpoint paths, permissions and MongoDB collection names. Search your dashboards, saved searches, automation, role definitions and any scripts for the old name and its endpoint paths. Note which roles grant Data Warehouse permissions, because those grants must map to the new permission names. Keep the list with the API inventory so that the same owners can update both.
Test environment that mirrors backend versions
Build a non-production cluster that matches production on the components that Graylog 7.0 changes: Java 21 on the Graylog nodes, MongoDB at or above the 7.0 minimum, and the search backend version that your Graylog release supports. Restore the production backup into it and run the upgrade there first. Confirm that dashboards load, event definitions evaluate, inputs ingest and the API inventory scripts succeed. A test that uses older backend versions will not prove the upgrade path.
Message journal drain check
Graylog buffers incoming messages in its message journal before writing them to the search backend. If the journal still holds unprocessed messages when you stop a node for the upgrade, that backlog must be replayed afterward, and a large backlog delays the cutover. Before the change window, confirm on each node that the journal is draining and that its utilization is low. Record the starting value so that you can confirm after restart that the journal returns to normal.
How to sequence the Graylog 6 to 7 upgrade with checks and rollback points
The sequence turns a set of breaking changes into an ordered run of checks, with a named rollback point after each stage so the team knows what to restore if a step fails.
Confirm Java 21 and host readiness
The platform team confirms every Graylog server node runs Java 21 and that each host meets the Graylog 7.0 requirements for packages, disk and network before anything changes. Graylog 7.0 requires Java 21 and at least MongoDB 7.0, so the team should check both versions on every node, not only the first. Rollback point: nothing has changed yet, so the restore step is simply to keep the current packages and configuration files. The step is done when a written inventory lists the Java and MongoDB versions per host and each gap has an owner.
Take a full backup before any change
The operator takes a verified backup of the MongoDB configuration database, the Graylog configuration files including the server configuration, and the OpenSearch or Data Node indices or snapshot repository. The backup must be tested by restoring it to a non-production copy or by confirming the restore procedure with the team that owns the data layer. Rollback point: this backup is the baseline every later step returns to. The step is done when the restore has been demonstrated, not just the backup job reported success.
Run the preflight check and resolve findings
The operator runs the Graylog preflight check and works through every finding before upgrading, treating each as a blocker until it is fixed or formally accepted. Graylog documents that skipping the check with skip_preflight_checks set to true is possible but not recommended, because the findings are the cheapest place to catch configuration and version gaps. Rollback point: the check changes nothing, so no restore is needed. The step is done when the check reports no open findings and the output is saved with the change record.
Upgrade MongoDB one release at a time
The database owner moves MongoDB through each intermediate release in order to reach at least 7.0, and does not jump versions. After each release the owner checks replica set health, that all members have rejoined and that Graylog can read and write its configuration. Rollback point: before each MongoDB step, take a fresh backup and record the current version, so a failed step can be reversed to the last stable release. The step is done when the replica set reports healthy members at the target version and Graylog starts cleanly against it.
Confirm OpenSearch or Data Node support
The data layer owner checks the Graylog compatibility matrix against the search backend in use. Graylog 7.0 to 7.2 supports OpenSearch from 1.1.x up to 3.7.x, while use of OpenSearch 1.x is deprecated since Graylog 7.0 and will be removed in Graylog 8.0, so any cluster on 1.x needs a dated plan to move to a supported version or to Graylog Data Node. Rollback point: the search layer is untouched at this stage, so the restore is the snapshot taken earlier. The step is done when the team has a written decision on the backend version and its migration owner.
Upgrade Graylog server nodes with leader settings
The operator upgrades Graylog server nodes one at a time while handling the leader setting per node: the node that runs as leader is set to is_leader true, and follower nodes are set to is_leader false as the multi-node guide describes. Each node is checked for a clean start, a drained message journal and a healthy connection to MongoDB and the search backend before the next node is touched. Rollback point: restore the previous package and configuration on the node that failed and keep the remaining nodes on the old version. The step is done when all nodes report the same version and the journal is draining.
Verify inputs, searches, alerts and API clients
The operations team confirms inputs are receiving messages, saved searches and dashboards return results, and event definitions evaluate and send notifications to their channels. It also tests every API client and script, since the 7.0 entity creation calls now take a CreateEntityRequest parameter, new tokens are admin-only and expire after 30 days by default, and the Data Warehouse feature is renamed Data Lake in endpoints, permissions and collection names. Rollback point: if a critical integration fails and cannot be fixed, restore the backup from the earlier step and reopen the change. The step is done when each check has a recorded result and the owners of automation sign off.
How the 7.0 API token and entity creation changes break automation
Three changes in Graylog 7.0 can stop scripts and integrations that ran cleanly on 6.x, and they fail in different ways. Only admins can create new API tokens, so any pipeline that mints a token with a non-admin user account will fail at creation rather than at runtime. New tokens expire after 30 days by default, so a token created during the upgrade will stop working about a month later, often on a weekend or during an unrelated change window. The entity creation APIs for streams, dashboards, event definitions, notifications and other entities now take a CreateEntityRequest parameter, which means a request body that worked on 6.x is rejected by 7.0 until the client is rewritten to send the new structure. The first two changes are about identity and credentials, the third is about request shape, and each needs its own fix.
Start by finding the clients. Search your configuration management, CI pipelines, cron jobs, ticketing and SOAR platforms, and any in-house plugins for calls to the entity creation endpoints and for token use. Check the access logs of the Graylog server nodes for requests to those paths over a representative period, because a quarterly reporting script can be easy to miss in a list of repositories. For each client, record which user or token it authenticates with, whether that identity is an admin, when its token expires under the 30-day default, and which team owns the code. Confirm the exact token and entity behavior against the Graylog 7.0 upgrade notes and your own staging test before you plan the cutover, since the notes are the reference for what changed.
Plan rotation as a scheduled task, not an emergency. Issue replacement tokens from an admin identity that is assigned to the client, store them in your secrets manager, and update each client in a test environment first. Set a rotation date for every token that lands before the 30-day expiry window your team can comfortably cover, and assign a named owner to each client who is responsible for the request shape changes, the token renewal and the decommissioning of old credentials. Clients without an owner should be retired or handed off before the production upgrade. Give owners a rollback path for scripts that cannot be fixed in time, such as keeping a 6.x-compatible instance for a short period, and agree on that period in writing with the people who run the upgrade.
What makes a Graylog 7 upgrade take longer
The table lists the factors that most change how much planning, testing and rework a Graylog 6 to 7 upgrade needs, and which direction each one pushes the effort. Use it to size your own environment before asking for a written scope, since the drivers often stack.
| Driver | Why it adds effort | How to keep it down |
|---|---|---|
| Node count and topology | A multi-node cluster needs ordered upgrades, all nodes on the same version before the next step, and inputs kept flowing through the journal | Confirm the topology early and plan a maintenance window per tier |
| MongoDB size and version gap | Starting below MongoDB 7.0 means stepwise upgrades one release at a time, each needing checks and a restore point | Confirm your current MongoDB version and replica set health before scheduling |
| Index data volume in OpenSearch or Data Node | Larger indices lengthen backup, restore and cluster health checks before and after the upgrade | Confirm backup capacity and index counts with your storage team |
| OpenSearch 1.x backends | Graylog 7.0 deprecates OpenSearch 1.x, so a backend migration to a supported version or Data Node joins the upgrade scope | Confirm your backend version and whether a separate migration project is needed |
| Data Warehouse objects | Objects using the Data Warehouse name need review for the rename to Data Lake, covering API paths, permissions and MongoDB collection names | Inventory affected objects and scripts before the test cycle |
| Number of API clients and scripts | Automation that creates streams, dashboards, event definitions or notifications must adapt to the CreateEntityRequest structure and new token rules | Inventory every client, its owner and the tokens it uses |
| Custom plugins | In-house plugins must be rebuilt or reviewed against the 7.0 changes, and each one needs its own test pass | List plugins and confirm which maintainers can rebuild them |
| Kafka dependencies | Deployments that depend on Kafka brokers must confirm the 2.1 minimum and any connected pipelines before cutover | Confirm broker versions and client compatibility in advance |
| Teams that test dashboards and alerts | Each team that owns dashboards, event definitions or notifications needs time to verify results after the upgrade | Agree test owners and acceptance steps in the written plan |
Questions teams ask before upgrading Graylog to 7.0
What drives the cost of a Graylog 6 to 7 upgrade?
The cost depends on how much of your environment the upgrade touches, not on the version number alone. The main drivers are the number of Graylog, MongoDB and Data Node or OpenSearch nodes, how many scripts and API clients call Graylog, how many custom plugins need rebuilding, and how much testing your organization requires before cutover. Each of these adds planning, build and verification hours. Ask for a written scope that lists each component, the environments covered (test and production), and which items are one-time work versus recurring support. DeployOpen does not publish prices, so a quote follows from that scope. Graylog's own pricing page lists Enterprise and Security license fees, but those are separate from upgrade services and only apply if you buy those editions.
How long does a Graylog 7.0 upgrade take?
Duration depends on the size of the cluster, the number of prerequisite upgrades, and how much API and parsing work the team has to fix before go-live. The Graylog 7.0 notes require Java 21, a MongoDB 7.0 minimum, and MongoDB upgrades one release at a time, so a deployment on an older MongoDB needs several sequential steps, each with its own backup and check. Client-side fixes for the CreateEntityRequest change and the 30-day API token default also extend the schedule. Your test window matters as much as the build. Ask for a timeline in the written scope that separates preparation, staging, production cutover and post-upgrade checks, and confirm it against your change calendar.
What must our team provide before the upgrade starts?
Plan to provide the following before work begins:
- Administrative access to Graylog, MongoDB, Data Node or OpenSearch, and the hosts or containers they run on, in the environments you control.
- Current backups of MongoDB and the search backend, with a tested restore procedure.
- An inventory of every API client, script, automation and custom plugin that creates entities, since the 7.0 entity creation APIs take a CreateEntityRequest parameter and break existing clients.
- A list of users or service accounts that rely on API tokens, because only admins can create new tokens and new tokens expire after 30 days by default.
- A staging environment and a defined test window with named owners who can confirm log flow, searches and alerts.
Confirm each item with your own team and record it in the scope before the schedule is fixed.
Can our in-house team upgrade Graylog to 7.0 without a partner?
Yes, many teams do this internally, provided they have Linux, MongoDB and search-backend administration skills and time for staged testing. The work is documented, but it has several sequential gates: prerequisite runtime and database versions, the preflight check, MongoDB stepwise upgrades, Graylog node upgrades and backend upgrades. Teams most often underestimate the API inventory and the parsing or automation fixes that follow the Data Warehouse to Data Lake rename and the entity API change. Skipping preflight checks with skip_preflight_checks = true is possible but not recommended. Decide based on whether your staff can complete the staged work, test every integration and run a rollback plan. A fixed-scope engagement with DeployOpen covers the planning, implementation and documentation in your own infrastructure.
How does the OpenSearch 1.x deprecation affect the timing of our upgrade?
Graylog deprecated use of OpenSearch 1.x starting with Graylog 7.0 and plans to remove that support in Graylog 8.0, so staying on 1.x means you will need to move to a supported backend before the next major release. The compatibility matrix says Graylog 7.0 to 7.2 support OpenSearch from 1.1.x up to 3.7.x, and Graylog Security requires OpenSearch 2.0 or later. Graylog recommends Data Node as the search backend. Because the search backend upgrade interacts with the Graylog node upgrade order, decide the backend path during planning rather than after the Graylog binaries are updated. Confirm the exact target version with the compatibility matrix and your edition before scheduling.
Do we need a support retainer after the 7.0 cutover?
A retainer is optional. Some teams close the project after cutover and handle routine operations themselves, while others want ongoing help with patching, the 7.1 and 7.2 minor upgrades, backups and test runs. Consider how many people on your team know the new MongoDB, Data Node and API changes, how often you expect to upgrade, and how quickly you need help if a log pipeline stops. DeployOpen offers ongoing support and upgrades as retainers, and these are scoped in writing separately from the initial upgrade. Ask for the retainer terms, response expectations and included activities in the quote so you can compare them with your internal capacity.
How DeployOpen scopes a Graylog upgrade before any change is made
DeployOpen starts every Graylog 6 to 7 upgrade with a written, fixed scope, and no production change is made until that scope is agreed. The scope begins with an environment inventory: every Graylog server node, the MongoDB version and topology, the Data Node or self-managed OpenSearch backend (including any OpenSearch 1.x still in use, which is deprecated since Graylog 7.0), the Kafka broker version if the journal or integrations depend on it, the operating system and Java runtime on each host, and whether the installation uses packages or Docker Compose. Each item is compared against the prerequisites in the Graylog 7.0 upgrade notes, so gaps such as the Java 21 requirement or the MongoDB 7.0 minimum are known before the plan is written.
The scope then covers API and plugin review. DeployOpen inventories scripts, automation and custom plugins that call the entity creation APIs, because those calls now take a CreateEntityRequest parameter and break existing clients. It also records how API tokens are issued and used, since only admins can create new tokens and new tokens expire after 30 days by default. Any reference to a Data Warehouse path, permission or MongoDB collection is listed for the rename to Data Lake. The scope names the rehearsal environment, the upgrade sequence (MongoDB stepwise, then Graylog, then Data Node), the rollback plan and the post-upgrade checks, such as journal drain and parsing validation. Ask for the written scope to name who signs off each step.
Quotes follow from that written scope. DeployOpen does not publish a price list, so the quote reflects the systems, integrations and environments the scope covers. When you request one, ask the provider to itemize the environment inventory, the rehearsal work, the API and plugin changes, the rollback plan and the validation steps as separate lines, and to state which items are one-time and which recur. Confirm with the vendor, in your own environment, whether skip_preflight_checks will be used, since the upgrade notes advise against it.
How DeployOpen works on this
DeployOpen plans, implements and documents Graylog upgrades inside your own infrastructure, starting with an inventory of your 6.x version, runtime, MongoDB, Kafka and API clients. Work is agreed as a fixed-scope engagement, so the stepwise MongoDB path, the 7.0 API changes and the Data Lake rename are settled in writing before the upgrade window opens.
How we scope
- Inventory your current Graylog 6.x version, Java runtime, MongoDB release and Data Node or OpenSearch backend.
- Map every script, dashboard and integration that calls the entity creation APIs and needs a CreateEntityRequest update.
- Agree in writing the upgrade path, rollback points, preflight check handling and the environments covered.
How we build
- Prepare Java 21 hosts, MongoDB stepwise upgrades and Kafka broker versions in a staging copy of your cluster first.
- Update API clients, token handling for the new 30-day default and Data Lake references, then test them against staging.
- Run the 7.0 upgrade in staging, check inputs, parsing and search results, and record every deviation before production.
How we hand over
- Deliver a written runbook with backup steps, node order, verification checks and rollback procedure for your environment.
- Document the changed API calls, renamed permissions and collection names so your team can maintain them after the upgrade.
- Walk your operators through the post-upgrade checks, including journal drain and dashboard validation, before we close the engagement.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after the engagement closes.
- Ask your DeployOpen contact to confirm the scope of any retainer, response expectations and the versions it covers.
- Plan the next Graylog 7.x minor release as a separate scoped piece of work, with its own compatibility check.
