Title
Create new category
Edit page index title
Edit category
Edit link
NiFi Upgrade Standalone Toolkit — Usage Guide
This guide walks customers through using the Acceldata NiFi Upgrade Toolkit to move from ODP NiFi 1.28.1 → ODP NiFi 2.7.2 and the matching upgrade for NiFi Registry 1.x → 2.7.2.
The toolkit covers three stages:
- Pre-upgrade check — assesses your current install and flow for blockers.
- Pre-upgrade backup + install — captures a backup, then installs the 2.7.2 binaries with automatic rollback on failure.
- Post-upgrade check — validates the upgraded service over its REST API.
The toolkit handles assessment, backup, install, and post-cutover validation. It does not rewrite flow.json.gz (processor replacement, bundle edits) — that work is done in the NiFi UI, in NiFi Registry, or via your own migration tooling.
Clustered NiFi: run the installer node-by-node (stop all nodes → install on each in turn → start nodes one at a time). The installer warns if it detects clustering but does not orchestrate across nodes.
Prerequisites (both sections)
- Python 3.6+ on the NiFi / Registry host
- Java 21 available on the host (required by NiFi 2 / Registry 2)
- Shell access (root/sudo for install stage)
- The toolkit tarball extracted on the host:
xxxxxxxxxxwget https://mirror.odp.acceldata.dev/ODP/standalone/3.3.6.4-1/nifi-upgrade-toolkit.tar.gztar -xzf nifi-upgrade-toolkit.tar.gzcd nifi-upgrade-toolkit./install_deps.sh # one-time per host: installs ijson for streaming flow.jsonSection 1 - NiFi
1.1 Stage 1: Pre-upgrade check
Assesses your NiFi 1.28.1 install and flow for anything that will break under NiFi 2.
Run:
xxxxxxxxxx# Auto-discover NiFi home from the running process or common install paths./pre_upgrade_check.sh # Or pass it explicitly, with Java 21 for the version check./pre_upgrade_check.sh \ --nifi-home /usr/odp/current/nifi \ --java-home /usr/lib/jvm/java-21NIFI_HOME and JAVA_HOME environment variables are accepted in place of the flags.
What it Checks
| No. | Check | Flags |
|---|---|---|
| 1 | Java version | Java 21 must be available for NiFi 2 |
| 2 | Removed / deprecated components | Kafka 1/2/2.6, HBase, Hive, Solr, GetTCP, etc. |
| 3 | Removed scripting languages | Ruby, Python (Jython), ECMAScript, Lua |
| 4 | Process group variables | Must migrate to Parameter Contexts |
| 5 | EVENT_DRIVEN scheduling | Removed in NiFi 2 |
| 6 | Templates | Removed in NiFi 2 |
| 7 | Legacy Kerberos | Principal/keytab/password patterns to move to Kerberos User Services |
| 8 | Bundle coordinate changes | NAR moves/renames (Jolt, FileParameterProvider, …) |
| 9 | Sensitive properties | Missing nifi.sensitive.props.key; PBE algorithms dropped in NiFi 2 |
| 10 | Controller service wiring | Dangling refs, disabled dependencies, circular graphs |
| 11 | Expression Language | EL functions removed in NiFi 2 (none on the 1.28.1 → 2.7.2 path) |
| 12 | Third-party NARs | Non-org.apache.nifi bundles |
| 13 | Groovy compatibility | Groovy scripted components (manual validation) |
| 14 | Cluster configuration | ZK connect string, TLS/S2S vs NiFi 2 behavior |
| 15 | Parameter Context conflicts | Duplicates / empty contexts |
| 16 | Authorization | FileAuthorizer (removed in 2.7.1+); Ranger major version |
| 17 | Connector architecture | Processors that need new controller services in NiFi 2 |
Output
Two files are produced in the working directory:
| File | Contents |
|---|---|
nifi-pre-upgrade-report-<timestamp>.json | Machine-readable report |
nifi-pre-upgrade-report-<timestamp>.txt | Human-readable log of the run |
| Prefix | Meaning |
|---|---|
OK | No issues found |
WARN | Advisory — review, not a hard blocker |
ERROR | Must be resolved before upgrading |
Exit codes: 0 = clean (OK / WARN), 2 = one or more ERROR items, 1 = script error.
Resolve every ERROR in the report before continuing.
1.2 Stage 2a: Pre-upgrade backup
Captures conf/, the flow, and the content/provenance repository paths referenced in nifi.properties into a timestamped tarball under /var/tmp/nifi-upgrade-backups/.
The installer in Stage 2b refuses to run without a backup archive from this step.
xxxxxxxxxx# Dry run — lists paths that would be archived./upgrade_pre_activity_nifi.sh --nifi-home /usr/odp/current/nifi # Create the backup./upgrade_pre_activity_nifi.sh --nifi-home /usr/odp/current/nifi --execute1.3 Stage 2b: Install NiFi 2.7.2
Fetches the NiFi 2.7.2 tarball from the Acceldata repo, verifies its sha256, stops the running 1.x service, extracts the new version, merges configuration from the Stage 2a backup, flips the /usr/odp/current/nifi symlink, and starts the service. On any failure after service stop, the script automatically rolls back — symlinks revert, conf/ is restored from the backup, and the 1.x service is started again.
Supported Operating Systems: RHEL 8, RHEL 9, Debian, Ubuntu (auto-detected).
xxxxxxxxxx# Standard ODP layout (installs NiFi + Registry together)./upgrade_nifi.sh \ --nifi-home /usr/odp/current/nifi \ --nifi-registry-home /usr/odp/current/nifi-registry # NiFi only./upgrade_nifi.sh --nifi-home /usr/odp/current/nifi --skip-registry # Preview without making changes./upgrade_nifi.sh --nifi-home /usr/odp/current/nifi --dry-runCommon overrides
| Flag | Default | Purpose |
|---|---|---|
--install-root | /usr/odp | Base directory under which the new version is extracted |
--current-symlink-nifi | /usr/odp/current/nifi | Symlink that is flipped to the new version |
--java21-home | /usr/lib/jvm/java-21 | Java 21 location for NiFi 2 |
--backup-root | /var/tmp/nifi-upgrade-backups | Where Stage 2a archives are read from |
--tarball-url | Acceldata repo URL | Override for air-gapped installs |
Checksum: every tarball is fetched with its .sha256 and verified via sha256sum -c before anything is extracted. A mismatch aborts before any state is mutated.
1.4 Stage 3: Post-upgrade check (NiFi)
Calls the NiFi 2 REST API and validates the upgrade landed cleanly.
xxxxxxxxxx# Local, self-signed TLS./post_upgrade_check.sh --base-url https://127.0.0.1:8443/nifi-api --insecure # Remote with basic auth./post_upgrade_check.sh \ --base-url https://nifi.example:8443/nifi-api \ --user nifi --password "$NIFI_PASSWORD"| # | Check | What it Verifies |
|---|---|---|
| 1 | NiFi version | Reports 2.x |
| 2 | Invalid processors | invalidCount == 0 across all process groups |
| 3 | Controller services | None in validationStatus=INVALID |
| 4 | Cluster node health | All nodes CONNECTED (skipped for standalone) |
| 5 | System diagnostics | NiFi reachable; versionInfo present |
| 6 | Bulletin board | No ERROR-level bulletins |
Exit 2 if the version is not 2.x, any processor or controller service is INVALID, any cluster node is not CONNECTED, or ERROR-level bulletins are present.
Section 2 - NiFi Registry
The Registry upgrade follows the same three-stage flow. If you run NiFi and Registry on the same host, you can combine the pre-check and post-check invocations as shown at the bottom of this section.
2.1 Stage 1: Pre-upgrade Check
Validates Registry 1.x configuration before moving to Registry 2.x: Java 21, nifi-registry.properties, bootstrap.conf, authorizers, identity providers.
xxxxxxxxxx./registry_pre_upgrade_check.sh \ --nifi-registry-home /usr/odp/current/nifi-registry ./registry_pre_upgrade_check.sh \ --nifi-registry-home /opt/nifi-registry \ --java-home /usr/lib/jvm/java-21 \ --output /tmp/reg-report.jsonNIFI_REGISTRY_HOME can be set instead of --nifi-registry-home. Exit codes match the NiFi pre-check: 0 for clean, 2 if any ERROR is reported.
2.2 Stage 2a: Pre-upgrade Backup
The Stage 2a script for NiFi also captures Registry state when --nifi-registry-home is supplied to the installer; for a Registry-only or standalone Registry host, back up the conf/ directory and any database/flow-storage directory referenced by nifi-registry.properties before running Stage 2b.
2.3 Stage 2b: Install NiFi Registry 2.7.2
Registry is installed by the same upgrade_nifi.sh script when --nifi-registry-home is passed. The same checksum verification and automatic rollback apply.
xxxxxxxxxx# NiFi + Registry togethersudo ./upgrade_nifi.sh \ --nifi-home /usr/odp/current/nifi \ --nifi-registry-home /usr/odp/current/nifi-registry # Override the Registry tarball source (air-gapped, etc.)sudo ./upgrade_nifi.sh \ --nifi-home /usr/odp/current/nifi \ --nifi-registry-home /usr/odp/current/nifi-registry \ --registry-tarball-url https://repo.acceldata.io/odp/nifi/2.7.2/nifi-registry-2.7.2-odp-bin.tar.gzRegistry symlink default: --current-symlink-registry /usr/odp/current/nifi-registry.
Validates the Registry REST API after cutover.
xxxxxxxxxx./registry_post_upgrade_check.sh \ --base-url https://host:18443/nifi-registry-api| Check | What it Verifies |
|---|---|
/about | Reports 2.x |
/buckets | Reachable |
/access/config | Responds |
2.5 Running NiFi + Registry Together
Both checks can be combined in a single invocation:
xxxxxxxxxx# Pre-upgrade — NiFi + Registry in one run./pre_upgrade_check.sh \ --nifi-home /usr/odp/current/nifi \ --nifi-registry-home /usr/odp/current/nifi-registry # Post-upgrade — NiFi + Registry in one run./post_upgrade_check.sh \ --base-url https://nifi.example:8443/nifi-api \ --registry-base-url https://nifi.example:18443/nifi-registry-api \ --user admin --password "$PW"Aggregate exit codes follow the strictest result across the two checks.
Recommended workflow
- Run the pre-upgrade check for NiFi (and Registry, if applicable). Resolve every
ERRORin the report. - Run the pre-upgrade backup with
--execute. - Run the installer (
upgrade_nifi.sh) on each host. For clusters, do this node-by-node. - Run the post-upgrade check against the upgraded service URLs.
- Verify your flows in the NiFi UI and your buckets in the Registry UI.
Support
This toolkit is shipped by Acceldata. For production upgrade runbooks and assistance, contact your Acceldata or ODP distribution support channel.