Skip to content

Elasticsearch 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.


Instructions

  1. In a PowerShell (Administrator), change to the SEAL Elastic Stack - 8.19.24.551 - msi\server directory:

    cd "SEAL Elastic Stack - 8.19.24.551 - msi\server"
    
  2. Start Upgrade Helper with the -dryrun option:

    & "C:\Program Files\SEAL Systems\seal-kibana\node\default\node.exe" .\upgrade_helper.js -dryrun
    
  3. Review rollovers, index cleanup, and indices that need re-indexing.

  4. Start Upgrade Helper without the -dryrun option:

    & "C:\Program Files\SEAL Systems\seal-kibana\node\default\node.exe" .\upgrade_helper.js
    

    For available options, see Elasticsearch Upgrade Helper - Usage

    Hint - patience required

    It may take some time until the re-indexing process is finished.

  5. In a browser, Start Elastic Upgrade Assistant and follow the instructions:

    http://localhost:5601/app/management/stack/upgrade_assistant/overview
    
  6. In Elastic Upgrade Assistand, complete any reported data-stream or system-index actions.

  7. Start Upgrade Helper again, until any upgrade warnings are eliminated.


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=0 unless that variable is already set to 0. Use trusted TLS certificates in production whenever possible.


Back to top