Version Upgrade Notes

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

Upgrading to 6.3.2: Mandatory Password Change Fix and Open Data Warehouse Removal

IMPORTANT

Applies when upgrading from a version earlier than 6.3.2 to 6.3.2 or a later 6.3.x release. Before upgrading, check self-service password change integrations, warehouse engine configuration, and existing open data warehouse accounts.

Mandatory Password Change

Version 6.3.2 fixes a bypass that allowed users signed in with HENGSHI local accounts to call regular business APIs before completing a mandatory password change. It does not introduce a new password policy. After upgrading, local login sessions with an unchanged initial password or an expired password can only change the password or log out. Users must complete the password change to resume regular business access. SSO/LDAP and access token authentication are not affected by this restriction.

• Users of the HENGSHI interface should follow the on-screen prompts to change their password before continuing.
• Integrations that use the old user profile API for self-service password changes must switch to the dedicated password change API during the upgrade. Refer to the self-service password change section in the API manual supplied for the target version for definitions, parameters, and examples. The old user profile API no longer accepts password change requests.
• The administrator password reset workflow is unchanged.

Open Data Warehouse Management Removal

Version 6.3.2 removes the open data warehouse management menu and related APIs. Complete these checks before upgrading:

1. Stop integration workflows that depend on the open data warehouse management menu or related APIs. These entry points can no longer be used to manage warehouse accounts after upgrading.
2. Check deployment scripts and external configuration for OPEN_DW_TYPE. This setting has been removed. Check that the existing ENGINE_TYPE setting matches the actual engine type. If only OPEN_DW_TYPE was configured, or the two values differ, set ENGINE_TYPE to the actual engine type (for example, greenplum) before upgrading. No migration is needed if ENGINE_TYPE already matches the actual engine.
3. Remove the obsolete OPEN_DW_TYPE, OPEN_DW_USER, and OPEN_DW_DB settings.
4. Review existing open data warehouse accounts and their consumers. The upgrade does not automatically disable these accounts or revoke their privileges. A database administrator must disable accounts or revoke privileges manually when they are no longer needed.

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

Upgrading from 6.1 to 6.2 or later

Starting from 6.2, the k8s configuration package includes hengshi-rbac.yaml, which grants the default ServiceAccount namespaces/get permission. You must complete the following two steps during upgrade, otherwise the hengshi container will fail due to insufficient permissions.

1. Replace the namespace placeholder

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

2. Apply the RBAC configuration

kubectl -n <namespace> apply -f hengshi-rbac.yaml

TIP

hengshi-rbac.yaml is located inside the k8s configuration package of the target version. For the full deployment procedure, see Kubernetes Deployment Guide.