Version Upgrade Notes

This document outlines important notes for version upgrades. Please read carefully before proceeding with subsequent upgrade operations.

need migrate data, skip installation

When the installer detects that the versions of the currently installed components and those in the upgrade package are inconsistent, a direct replacement upgrade cannot be performed.

You need to perform data migration using a script before proceeding with the upgrade.

• If you are using the built-in HENGSHI database (metadb), refer to Database Service Upgrade
• If you are using the built-in HENGSHI object storage (minio), refer to Object Storage Service Upgrade

Upgrade from Version <= 4.2 to This Version

1. Metadb version does not support 9.x versions. Please confirm the Metadb version information before upgrading.

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

2. JDK version no longer supports 1.8. This issue can be ignored for container and K8s deployment methods. For VM standalone or cluster deployment methods, it is necessary to execute init-os all before upgrading.

   1. For intranet environments, contact after-sales personnel to obtain JDK static resources.

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 parameter in conf/hengshi-sense-env.sh

export HS_JDK_HOME="JDK installation directory"  # The directory above the bin directory

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

Rollback to Version <4.4

1. Version 4.4 introduces logical-level optimizations for the Greenplum engine, which are not compatible with programs running on Version <4.4. Before performing the rollback operation, execute the following steps:

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

After completion, proceed with the version rollback operation.

Precautions for Using an External PostgreSQL Database to Replace Metadb

Please refer to Replacing HENGSHI metadb, specifically the step using a super administrator account to grant permissions to users in the preparations.

Notes on Configuring Secondary Paths

In this version, the CONTEXT_PATH parameter is no longer supported for secondary path access.
If you need to enable secondary path access, please refer to Secondary Access Path Configuration.

Precautions for Cleaning Minio

In previous versions, some scenarios of deleting apps did not remove images, resulting in some unused images being generated in Minio. Therefore, unused images in Minio need to be cleaned up, the deletion logic improved, and the storage layout reorganized.

Please make the following preparations before upgrading.

1. Back up Minio (including cloud environments) and metadb.
2. During the upgrade, wait for the cleanup logic to complete. You can monitor the progress of the cleanup by checking the logs and filter relevant information using MinioImageClean. According to tests, cleaning up 11GB of unused images takes about 4 minutes.

Version impact scope: Versions 4.5.4 and earlier, version 4.6, and version 4.6.1 will perform Minio cleanup operations when upgrading to the current version. Other versions will not perform Minio cleanup operations when upgrading to the current version.

LDAP Authentication Method Default Configuration Change

The default configuration for enabling user attribute synchronization in the LDAP authentication method is set to false. During upgrades, user attributes will no longer be synchronized. Therefore, before upgrading, please confirm whether you need to synchronize user attributes. If synchronization is required, set this configuration to true.

Version Impact Scope: When upgrading from versions 4.5.11 and earlier, 5.0.0, 5.0.1, 5.0.2, 5.0.3, 5.0.4, and 5.1.0 to the current version, you need to check this configuration item.

Notes on Modifying the Default Name of Session Cookie

The default name of the session cookie is _USER_SESSION_ID. After upgrading, you will need to log in again. If your system uses the original cookie name sid in its logic, you need to change it to the new name _USER_SESSION_ID, or set the parameter export SESSION_COOKIE_NAME=sid (the original cookie name).

Version impact: 4.5.15 and earlier, 5.0.0~5.0.8, 5.1.0~5.1.4. Other versions are not affected.

6.0+ Initial Upgrade Health Check Configuration

The upgrade and migration process for version 6.0.0 can be time-consuming. The duration varies depending on the size of the metadb, CPU performance, and disk I/O performance. For example, upgrading a metadb of 40GB (75,000 dashboards, 430,000 charts) on a Xeon W-2191B @ 2.30GHz with a standard cloud SSD takes approximately 15 minutes. It is recommended to disable the health check before performing a major upgrade to 6.0+ for the first time, and restore the health check after the upgrade and successful startup. Below are modification suggestions for different deployment methods:

2-1 Disable Health Check

[Standalone and Cluster Deployment]

Stop the monit monitoring service

${HENGSHI_HOME}/bin/hengshi-sense-bin stop monit
# {HENGSHI_HOME} is the directory variable where hengshi is installed. Do not copy and execute directly.

[Docker Deployment]

Comment out the healthcheck section for hengshi in the docker-compose file, then start the hengshi service

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

[K8s Deployment]

Comment out the following three items in the hengshi-sense deployment manifest, then start 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 Restore Health Check After Success

[Standalone and Cluster Deployment]

Restore the monit monitoring service

${HENGSHI_HOME}/bin/hengshi-sense-bin start monit
# {HENGSHI_HOME} is the directory variable where hengshi is installed. Do not copy and execute directly.

[Docker Deployment] and [K8s Deployment]

Restore the content that was commented out during the shutdown phase, then restart the hengshi service.

Version Impact Scope: The first upgrade from a version 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 version 6.0+ are not affected by this when performing subsequent major upgrades (i.e., 6.0.x -> 6.1.0 is not affected by this item). There is no need to disable the health check for the first upgrade.

6.0+ Nginx Configuration Modification

Starting from version 6.0.0, the frontend has optimized the caching logic for static files. Accordingly, you need to add cache configuration for entry static files in the reverse proxy in front of HENGSHI SENSE. Taking nginx as an example, add the following to the server block of HENGSHI SENSE:

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 require corresponding logic configuration

Version impact scope: Upgrading from versions prior to 6.0.0 to 6.0.0+