Version Upgrade Notes

This article describes the precautions to take when upgrading; please read it carefully before proceeding with the upgrade.

Need to migrate data, skip installation

When the installer detects that the currently installed component versions differ from those in the upgrade package, a direct replacement upgrade is not possible.

A data migration must be performed via scripts before the upgrade can proceed.

• Using the HENGSHI SENSE built-in database (metadb), refer to Database Service Upgrade
• Using the HENGSHI SENSE built-in object storage (minio), refer to Object Storage Service Upgrade

Upgrading from Version ≤4.2 to This Version

1. Metadb versions 9.x are no longer supported; confirm the Metadb version before upgrading.

   1. If using HENGSHI’s built-in database, refer to Database Service Upgrade.
   2. If using an external database, upgrade it yourself; version 13.xx is recommended.

2. JDK 1.8 is no longer supported. For container or K8s deployments this step can be skipped; for VM single-node or cluster deployments you must run init-os all before upgrading.

   1. In offline environments, contact support to obtain the JDK static package.

cd /opt/hengshi/lib
export hs_version="openjdk-11.0.17_8.1"
wget https://download.hengshi.com/hs-jdk/${hs_version}.tar.gz
tar -zxf ${hs_version}.tar.gz && rm ${hs_version}.tar.gz
ln -sf ${hs_version} jdk

2. Note: If a specific JDK version is required, configure the following in conf/hengshi-sense-env.sh:

export HS_JDK_HOME="JDK installation directory"  # parent directory of the bin folder

3. A built-in Doris engine is provided. If you need to use Doris as the default built-in engine, refer to Doris Engine Configuration.

Roll Back to Version < 4.4

1. Version 4.4 introduces logic-level optimizations for the Greenplum engine and is incompatible with programs launched under Version < 4.4. Before performing the rollback, run the following:

cd /opt/hengshi
bin/clean_engine.sh -d true

After completion, proceed with the rollback operation.

Notes on Using an External PostgreSQL Database Instead of Metadb

Please refer to the step "Use a superuser account to grant permissions to users" in the preparation section of Replacing HENGSHI Metadb.

Notes on Configuring a Secondary Path

This release no longer supports secondary-path access via the CONTEXT_PATH parameter.
If you need secondary-path access, please refer to Secondary Access Path Configuration.

MinIO Cleanup Notes

Earlier versions sometimes failed to delete images when an App was removed, leaving orphaned files in MinIO. This release adds a cleanup job that removes those unused images and improves the deletion logic while reorganizing the storage layout.

Before upgrading, complete the following preparations:

1. Back up MinIO (including cloud deployments) and the MetaDB.
2. Wait for the cleanup job to finish during the upgrade. Monitor progress in the logs by filtering on MinioImageClean. Tests show that cleaning 11 GB of orphaned images takes roughly four minutes.

TIP

Affected versions: 4.5.4 and earlier, plus 4.6.
When upgrading from 4.6.1 to this release, the MinIO cleanup task will run; upgrades from any other version will skip it.

Modifying the Default Configuration for LDAP Authentication

LDAP authentication has the “sync user attributes” option disabled by default.
During an upgrade, user attributes will no longer be synchronized.
Before upgrading, confirm whether you need to synchronize user attributes; if so, set this configuration to true.

Affected versions: When upgrading from 4.5.11 and earlier, 5.0.0, 5.0.1, 5.0.2, 5.0.3, 5.0.4, or 5.1.0 to the current release, verify this setting.

Notes on Renaming the Session Cookie Default

The default name of the session cookie is _USER_SESSION_ID; after upgrading, users must log in again.
If your customer’s system still relies on the former cookie name sid, update the code to use the new name _USER_SESSION_ID,
or set the parameter export SESSION_COOKIE_NAME=sid (the original cookie name).

Affected versions: 4.5.15 and earlier, 5.0.0–5.0.8, 5.1.0–5.1.4; other versions are not impacted.

6.0+ First-Upgrade Health-Check Configuration

The 6.0.0 upgrade/migration takes a long time; actual duration varies with metadb size, CPU performance, and disk I/O.
Example: metadb 40 GB (75 k Dashboards, 430 k Charts), Xeon W-2191B @ 2.30 GHz, standard cloud SSD ≈ 15 min.
Before the first 6.0+ major upgrade, disable startup health checks; re-enable them only after the upgrade and successful startup.
Below are modification suggestions for common deployment types:

2-1 Disable Health Checks

[Single-node & Cluster Deployment]

Stop the monit monitoring service

${HENGSHI_HOME}/bin/hengshi-sense-bin stop monit
# {HENGSHI_HOME} is the installation directory variable for HENGSHI; do not copy and execute it directly.

[Docker Deployment]

Comment out the healthcheck section under hengshi in the docker-compose file, then restart the hengshi service

    healthcheck:
      test: /opt/hengshi/bin/hengshi-sense-bin health hengshi
      interval: 10s
      timeout: 30s
      retries: 90

[Kubernetes Deployment]

Comment out the following three probes in the hengshi-sense deployment manifest, then restart the hengshi service

• startupProbe
• livenessProbe
• readinessProbe

kubectl -n [namespace] edit deployment hengshi-sense

          startupProbe:
            exec:
              command:
                - /bin/bash
                - /opt/hengshi/bin/hengshi-sense-bin
                - health
                - hengshi
                - single
            periodSeconds: 10
            successThreshold: 1
            failureThreshold: 90
          livenessProbe:
            exec:
              command:
                - /bin/bash
                - /opt/hengshi/bin/hengshi-sense-bin
                - health
                - hengshi
                - single
            periodSeconds: 10
            successThreshold: 1
            failureThreshold: 3
          readinessProbe:
            exec:
              command:
                - /bin/bash
                - /opt/hengshi/bin/hengshi-sense-bin
                - health
                - hengshi
                - single
            periodSeconds: 10
            successThreshold: 1
            failureThreshold: 3

2-2 Post-upgrade Health Check Recovery

[Single-node & Cluster Deployment]

Restore the monit monitoring service

${HENGSHI_HOME}/bin/hengshi-sense-bin start monit
# {HENGSHI_HOME} is the installation directory variable of HENGSHI; do not copy and execute it directly.

[Docker Deployment] & [K8s Deployment]

Uncomment the content disabled during the shutdown phase, then restart the hengshi service

Version scope: first-time upgrade from any release prior to 6.0.0 to 6.0+, e.g. 4.5.x → 6.2.y, 5.4.x → 6.0.y

Systems already running 6.0+ are unaffected when upgrading to another major version, i.e. 6.0.x → 6.1.0 is not subject to this requirement; there is no need to disable the health check for the initial upgrade.

6.0+ nginx configuration changes

Version 6.0.0 optimizes the caching logic for static assets; consequently, the reverse proxy in front of HENGSHI SENSE must be updated to cache the entry-level static files.
Take nginx as an example—add the following inside the HENGSHI SENSE server block:

location ~* \.(html|htm)$ {
    add_header Cache-Control "no-store, no-cache, must-revalidate";
    add_header Pragma "no-cache";
    add_header Expires "0";
}

Complete nginx configuration reference; other proxies or cloud LBs need equivalent settings.

Version impact: upgrades from versions prior to 6.0.0 to 6.0.0+

6.2+ k8s Deployment Notes

Starting from 6.2, the k8s deployment method adds the hengshi-rbac.yaml file. When upgrading, you must apply this file (it is located inside the k8s configuration package of the corresponding version):

# Replace <namespace> with the actual namespace name
sed -i 's/__HENGSHI_NAMESPACE__/<namespace>/' hengshi-rbac.yaml
kubectl -n <namespace> apply -f hengshi-rbac.yaml