Upgrade Helper¶
The upgrade_helper.js script offers a partial automation of data migration when the upgrading to the next major version of SEAL Elastic Stack.
It checks whether an Elasticsearch cluster is ready for an upgrade to the next major version. It checks:
-
cluster health
-
Elasticsearch version compatibility
-
Upgrade Assistant warnings
-
system-index migration requirements
-
incompatible indices
-
incompatible data streams.
The script uses the Elasticsearch and Kibana REST APIs.
Hint - Node.js version
The scritpt requires Node.js 18 or later.
Starting Upgrade Helper¶
-
Linux:
/opt/seal/seal-kibana/node/glibc-217/bin/node ./upgrade_helper.js <-options> -
Windows:
& "C:\Program Files\SEAL Systems\seal-kibana\node\default\node.exe" .\upgrade_helper.js <-options>
Usage¶
node configuration/scripts/upgrade_helper.js \
-url http://localhost:9200 \
-kurl http://localhost:5601 \
-user elastic:elastic \
-targetversion 9.0.0
-dryrun
| Option | Description |
|---|---|
-debug |
Activates the debugging mode. |
-dryrun |
Shows a preview of planned changes. |
-h or -help |
usage command: <node_path> ./upgrade_helper.js -h |
-k or -kurl <url> |
Kibana URL Default: http://localhost:5601 |
-l or -url <url> |
Elasticsearch URL Default: http://localhost:9200 |
-monochrome |
Prints results in plain text using the terminal's configured foreground color. |
-reindex-polling-interval <seconds> |
Interval in seconds for checking the Kibana re-indexing queue. Default: 10 |
-t or -targetversion <version> |
Target version of Elasticsearch. If not specified, the next major version is chosen. |
-u or -user <user:password> |
Basic authorization credentials for Elasticsearch and Kibana. |
Re-indexing Behavior¶
For incompatible indices, the script triggers Kibana Upgrade Assistant batch re-indexing and waits for the queue to become empty. It then checks Elasticsearch migration deprecations again.
Before re-indexing, the script cleans up all existing .kibana-event-log-7.17.<patch> aliases. If no such alias exists, it skips this cleanup step.
If one or more indices still require re-indexing, the script creates an empty target index named:
reindexed-v<target-major>-<source-index>
It does not overwrite an existing target index. The script then triggers one retry for the successfully prepared targets, waits for the queue, and verifies completion again. Any remaining indices are reported as requiring manual action.
When re-indexing succeeds and no incompatible data streams require manual action, the script checks upgrade readiness again before finishing. It reports that the system is ready without requiring a second invocation.
The target is deliberately created without mappings, aliases, ILM settings, or pipelines. This prevents the production index template from being unintentionally applied to the temporary re-index target.
For known mapping conflicts, the code contains an inactive alternative that creates the target with index.default_pipeline. It derives the pipeline name from the source index alias. Enable this only when the alias is known to match the required top-level ingest pipeline.
Safety Notes¶
-
If Kibana reports a pending re-index queue when the script starts, it enables dry-run mode automatically and performs no changes.
-
The helper does not delete existing
reindexed-v...target indices. -
A completed Kibana queue alone is not treated as success; the script verifies Elasticsearch migration deprecations afterwards.
-
Incompatible data streams require manual resolution in Kibana Upgrade Assistant.
-
The script sets
NODE_TLS_REJECT_UNAUTHORIZED=0unless the variable is already set to0. Use trusted TLS certificates in production whenever possible.