Mastering Inceptor Server HA: Configuration, Failover, and Best Practices

Inceptor Server HA Overview

High availability (HA) is crucial for system clusters. Inceptor Server HA, introduced in TDH 4.7, allows multiple server nodes (Active and Standby) coordinated by Zookeeper to ensure seamless failover and improve service reliability.

Implementation Principles and Limitations

Only one Master Inceptor Server runs with YARN resources; standby nodes do not request resources, preventing waste. HA works only with YARN as the resource manager and supports only HiveServer2. It can coexist with multi‑active Inceptor servers, but only the master provides services.

HA supports only YARN as the resource framework.

HA can coexist with multi‑active servers, yet only the master utilizes resources.

Multiple Inceptor services on a single machine must belong to different HA groups.

Each standby server requires an additional Application Master to manage YARN resources.

HA is compatible solely with HiveServer2.

Configuration Process

Configuring HA involves two steps: setting up multiple Inceptor Server roles and enabling HA.

Configure Multiple Inceptor Servers

When creating a new Inceptor service, select two or more server roles. After creation, the role page displays the added servers.

For an existing service, verify that multiple server roles exist; if not, add a new Inceptor Server role via the role page.

Enable HA

Set the following parameters in the Manager configuration page (add custom parameters if needed):

inceptor.ha.enabled : default false; set to true to enable HA.

inceptor.ha.groupid : group ID, usually the Inceptor SID (e.g., Inceptorsql1).

inceptor.ha.impl : default implementation io.transwarp.inceptor.ha.ZKHAManager (Zookeeper‑based).

inceptor.ha.heartbeat.type : "version" or "timestamp" method for heartbeat timeout.

hive.zookeeper.quorum : Zookeeper node list used by Inceptor.

After setting these parameters, restart all Inceptor servers in the same HA group. The HA status page (port 4040) shows the master and standby states.

Connection String

Use a JDBC URL that lists both server hostnames to enable automatic failover, for example:

beeline -u jdbc:hive2://leviathan1:10000,leviathan2:10000/default

Connecting to a single address does not trigger failover.

Failover Behavior

When a server switch occurs, any running query fails and must be re‑executed; the client replays session settings to preserve the current database and Hive configuration. Transactions are rolled back on the standby before it becomes master; if rollback fails, the standby exits. Beeline scripts abort on JDBC errors during failover.

HA Tools

Inceptor provides a command‑line utility to monitor and manage HA status, view the current master, and force a master switch.

java -cp /usr/lib/ngmr-shell/target/scala-2.10/ngmr-shell_2.10-1.1.0-transwarp-[TDH版本].jar -Djava.ext.dirs="/usr/lib/ngmr/lib_managed/jars:/usr/lib/zookeeper" io.transwarp.inceptor.ha.HATools [options]

Examples of checking status and forcing a master switch are illustrated in the screenshots.

Conclusion

Inceptor Server HA significantly improves service stability by ensuring transparent node switching and maintaining consistency of queries and transactions, thereby enhancing the overall quality and reliability of the TDH platform.