The NiFi 2 upgrade has two halves. The first is getting flows ready: components replaced, scripts rewritten, templates retired, variables turned into parameters. The second is moving production onto NiFi 2 without losing data or a weekend. This post is about the second half.
Get to the final 1.x release first
The supported route to NiFi 2 runs through the last 1.x line. Upgrading there first is a normal minor upgrade with a well-trodden procedure, and it buys you two things: deprecation warnings that name the components your flows use that are going away, and the parameter and registry features you need for the preparation work. Treat it as its own change, with its own window and its own rollback. Do not combine it with the NiFi 2 move.
Prefer a parallel cluster to an in-place upgrade
Nodes in a NiFi cluster run the same version, so there is no rolling node-by-node upgrade from 1.x to 2.x inside one cluster. You can stop the whole cluster and upgrade it in place, but then rollback means restoring the old installation, the old flow and the old repositories, under pressure.
A parallel NiFi 2 cluster is more work to stand up and far easier to live with. It runs Java 21 with the new configuration from day one, it can be tested at production volume before anything moves, and the 1.x cluster stays intact as the rollback target.
Move flows in groups, not all at once
Divide the estate into cutover groups, using the inventory from your assessment. Good groups share sources and sinks, so you move a source and everything that reads from it together. Start with a group that matters but is forgiving: a feed with replayable sources and a tolerant consumer. Leave the flows with the hardest delivery requirements for later, when the procedure has been run a few times.
For each group, the cutover looks the same:
- Deploy the group's versioned flows to the NiFi 2 cluster from the registry, with the production parameter context, but leave the sources stopped.
- Stop the sources on the 1.x cluster and let the queues downstream drain to empty.
- Confirm the drain: no FlowFiles left in the group's queues, nothing in flight to sinks.
- Start the group on NiFi 2, sources last.
- Watch the first full cycle: throughput, queue depth, bulletins, and the downstream system's own view of what arrived.
Draining matters. FlowFiles sitting in a 1.x queue are in that cluster's repositories, and they are not going to appear on the new cluster by themselves.
Decide what "replayable" means for each source
The safety of a cutover depends on the sources. A Kafka consumer with committed offsets, a directory that is only cleaned up after processing, or a database query with a high-water mark can usually be resumed on the new cluster where the old one stopped. A listener that accepts pushes, such as syslog, HTTP or TCP, cannot be paused without the sender noticing. For those, plan the switch at the sender or the load balancer, and agree the window with whoever owns it.
Rehearse the rollback
A rollback plan that has never been run is a hope. For each group, write the rollback steps down: stop the group on NiFi 2, drain it, restart it on 1.x, and point any push sources back. Then run it, in staging and once in production on the first low-risk group, with the clock running. You will find a missing firewall rule or a forgotten certificate in rehearsal rather than at two in the morning.
Keep the 1.x cluster running, with its flows stopped, until every group has been on NiFi 2 through at least one full business cycle: a month end for anything financial, a reporting period for anything regulatory.
Write the evidence down
Each group's cutover should leave a short record: when it moved, what was checked, what the first cycle looked like, and who signed it off. Regulated teams need this for auditors. Everyone else will want it the first time someone asks whether a missing record went missing before or after the move.
When to decommission 1.x
Only when every group has run cleanly on NiFi 2 through its business cycle, and the registry, parameter contexts and runbooks are confirmed as the system of record. Then archive the 1.x configuration and flow files, and turn the old cluster off.
This is how we run the cutover stage of a NiFi 2 migration.