Why upgrading a NiFi cluster needs one planned change window
A cluster upgrade is a coordinated change in which every node ends on the same NiFi version, queues are drained before each node stops, and configuration is carried over from the old installation to the new one. Treating it as a rolling series of independent node installs is the mistake that causes most cluster upgrade incidents, because nodes running different versions cannot be left to share a flow. Plan one change window with a named owner, a rollback point and a fixed node restart order, even when the work is spread over several sessions.
The supported path into NiFi 2 runs through the migration guidance. The project requires upgrading to NiFi 1.27.0 before moving to 2.0.0, and changing the flow configuration file from flow.xml.gz to flow.json.gz. The downloads page describes NiFi 1.28 as the last minor release of the version 1 series, and lists December 8, 2024 as the end-of-support date for 1.28.1. Clusters still on 1.x are therefore running without further maintenance from the project, which makes the move a security and supportability question as well as a feature decision.
Before scheduling the window, confirm the exact current version on every node, not only on the first node you log into, and confirm that the flow is in the format the migration guidance expects. The [NiFi System Administrator's Guide](https://nifi.apache.org/nifi-docs/administration-guide.html) sets out the upgrade steps this page follows. Ask your implementation partner or internal team to write down which custom NARs, third-party drivers and configuration overrides each node holds, since those decide how much of the window is spent on preparation rather than on the restart itself.
What changes in a NiFi cluster upgrade and what each change requires
This table lists the changes that affect a NiFi cluster when moving from 1.x to 2.x and shows what each one requires from the team running the upgrade. Read each row as a pre-upgrade task: the impact column explains what breaks if it is skipped, and the action column names the work to finish before any node restarts. Rows that need deeper steps point to the follow-on pages in this group.
| Change | Impact | Action needed |
|---|---|---|
| Flow configuration file moves from flow.xml.gz to flow.json.gz | NiFi 2 reads flow.json.gz, so a 1.x flow.xml.gz is not loaded as-is on every node. | Follow the migration guidance to convert the flow configuration before starting any upgraded node, and keep a backup of the original file. |
| Variable registry scope removed in 2.0, replaced by ENVIRONMENT | Flows or parameters that reference the variable registry scope will not resolve after the upgrade. | Find variable references in flows and move them to parameter contexts; see the migration of variables to parameter contexts page. |
| Distributed map cache components renamed | Processors and controller services that point to the old component names will fail to find them on NiFi 2. | Inventory map cache usage and update component references per the migration guidance before cutover. |
| Java 21 as minimum runtime | Nodes running an older JDK cannot start the new version, so a partially upgraded cluster can halt. | Install Java 21 on every node and container image, and confirm JVM arguments and third-party JDBC drivers before the first restart. |
| Python 3.10, 3.11 or 3.12 for optional Python processors (beta) | Python-based processors need a supported interpreter on each node. The feature is documented as beta. | Install a supported Python version on every node if Python processors are used, and test them in a non-production cluster first. |
| Kerberos provider deprecated | Kerberos SPNEGO login is deprecated, so existing browser login and service accounts need a new authentication path. | Choose a replacement login provider and plan how Kerberos-authenticated accounts and processor credentials will be handled. |
| NiFi Registry deprecated for removal in NiFi 3.0 | Flows versioned in NiFi Registry will need a new home before NiFi 3.0 removes the component. | Plan the move to a Git-based flow registry client; the Git-based registry migration page covers the steps. |
| Cluster coordination through ZooKeeper, or Kubernetes ConfigMaps or Leases | The coordination option must be set consistently on all nodes, and a mismatch prevents the cluster from forming. | Confirm which option the cluster uses, update its configuration on every node, and verify coordination is healthy before admitting nodes. |
Why every node must run the same version before the cluster rejoins
Mixed versions in one NiFi cluster are not a state to plan for. Nodes in a cluster share flow state, coordinate through the cluster's coordination layer, and must agree on the flow definition they run, so a cluster with nodes on different versions is a transitional condition you move through quickly, not a steady state you operate. The exact node-compatibility rules for your target release, including whether any mixed-version window is tolerated during a rolling change and for how long, are set out in that release's upgrade notes. Confirm them there before you schedule the work, because the supplied facts for this page do not state them and the answer determines how much of the upgrade you can do one node at a time. A rolling upgrade takes one node out of the cluster, upgrades it, starts it and waits for it to rejoin before touching the next. The cluster keeps serving flows on the remaining nodes throughout, but every node you have not yet reached still runs the old version while the upgraded ones run the new one. A stop-everything upgrade shuts all nodes down, installs the new version on each, and starts them together. It is simpler to reason about and avoids the mixed window entirely, but flows stop for the whole duration. Choosing between them is a business decision about downtime and a technical decision about what the release notes permit. During the window, the coordination layer decides which node is the cluster coordinator and which is primary, tracks which nodes are connected, and holds the state that lets a rejoining node pick up the current flow. With an embedded or external ZooKeeper ensemble, a node that restarts registers again and must be accepted by the coordinator. On Kubernetes, ConfigMaps or Leases play the same role for state and leader election. Check the coordination layer's health before each node restart, and confirm with your target release notes how a node on the new version is handled when it joins a cluster still holding old-version members.
What to prepare before touching the first node
A NiFi cluster upgrade fails most often in preparation, not during the restart. The cards below cover the backups, inventories and assessments that must exist before any node is stopped, so that a failed step can be reversed and the team knows exactly what the new version must accept.
Full backup of flows and configuration
Back up the flow definition file, the configuration directory, the repositories and the certificates and keystores before shutdown. Confirm that you can restore each piece on a spare host, because a backup you have never restored is only an assumption. Record the NiFi version and the cluster node list alongside the copy so the rollback target is unambiguous.
Inventory of custom and modified NARs
List every custom processor bundle and every NAR you have modified, including the source version and the build that produced it. Each entry needs a rebuild or replacement decision for NiFi 2, because NARs built for 1.x are not carried forward unchanged. Keep the preserved copies so the new installation can receive them during the upgrade.
Sensitive properties key and algorithm
Record the sensitive properties key and the value of nifi.sensitive.props.algorithm currently in use, and store the key in your secrets vault with restricted access. Confirm the algorithm is one that the target release accepts before the upgrade starts. Without the key, encrypted values in the flow and configuration cannot be read by the new nodes.
Queue and activity assessment
Identify which queues hold data, which processors are running and which remote transfers are active. Plan to drain or clear the queues you can, and decide how to handle the rest, such as holding inbound sources or accepting replay from upstream. Record the expected queue depths so you can confirm after restart that no data was lost.
Staging cluster with production flows
Build a staging cluster on the target version and load a copy of the production flow definition, parameter contexts and custom NARs. Run the upgrade steps there first and check that every processor starts, every controller service enables and every connection to external systems works. Use it to measure how long the procedure takes on your hardware.
Kerberos-authenticated components and accounts
List every component, controller service and service account that authenticates with Kerberos, including the SPNEGO login, keytabs and processor credentials. Decide the replacement for each before the upgrade, since Kerberos SPNEGO login is deprecated. Confirm which accounts need new credentials and who holds them, so the cutover does not stop on an expired keytab.
The order to upgrade and restart NiFi nodes
This sequence moves a NiFi cluster from one version to another without losing queued data, custom code or cluster coordination, and it leaves a checkpoint after every node so a failed step can be reversed before the next node is touched. Confirm each step against the Administrator's Guide and the target release notes before you run it in your environment.
Confirm the supported upgrade path and target version
Before any change, the platform owner confirms the current version, the target version and whether the move is a direct upgrade or needs an intermediate release. The NiFi migration guidance sets required stops for some paths, such as moving from 1.x to 2.x, so check the path against the migration guidance and the target release notes. The output is a written version record for every node, signed off by the platform owner. Do not start draining queues until every node reports the same current version and the path is confirmed.
Clear activity and drain queues
The cluster operator stops new data from entering the flow where the flow allows it, then lets processors work through their queues until connections are empty or the remaining data is understood and accepted. Record the queue depth on each connection and the provenance state before you proceed, because data still in flight at shutdown is the most common source of duplicates or gaps after an upgrade. The step is complete when the queue report shows no data that must be processed by the old version and the team has captured a backup of the flow definition. Confirm the drain approach for your own flows with the Administrator's Guide.
Shut down the existing NiFi nodes
Stop each node in the order your cluster runbook defines, and confirm that the node has left the cluster before stopping the next one. Keep the existing installation directory, repositories and configuration files in place rather than deleting them, so the node can be restored quickly. The output is a stopped process on each node, with no active NiFi Java process left running. If a node does not stop cleanly, investigate before forcing the shutdown, because a forced stop can leave repositories inconsistent.
Preserve custom processors and modified NARs
Copy every custom processor NAR, every modified NAR and any third-party driver or library that the flows depend on into a version-controlled location, and record the source and build of each file. Custom components built for an earlier release often need rebuilding for the target release, so keep the original artifacts as the rollback copy and plan the rebuild as a separate task. The step is complete when the team can list each custom NAR, its build origin and its location, and when the rollback copy is verified on a separate host or in backup storage.
Install the new version on the first node
The platform engineer installs the target NiFi release on the first node into a new directory, leaving the old installation untouched, and places the preserved custom NARs in the new lib location only after confirming they are compatible with the target release. Install the same release on every node, because the cluster does not run with mixed versions. The output is a confirmed version string on the first node and a matching checksum record for the distribution archive. Do not move on to the second node until the first node has passed the checkpoints below.
Update configuration files and the sensitive properties key
Update the configuration files on the first node, including the properties file, the cluster and state settings, the bootstrap JVM arguments and the sensitive properties algorithm and key. Where the target release changes the flow configuration file format, run the documented conversion before the first start, and keep the original flow file in backup. Confirm the sensitive properties key is the same one used to encrypt the existing flow, because a changed key prevents protected values from being read. The step is complete when the configuration validates and the node starts with the same sensitive properties key as the rest of the cluster.
Start the first upgraded node and check cluster health
Start the first upgraded node and check that it loads the flow, joins the cluster and syncs the flow with the cluster state. Verify cluster membership in the UI or through the administrative API, confirm the flow matches the expected version, and check queue health and processor status before you change any other node. Record the results as the checkpoint for the node. If the node fails to join or the flow does not sync, stop, and roll back this node to the preserved installation using the saved configuration and backup, which keeps the rest of the cluster on the old version.
Repeat the sequence for each remaining node
Apply the same shutdown, preservation, installation, configuration and start steps to each remaining node in the order the Administrator's Guide and the target release notes specify, and check membership, flow sync and queue health after every node. Keep a rollback point for each node, so that a failure on one node can be reversed without touching nodes already verified. The step is complete when every node reports the target version, joins the cluster, syncs the flow and shows healthy queues. Confirm the exact node restart sequence with the Administrator's Guide and the release notes for your target version before you begin.
How the approach changes for ZooKeeper and Kubernetes clusters
With embedded ZooKeeper, each NiFi node runs its own coordination member inside the NiFi process, so the coordination layer upgrades along with the nodes. The cluster's election and shared state live on the nodes themselves, which means every step of a rolling upgrade must keep enough members running to hold a quorum. Removing or replacing a node changes the membership of that quorum as well as the NiFi cluster.
- Quorum during restarts: Restart one node at a time and confirm the cluster shows the expected number of connected nodes before moving on. In a three-node cluster, stopping two nodes at once removes the majority that coordination needs.
- Node replacement: A new node must run the target version before it joins, and the retired node must leave the cluster before its identity or hostname is reused.
- Leader handover: When the node acting as cluster coordinator restarts, another node takes over. Expect a short period of coordination activity and wait for the new coordinator to stabilize before starting the next restart.
- Rollback: Coordination data moves forward with the upgraded nodes, so returning a single node to the old version is only safe before flow or configuration formats change. Keep the previous installation and flow files for a full restore.
Confirm the embedded ZooKeeper startup setting, port layout and quorum rules for your target version in the administration guide before you schedule the restarts.
With an external ZooKeeper ensemble, coordination runs outside the NiFi nodes, so the ensemble has its own lifecycle, upgrade path and failure domain. NiFi nodes connect to it as clients. This simplifies node replacement, but it adds a dependency that must be healthy, supported and reachable from every node for the whole upgrade window.
- Ensemble health first: Confirm the ensemble has a leader and is healthy before stopping any NiFi node. Upgrade the ensemble on its own schedule so it does not change during a NiFi cutover window.
- Connection string consistency: Every node must point to the same connection string, set through the
nifi.zookeeper.connect.stringkey innifi.properties. Confirm the key name, along with any chroot or ACL settings, in the guide for your target version. - Node replacement: New nodes join without changes to the ensemble, but their identities and state directories must match what the cluster expects. Retire the old node in NiFi before reusing its address.
- Leader handover: Coordinator election happens through the ensemble, so the handover is independent of the NiFi node restart order. Observe the behavior in your own test cluster before relying on it in production.
- Rollback: Rolling back NiFi nodes does not roll back the ensemble. Take ensemble data snapshots before the cutover so that both layers can be restored independently.
Ask whether your ensemble version is supported by the NiFi release you are targeting, and confirm the answer in the administration guide.
On Kubernetes, NiFi can store cluster state and perform leader election with ConfigMaps or Leases, so coordination depends on the Kubernetes API and RBAC permissions rather than on a ZooKeeper ensemble. The workload definition, such as a StatefulSet or an operator, usually controls the upgrade, so order, replacement and rollback follow its rules as well as NiFi's.
- Ordering through the controller: Your workload controller decides which pod restarts first and how many at a time. Review its update strategy for your deployment method and avoid unattended rolling updates on a live flow.
- Node replacement: A replaced pod keeps or receives an identity depending on how the workload is defined. Check that the replacement reattaches the persistent volumes that hold the repositories and that the stale member leaves the cluster.
- Leader handover: Election uses the Lease or ConfigMap objects. Confirm that the service account's RBAC role can still read and update them after the upgrade, because a missing permission can block election.
- Rollback: Reverting the image does not revert repository formats or flow files already written by the new version. Snapshot the persistent volumes and record the previous image tag before you start.
Confirm the Kubernetes coordination settings, required RBAC rules and supported Kubernetes versions in the NiFi System Administrator's Guide for your target release.
How to test the upgrade and roll back safely
Rehearse the full cluster upgrade in a staging cluster that mirrors production before touching production nodes. Use a copy of the production flow.xml.gz or converted flow file, the same custom and modified NARs, the same nifi.properties layout and representative data volumes, including queued FlowFiles and at least one flow that uses each external connection. A staging run on an empty canvas proves little, because most failures in this upgrade come from processors that validate only when real configuration, parameter contexts and credentials are loaded. Time each step of the rehearsal and record what you had to change, since those changes become the production runbook.
Before declaring production successful, check four things on every node. Confirm cluster membership: all nodes should show as connected and on the same version, and the coordinator should be able to see every node through ZooKeeper or the Kubernetes state provider you chose. Confirm flow sync, so every node reports the same flow version. Confirm processor validation: stopped processors should report valid, and any invalid component should be traced to a missing NAR, parameter or service rather than assumed to be cosmetic. Finally, confirm that provenance can be queried and that sensitive values such as controller service passwords decrypt. An unreadable sensitive value usually means the nifi.sensitive.props.key or algorithm was not carried over correctly, and a processor will fail only when it next runs.
Rollback depends on what you changed. Keep a full backup of the conf directory, the flow file, the flow and state repositories, the content repository if you need it to replay data, and the previous NiFi installation with its NARs, so you can restart the old version on the same hosts. If you have only converted the flow file format, rolling back means restoring the pre-conversion copy and the old binaries together, and you must confirm that the older version can read that file. Kerberos, parameter context and processor replacement changes are covered on their own pages, so check each one for its own reversal path. Confirm your rollback plan in staging too, because restarting an old version against a converted repository is the step most likely to fail.
What makes a NiFi cluster upgrade take longer
This table lists the factors that stretch a NiFi cluster upgrade and what each one means for your plan. Use the question column as a checklist for scoping a quote or an internal change window. The main takeaway is that node count is rarely the largest driver; custom NARs, removed components and queued data usually decide how much work the upgrade requires.
| Driver | Why it matters | What to ask |
|---|---|---|
| Number of nodes | Every node must run the same version, so each node needs its own drain, stop, install and restart steps, and the cluster must rejoin cleanly after each one. | How many nodes, which coordination method (embedded or external ZooKeeper, or Kubernetes) and whether a staging cluster mirrors production. |
| Custom or modified NARs | Custom processors and changed NARs must be carried across and rebuilt or retested for NiFi 2, which can require code changes and new test runs. | How many custom or modified NARs exist, who owns their source code, and whether they have automated tests. |
| Removed or deprecated components | Flows that use components removed or deprecated in NiFi 2 need replacement or redesign before the cutover, not just a configuration change. | Which processors and controller services the flows use, and whether replacement mappings have been validated in a test environment. |
| Queue volume that must drain | Queued FlowFiles must be drained or cleared before shutdown, and large backlogs extend the window and raise the risk of data loss or duplicates. | Current queue depth per connection, the expected inflow during the window, and the agreed approach for handling data that cannot drain. |
| Python processor use | Optional Python-based processors need a supported Python version and are described as a beta feature, so their behavior must be tested on the new runtime. | Which Python processors are in use, the Python version on each node, and whether their scripts depend on third-party packages. |
| Authentication migration | Moving from Kerberos SPNEGO login or other providers to a supported option changes how users and service accounts sign in, and needs coordinated testing. | Which login providers are configured today, which accounts depend on them, and who approves the switch to the replacement provider. |
| Sensitive properties work | The sensitive properties algorithm and key must be checked and updated consistently across nodes, and an error here can make encrypted values unreadable. | Which algorithm and key handling the current instance uses, where the key is stored, and how a rollback would restore access. |
| Flows referencing variables | Variable registry references must move to parameter contexts and the ENVIRONMENT scope, and each referencing flow must be found and tested. | How many flows reference variables, whether parameter contexts already exist, and which flows are promoted across environments. |
Common questions before upgrading a NiFi cluster
How much does an Apache NiFi cluster upgrade cost?
The cost depends on the written scope, not on a standard rate. The main drivers are the number of nodes, how many flows use custom processors or modified NARs that must be rebuilt or retested, how many components need replacing, and how much of the environment (TLS, authentication, Kubernetes or ZooKeeper coordination) must be checked during the change. Some work is one-time, such as the upgrade itself and any flow rework. Other costs recur, such as patching and version alignment after the upgrade. Ask for a quote that lists each node, each custom artifact, each change to configuration files and the testing expected before and after cutover. DeployOpen does not publish a price list; a quote follows from the agreed scope.
How long does a NiFi cluster upgrade take?
No duration is given without a scope, because the time depends on how many nodes you run, how large the queues and repositories are, how many flows and custom NARs need work, and how much testing your change process requires. Start by inventorying the cluster: NiFi version, node count, custom and modified NARs, flow configuration, sensitive properties settings and any coordination service in use. That inventory is what allows a fixed-scope timeline to be written. Ask any provider to state the assumptions behind its schedule and what would extend it.
What does the upgrade need from our team?
Your team needs to provide access to every node, the current flow definition and configuration files, the list of custom processors and NARs with their source or build records, and a test environment that resembles production. You also need a named owner who can approve the maintenance window, decide whether queued data can be drained or must be processed first, and confirm which people can rotate or hold the sensitive properties key. Finally, someone must confirm the identity provider and certificate details for the target version, since authentication changes often affect the cutover.
Can our in-house team run the NiFi cluster upgrade?
Yes, many teams do, provided they have engineers who understand NiFi clustering, the upgrade steps in the administrator's guide and their own flows. The work is mostly sequential and procedural, but the risk sits in details: preserving custom and modified NARs, clearing activity, updating configuration files, and checking the sensitive properties algorithm and key before the new version starts. Teams without recent NiFi operations experience often benefit from a written runbook, a rehearsal on a copy of the cluster and an independent reviewer. Decide early which parts your team will own after handover.
Is a rolling upgrade of a NiFi cluster possible?
A rolling approach is the usual way to keep a cluster serving flows, because nodes can be taken down and upgraded one at a time while the others continue. Every node must end on the same NiFi version, so a rolling sequence is a transition period, not a state to remain in. Before each node stops, its activity must be cleared and its queues drained or accounted for, and the flow must still run on the remaining nodes. Confirm with your own tests whether your flows, load and coordination setup (embedded or external ZooKeeper, or Kubernetes leases) tolerate that transition. Some major version changes also require intermediate steps, which the migration guidance describes.
What happens to the sensitive properties key during the upgrade?
The sensitive properties key protects encrypted values in your configuration, such as passwords and credentials stored in flow definitions. The administrator's guide lists updating the sensitive properties algorithm and key as a specific upgrade step, so it must be handled deliberately rather than copied over by accident. Confirm which algorithm your current instance uses, follow the documented procedure to set the algorithm and key for the new installation, and back up the key with its custody record. If the key is lost or mismatched, encrypted values cannot be read, so verify decryption on a test node before any production node moves.
How DeployOpen works on this
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, so a NiFi cluster upgrade is scoped against your nodes, flows, custom NARs and configuration before any change is made. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- We inventory every node, the NiFi version on each one, and whether the cluster uses ZooKeeper or Kubernetes for coordination.
- We list custom processors, modified NARs, third-party drivers and the sensitive properties algorithm so each one has an owner and a target.
- The written scope states which nodes, flows and configuration files are covered, plus the test and rollback steps agreed with your team.
How we build
- We rehearse the upgrade on a non-production copy of the cluster, following the order the Administrator's Guide sets for preserving NARs and shutting nodes down.
- We confirm that queues are drained or cleared, then update configuration files and the sensitive properties key in a controlled change.
- We restart nodes in the agreed order and check cluster membership, flow state and component validity after each step.
How we hand over
- You receive an updated runbook covering node order, drain steps, configuration changes and the verification checks used at each stage.
- Documentation records the final versions, preserved NARs, key handling and any open items that your team must confirm in your environment.
- Your operators are walked through the runbook so they can repeat the procedure for later maintenance without us on site.
How we support
- After handover, ongoing support, upgrades and continuous testing are available as a retainer, scoped separately from the upgrade itself.
- Retainer work can cover the next NiFi release, patch rounds and changes to custom code, with the scope agreed in writing each time.
- Ask us to confirm which support terms and response expectations apply to your environment before the retainer is signed.
