Skip to main content
Version: 8.8

Upgrade Optimize from 8.7 to 8.8

Upgrade Optimize from version 8.7 to 8.8. This guide explains the required preparation and the supported ways to run the Optimize upgrade without losing existing data.

You can upgrade directly from any 8.7.x release to 8.8.x. Do not skip minor versions. If you are upgrading from an earlier version, see Upgrading from an earlier Optimize version.

Before you begin​

Before starting the upgrade:

  • Plan for downtime. Optimize must be stopped during the upgrade.
  • Verify that your database version is supported for Optimize 8.8. See Optimize changes in 8.8.
Elasticsearch and OpenSearch

Unless stated otherwise, the steps in this guide apply to both Elasticsearch and OpenSearch. The term database is used to refer to either system.

Prepare for the upgrade​

  1. Shut down the database and open the jvm.options file in the config directory of your database installation.

    Set both Xms and Xmx to at least 1g:

    -Xms1g
    -Xmx1g

  2. Restart the database and ensure the database is running and remains available for the entire upgrade process.

  3. Shut down the Optimize instance before starting the upgrade.

  4. (Recommended) Create a snapshot of your database:

  5. Verify available storage. During the upgrade, temporary disk usage can reach up to twice the current database size.

  6. (Optional) Back up the following files from the Optimize config directory:

    • environment-config.yaml
    • environment-logback.xml

  7. Install the new Optimize version as described in the Optimize installation guide.

    If you customized logging in the previous version, copy the backed-up environment-logback.xml into the config directory of the new Optimize installation.

Upgrade the database version (optional)​

Only perform this step if you are upgrading Elasticsearch or OpenSearch as part of the Optimize upgrade.

Follow the official rolling upgrade documentation for your database:

For rolling upgrades, see:

Run the Optimize upgrade​

How you run the upgrade depends on how Optimize is deployed.

Helm-based deployments​

If Optimize is deployed using Helm, perform a standard Helm upgrade:

helm upgrade <release-name> <chart>

Follow your existing Helm upgrade workflow.

Non-Helm deployments​

For other deployment methods, run the Optimize upgrade as part of the startup process by passing the --upgrade flag.

Docker Compose example​

services:
  optimize:
    image: registry.camunda.cloud/optimize-ee/optimize:8-latest
    command: ["./optimize.sh", "--upgrade"]

To avoid long startup times that can interfere with container probes, run the upgrade using an init container:

initContainers:
  - name: optimize-upgrade
    image: registry.camunda.cloud/optimize-ee/optimize:8-latest
    command: ["./upgrade/upgrade.sh", "--skip-warning"]
containers:
  - name: optimize
    image: registry.camunda.cloud/optimize-ee/optimize:8-latest

Resume a failed upgrade​

Optimize upgrades are resumable. If the upgrade is interrupted, rerun the upgrade command. Completed steps are detected automatically and skipped.

Example log output:

INFO UpgradeProcedure - Skipping Step 1/2: UpdateIndexStep on index: process-instance-key1
INFO UpgradeProcedure - Starting step 2/2: UpdateIndexStep on index: process-instance-key2

Troubleshooting common issues​

Schema version mismatch​

Error message:

Schema version saved in Metadata does not match required [8.X.0]

This error occurs when the upgrade script does not match the current Optimize version.

For example, using an upgrade artifact intended for 8.5 → 8.6 against an 8.4 database causes this error.

Resolution: Download and run the Optimize upgrade artifact that matches your current Optimize version.