Why the sensitive properties algorithm must change before a NiFi 2 upgrade
The sensitive properties algorithm must be a value NiFi 2 supports before you upgrade. NiFi 2.0.0 accepts only NIFI_ARGON2_AES_GCM_256 and NIFI_PBKDF2_AES_GCM_256 for nifi.sensitive.props.algorithm. Any 1.x instance still using an older algorithm will not start on 2.x until the value is migrated, so the change belongs in the upgrade plan as a prerequisite step, not as a fix applied after a failed start. NiFi 1.x has no further maintenance path, and the project's migration guidance is explicit that the route to 2.0.0 runs through 1.27.0 first, so the sensitive properties change is one of several items to complete on that intermediate release.
The reason 1.x cannot simply be kept running is structural. The NiFi project states that the 1.x line depends on Jetty 9.4, Spring Framework 5.3 and AngularJS 1.8, and none of these can be upgraded within that line. NiFi 1.28 is the last minor release of the version 1 series, and the downloads page lists an end-of-support date of December 8, 2024 for 1.28.1. A team still on 1.x is therefore running without upstream fixes for its framework stack, which makes moving to 2.x a planned project with a defined order of steps rather than a deferred task.
Before scheduling the upgrade, confirm the algorithm your instance uses by checking nifi.properties on every node, since clusters can drift. Then decide which supported value you will migrate to and who owns the change window, because the sensitive properties key protects every encrypted value in the flow and the key must be handled carefully during the move. Confirm the exact command syntax and prerequisites against the NiFi migration guidance for deprecated components and your own test environment before you run it in production.
Which algorithm changes break the upgrade and what to do
This table compares the sensitive properties algorithm change between NiFi 1.x and NiFi 2.0.0, showing the impact on an existing instance and the action to take. Read each row in order, because the migration command must run on the 1.x instance before the upgrade begins.
| Item | Impact on a 1.x instance | Action required |
|---|---|---|
| NiFi 1.14.0 default change | Instances created or reset from 1.14.0 onward typically use NIFI_PBKDF2_AES_GCM_256, while older instances may still use a deprecated algorithm. | Check nifi.sensitive.props.algorithm in nifi.properties to confirm the value the instance actually uses. |
| NiFi 2.0.0 supported algorithms | NiFi 2.0.0 accepts only NIFI_ARGON2_AES_GCM_256 and NIFI_PBKDF2_AES_GCM_256 for sensitive properties. | Confirm the 1.x value is one of these two, or plan a migration to one of them before upgrading. |
| Deprecated algorithm in use | A 1.x instance on any other algorithm cannot run on 2.0.0 with its existing sensitive values as configured. | Run the nifi.sh set-sensitive-properties-algorithm command on the 1.x instance to migrate to a supported algorithm. |
| Migration command timing | The command changes how encrypted sensitive values are stored, so it must complete before the NiFi 2 binaries start. | Run it on the 1.x instance, verify the flow still loads, then proceed with the upgrade. |
| Cluster nodes | Each node holds its own nifi.properties, so a mixed configuration causes nodes to disagree about sensitive values. | Apply the same algorithm and migration steps on every node, and confirm all nodes match before restarting. |
| Backup and key material | A failed migration can leave encrypted values unreadable without the matching key and configuration. | Back up nifi.properties, the flow configuration and the sensitive properties key before running the command. |
How to check which algorithm your instance uses
On a package or archive install on a host or virtual machine, the algorithm is set in the NiFi properties file, which is normally nifi.properties in the conf directory of the NiFi home path. Open that file on each host and read the value of nifi.sensitive.props.algorithm. A 1.x instance often shows the default or an older value that was set when the instance was first installed, so do not assume the line is absent or current.
- Find the file: Locate the active
nifi.propertiesin the directory your service manager or startup script points to, not a copy in a backup or template folder. - Read the key: Record the exact value of
nifi.sensitive.props.algorithmand whether the line is commented out. - Check the service user: Confirm the process reads the same file, since a second installation under another path can hold a different value.
- Compare across hosts: Run the same read on every node and write the results in one table with the node name, path and value.
- Confirm the layout: Check the exact file location for your distribution against the NiFi System Administrator's Guide before you edit anything.
Record every node's value before you plan the upgrade, because the next step depends on what you find.
In a container image or Kubernetes deployment, the property is usually supplied through the image's configuration, a mounted nifi.properties file, or environment variables passed by a Deployment, StatefulSet or Helm values file. The file inside a running pod can differ from the file in the source repository if an init container or entrypoint script rewrote it, so check the running container, not only the manifest.
- Check the source: Review the Helm values, Kustomize overlays or manifests that set
nifi.sensitive.props.algorithmor the environment variable that feeds it. - Check the running pod: Use
kubectl execto read the effectivenifi.propertiesin each pod, and compare it with the manifest. - Look for overrides: Search for init scripts or entrypoint logic that rewrites the file at startup.
- Check the image tag: Note the image version, because the image may carry defaults that differ from your overrides.
- Keep the evidence: Save the rendered configuration as a file under version control so the change can be reviewed later.
If a value comes from a Kubernetes Secret, confirm who can read it, because the sensitive properties key itself must be handled with the same care.
A NiFi cluster must use one sensitive properties algorithm across all nodes. If nodes disagree, sensitive values in the shared flow may not be readable on every node, and the migration step you run later may fail or leave the cluster partly converted. Check the value on each node directly, and do not rely on the coordinator's view or a single representative host.
- Enumerate every node: Build the list from the cluster page in the UI or from your inventory, so no node is missed after a scale-out.
- Compare values: Mark each node as matching or differing from the others, and investigate any difference before continuing.
- Check the shared key source: Confirm that all nodes read the same sensitive properties key from the same source, such as a shared secret store or a matched file.
- Watch for stale nodes: A node that was removed, rejoined or rebuilt may carry older configuration.
- Freeze changes: Pause configuration changes while you collect values so the snapshot is accurate.
Only move on when every node reports the same value and you know the source of that value.
Auditors and security reviewers often ask which cryptographic settings protect stored credentials and sensitive flow values, and when they last changed. A written record of the check gives you a baseline for the change and for the evidence you retain, without you having to reconstruct it later. The record should show what was read, where, and by whom, rather than an opinion about whether the setting is good enough.
- Record the source: Note the file path, host or pod, and the exact key and value read.
- Record the time: Capture the date of the check so it can be matched to change tickets.
- Record the owner: Name the person who ran the check and the person who reviewed it.
- Store the output: Keep the command output or screenshot in your change repository, with access limited to the team that needs it.
- Ask for a second read: Have a second engineer confirm the values, especially for clustered installs.
The record is an input to your change process. It does not replace an independent assessment by your auditor.
Why NiFi 2 supports only Argon2 and PBKDF2 AES-GCM 256
The sensitive properties key protects values that NiFi writes to its configuration and flow files in encrypted form, such as passwords, tokens and other sensitive processor and controller service properties. The algorithm setting, nifi.sensitive.props.algorithm, determines how that key is used to derive the encryption key. NiFi 2.0.0 accepts only two values: NIFI_ARGON2_AES_GCM_256 and NIFI_PBKDF2_AES_GCM_256. Any instance still using an older algorithm must move to one of these two before it can start on NiFi 2. NiFi 1.14.0 had already changed the default to NIFI_PBKDF2_AES_GCM_256, so many 1.x instances may already be on a supported option, but you should confirm the value in your own nifi.properties rather than assume it.
Limiting the set to two options keeps the number of encryption schemes NiFi must maintain and test small, and it removes older choices from the upgrade path. The sources supplied for this topic do not compare the two supported algorithms on performance, memory cost or resistance to specific attacks, so do not choose between them on those grounds without evidence. Confirm the selection against your organization's cryptographic standards and key management policy, and check the NiFi migration guidance for any version-specific notes that apply to your deployment.
Record the algorithm you choose in your change plan, along with who approved it and how the key will be stored and backed up. Changing the algorithm re-encrypts sensitive values, so a failed or interrupted migration can leave values unreadable if the key is lost. Ask your security team to confirm how the sensitive properties key is protected at rest and who may access it before the migration window opens.
Running set-sensitive-properties-algorithm before the upgrade
This sequence moves a 1.x instance off a deprecated sensitive properties algorithm onto a option NiFi 2 supports, with a backup and a verification check at each stage so that the upgrade starts from a known-good state.
Back up configuration and flow definitions
Before changing anything, the administrator copies the full conf directory from every node, including nifi.properties, bootstrap.conf, authorizers.xml, login-identity-providers.xml and the flow configuration file, along with the current flow definitions and any exported templates. Store the copies outside the NiFi installation directory and record the sensitive properties key location and its current value in your secrets system. This backup is the rollback point: if the algorithm change fails, you restore these files and the original key and restart on the 1.x version. The step is done when the backup can be listed and restored to a scratch host, and when someone other than the operator has confirmed it is readable.
Confirm the current algorithm on every node
On each node, the administrator reads the value of nifi.sensitive.props.algorithm in nifi.properties and notes whether it is a deprecated option or one that NiFi 2.0.0 accepts. NiFi 1.14.0 changed the default to NIFI_PBKDF2_AES_GCM_256, so instances built on older defaults may still carry a different value. Compare the value across nodes, since a cluster where nodes disagree will not be consistent after the change. The step is complete when every node's value is written down and any node with a mismatch is identified before proceeding. Confirm the exact supported values against the NiFi migration documentation for your target release.
Stop the cluster before running the command
The administrator stops NiFi on the nodes according to your normal cluster procedure so that the sensitive properties migration runs against stopped instances and no flow changes are written during the update. Confirm that no node is still processing, that queues are drained or intentionally paused, and that the flow configuration file is not being written. The step is done when the process check on each host shows NiFi is not running. Ask your NiFi administrator whether your cluster needs a specific stop order, since this depends on your topology and any load balancer in front of it.
Run set-sensitive-properties-algorithm on the first node
On one node, the administrator runs the nifi.sh set-sensitive-properties-algorithm command with the target supported algorithm, so that the command migrates sensitive values from the deprecated algorithm to the supported one. The command reads the existing key and rewrites encrypted values in the flow and configuration files. Capture the command output and any warnings, and confirm that nifi.properties now shows the new algorithm value. The step is complete when the command reports success and the updated values are in place. Do not run it on a second node until the first node has passed verification in the next step.
Restart the first node and verify flow loading
The administrator starts the first node and checks the application log for errors about flow loading, sensitive property decryption or key mismatches. Open the UI on that node, confirm that the root canvas and process groups load, and spot-check a processor and a controller service that hold a sensitive value, such as a database password, by opening its configuration and confirming the value is present as a masked field. Verify that a representative processor can start in a test process group without credential errors. The step is done when the node is connected and these checks pass. If any check fails, stop, restore the backup taken earlier, and investigate before continuing.
Run the command on remaining nodes and verify each
Repeat the stop, command and restart sequence on each remaining node in turn, running the same log and UI checks after every restart. Confirm that each node reports the new algorithm value in nifi.properties and that it joins the cluster and shows the same flow version as the nodes already updated. Do not start a second node until the previous one is connected and verified. The step is done when every node shows the same algorithm, connects to the cluster and loads the same flow. Mismatched results between nodes should be treated as a stop condition.
Confirm the cluster is ready for the 2.x upgrade
Once all nodes are on the supported algorithm and verified, the administrator records the final algorithm value, the flow version, the backup location and the verification results in the change record. Confirm that the 1.x version still runs cleanly on the updated configuration, since this is the state the upgrade will start from. The step is complete when the change record is signed off and the team agrees to proceed. Only then move on to the NiFi 2.x upgrade, which should follow the migration guidance for your starting version and target release.
What to back up and inventory before changing the algorithm
Changing the sensitive properties algorithm rewrites every encrypted value in the flow and configuration files, so a failed step can leave a node unable to start. The cards below cover what to copy, list and test before the command runs, so that a rollback is possible if the migration fails.
Sensitive properties key and its storage
Locate the sensitive properties key that the instance uses, which is set through nifi.sensitive.props.key in nifi.properties or supplied from an external source in your deployment. Copy the key to a secure, access-controlled location separate from the NiFi host, and confirm that whoever runs the migration can retrieve it. Without this key, the encrypted values in the flow cannot be read after the change.
Flow configuration backups
Before running the migration, copy the current flow configuration file, flow.xml.gz in a 1.x instance, along with nifi.properties and the authorizers and login identity files. Store the copies with a timestamp and a checksum so you can confirm which version you are restoring. These files hold the encrypted values that the algorithm change rewrites.
Components holding sensitive values
Build a list of every processor, controller service and reporting task whose properties are marked sensitive, such as database passwords, API tokens and SSL keystore passwords. Record the component name, process group and property name for each. This list tells you which values to re-enter and verify after the migration, and it shows which components need attention before the NiFi 2 upgrade.
Non-production test copy
Run the migration first on a copy of the production configuration and key, on a separate instance with the same NiFi version. Start it, open the flow, and check that controller services and processors show their sensitive values as set. Only move to production once the test copy starts cleanly, because a failure in production affects live data movement.
Cluster node consistency
In a clustered deployment, confirm that every node uses the same sensitive properties key and the same nifi.properties settings before you start the migration. Plan the change so that all nodes are updated and restarted in a single, documented window. A node that keeps the old algorithm or key will fail to read the shared flow.
Record of the old algorithm for rollback
Write down the value of nifi.sensitive.props.algorithm currently in use, the NiFi version, the date and the person who approved the change. Keep this record with the backups. If the migration must be reversed, this record tells the team which algorithm and key pair the restored configuration expects.
What makes this step take longer in a large or regulated NiFi estate
The main factor in how long this step takes is how many places the sensitive properties key and the encrypted values it protects are spread across. On a single standalone instance, the change is a short, contained operation. In a cluster, every node holds its own copy of nifi.properties, and the algorithm setting must be consistent across them before the upgrade begins. Each additional node adds a stop, migrate, verify and restart cycle, and each node needs its own record of the before and after state. Confirm the node count, whether nodes are split across data centers or sites, and whether any node sits on a host that is hard to reach in a maintenance window. Also count the sensitive values in your flows and controller services, since every one of them must decrypt cleanly under the new setting.
In a regulated estate, the change usually waits on process rather than on the command itself. Many organizations treat a change to the key or algorithm as a high-risk change that needs a documented rollback plan, a named approver and a fixed window. Your change management system may require the exact nifi.sensitive.props.algorithm values before and after, the backup location of nifi.properties, and evidence that the migration ran without errors. If the sensitive properties key is held in a secrets manager or is generated by a configuration tool, that system will also need its own change record. Ask your change board how long approval normally takes and whether a standard change category applies to this kind of work.
Finally, plan retesting for flows that depend on encrypted parameters. Parameter contexts with sensitive values, controller services holding passwords or tokens, and any external scripts that read values from NiFi should be run again after migration, because a failed decryption often surfaces only when a processor is started. Confirm which flows are scheduled to run during the window, which of them call external systems with credentials, and who signs off that each critical flow works after the change. Document the test set before the window opens, so the team is not deciding what to test while nodes are down.
Factors that lengthen the algorithm migration
This table lists the factors that stretch the sensitive properties migration beyond a single command run, with the reason each adds work and what to check first. Use it to scope the effort before agreeing a schedule, since most of the time goes to finding and validating encrypted values rather than to the command itself. The main takeaway is that cluster size, the number of encrypted properties and the state of your configuration tooling matter more than the algorithm change.
| Driver | Why it adds work | What to check |
|---|---|---|
| Cluster size | Each node must be migrated and restarted consistently, so more nodes mean more runs, more verification and a longer rolling sequence. | Node count, whether all nodes share one configuration, and how each node's sensitive properties key is stored and backed up. |
| Count of sensitive properties | Every encrypted value in flow definitions, controller services and configuration files must be decrypted and re-encrypted, and each one is a possible failure point. | Number of components with sensitive property values and whether any values were added by hand or by parameter contexts. |
| Configuration management tooling | If settings are generated from templates or pipelines, the encrypted values may be rewritten on the next deployment and undo the migration. | Whether properties files and flow definitions come from Git, Ansible, Helm or similar tools, and whether those sources hold the old encrypted values. |
| Test coverage | Without a test environment that loads the migrated flows and exercises credentials, failures surface only in production after cutover. | Whether a copy of production configuration and flows exists, and whether each controller service that uses credentials can be tested. |
| Change control | Approvals, change windows and rollback plans add lead time, and the sensitive properties key must be handled under the same controls as other secrets. | Required approvals, the window for restarts, how the key is stored and who can access it, and the rollback steps agreed in advance. |
| Use of external key or secret stores | Where the key or credentials come from a vault or external store, access and rotation must be coordinated with the owners of that store. | Who owns the secret store, how access is granted to the migration account, and whether rotation is scheduled during the window. |
Common questions about the sensitive properties change
What does it cost to update the sensitive properties algorithm before upgrading?
The cost is mostly the time spent on the change itself, which is small compared with the upgrade work around it. The main components are inventory (finding every node, configuration file and deployment script that sets the algorithm), a test run of the migration command on a copy of the production configuration, a documented change window, and verification that flows still start and that sensitive values still decrypt. Costs rise when the instance runs many nodes, when deployment tooling hard-codes the old setting, or when the team has no current backup of the configuration. Ask any partner for a fixed-scope quote that lists each of these items, and ask whether it covers only this step or the full upgrade. This step is one-time work, but the sensitive properties key and related configuration must stay under your control afterward.
How long does the sensitive properties change take?
Duration depends on how many nodes and configuration files are involved, how many environments must be changed, and how much testing your change process requires. The command itself is one step in a longer sequence: confirm the current algorithm, back up the configuration, run the migration, restart, and verify. In a single standalone instance, the core work is short, but review and approval often take longer than the command. In a cluster, the timeline grows because every node must be handled in the same planned order as the rest of the upgrade. No supplied duration applies here, so ask your team or a partner to estimate it from your own environment and change calendar.
What must our team provide before the algorithm change?
You need to provide access and information, not just approval. The team should supply the current nifi.properties files for every node, the value of nifi.sensitive.props.algorithm in use, the sensitive properties key and where it is stored, and the deployment tooling that generates or templates these files. You also need a recent backup of the flow configuration and the ability to restore it, a non-production copy of the instance for rehearsal, and named owners for the change window and sign-off. Security and compliance staff should confirm how the key is protected, because a mismatch between the key and the migrated values causes sensitive properties to fail. Ask your partner which items they expect in writing before work starts.
Can our in-house team make this change without a partner?
Yes, a team that already runs NiFi can usually make this change alone, because the work is a configuration check followed by a supported command. The skills that matter are knowing where your NiFi configuration lives, handling the sensitive properties key safely, and rehearsing the change before production. A partner adds the most value when the instance has many nodes, custom deployment automation, unclear ownership of the key, or a tight window shared with a larger upgrade. Whichever route you choose, record the algorithm before and after, keep the rehearsal output, and confirm that every node reports the same configuration. Your team can confirm the exact command syntax and supported options in the migration guidance for its version.
Can we roll back after changing the sensitive properties algorithm?
Rollback is possible only if you prepare for it before the change, because the migration rewrites protected values. Take a full backup of the configuration and the sensitive properties key before running the command, and store both securely. If the change fails, restore the previous configuration files and the matching key, then restart the node and confirm that flows and sensitive values work. Do not discard the old key or configuration until the upgraded instance has been verified. Restoring the key without the matching configuration, or the reverse, will leave sensitive properties unreadable. Confirm your rollback steps in a rehearsal, since the first restore should not be the first time anyone runs it.
Does updating the algorithm alone make our NiFi instance ready for 2.x?
No. Updating the algorithm removes one blocker, but NiFi 2 requires several other changes before an instance can run. The supported algorithms in NiFi 2.0.0 are limited to NIFI_ARGON2_AES_GCM_256 and NIFI_PBKDF2_AES_GCM_256, so this step is necessary but not sufficient. Your readiness review should also cover the migration path through NiFi 1.27.0, the change from flow.xml.gz to flow.json.gz, the variable registry removal, the Java 21 runtime, the Python processor requirements, and any deprecated or removed components in your flows and custom code. Treat this change as one item in a checklist, and confirm the full list against the migration guidance for your target version.
How DeployOpen scopes and delivers this migration step
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, including the sensitive properties algorithm change that has to happen on a 1.x instance before the upgrade to NiFi 2. Engagements are fixed-scope, with the scope agreed in writing before any work starts.
How we scope
- We confirm the NiFi 1.x versions, nodes and environments that use nifi.sensitive.props.algorithm and need the change.
- The written scope lists which instances, clusters and configuration files are covered by the algorithm migration.
- We agree how sensitive properties key handling, backups and rollback are documented before any production change.
How we build
- We run the set-sensitive-properties-algorithm command against a copy of the instance first, then record the results.
- We verify that the flow still loads and that protected values, such as processor credentials, decrypt correctly after the change.
- We update the configuration files and key storage so that the upgrade plan starts from a known, tested state.
How we hand over
- You receive a written runbook with the exact commands, configuration changes and checks used in your environment.
- The handover records the algorithm before and after the change, the backup locations and the sign-off steps.
- Your team gets a walkthrough so it can repeat the procedure on remaining instances or clusters without us.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers if your NiFi estate needs them.
- We can review the sensitive properties setup again during the NiFi 2 upgrade and during any later version moves.
- Support scope, response expectations and review cadence are agreed in writing with the retainer.
