TIL: Map the Node Roles Before Installing GBase Database

When reviewing a GBase Database(GBase 8a) cluster installation, I once saw three host lists that looked like unrelated inventories: three scheduling nodes, four data nodes, and three GCware nodes.

The problem wasn't necessarily the number of machines. It was the assumption that each list represented a completely separate group of servers.

With GBase Database(GBase 8a MPP Cluster), the first step in a cluster deployment should be to map the node roles before running the installer.

1. Understand the Three Host Lists in demo.options

The host lists in demo.options describe different cluster roles. They are not necessarily three independent pools of machines.

• coordinateHost: Hosts running GCluster, which handles SQL requests and coordinates distributed query execution.
• dataHost: Hosts running GNode, which provides data storage and query execution.
• gcwareHost: Hosts running GCware, which manages cluster metadata, topology, and consistency-related coordination.

Depending on the deployment architecture, one machine may serve multiple roles. The actual role assignment must follow the requirements of the target GBase Database release and cluster design.

Here is an illustrative configuration:

installPrefix = /opt
coordinateHost = 192.168.146.20,192.168.146.21,192.168.146.22
coordinateHostNodeID = 20,21,22
dataHost = 192.168.146.20,192.168.146.21,192.168.146.22,192.168.146.23
gcwareHost = 192.168.146.20,192.168.146.21,192.168.146.22
gcwareHostNodeID = 20,21,22
dbaUser = gbase
dbaGroup = gbase

This example shows three hosts assigned both coordinator and GCware roles, with four hosts listed for data services. It is an example of role mapping, not a universal production topology.

Before copying it into your environment, confirm the required host-list format and NodeID rules in the documentation for your specific GBase Database version.

2. Check IP Addresses, Hostnames, and NodeIDs

A role map is only useful when its entries correspond to real, reachable machines.

If the configuration uses IP addresses, verify that each address belongs to the intended host and that the required network connections work.

If it uses hostnames, check name resolution on every relevant node. The hostnames must resolve consistently to the intended addresses, and SSH connectivity must work wherever the installer requires remote access.

NodeID handling also deserves attention. Some configurations derive or assign IDs according to release-specific rules, but you should not assume that an IP address's last octet is always the correct NodeID. Check the target release's demo.options example and installation manual.

Two common configuration mistakes are:

• A host appears in dataHost, but the associated role or NodeID configuration does not match the intended cluster topology.
• An IP address changes while a related node identifier or other configuration entry remains unchanged.

Either can cause problems during installation or cluster registration, depending on the release and deployment state.

3. Validate the Role Map Before Installation

Before starting a GBase Database cluster installation, create a simple table:

Host or IP	GCluster	GNode	GCware
192.168.146.20	Yes	Yes	Yes
192.168.146.21	Yes	Yes	Yes
192.168.146.22	Yes	Yes	Yes
192.168.146.23	No	Yes	No

Treat this as a planning worksheet, not a recommended topology for every production system.

Then verify three things:

1. Role consistency: The entries in coordinateHost, dataHost, and gcwareHost match the intended deployment.
2. Network reachability: Each listed host exists, resolves correctly where hostnames are used, and is reachable through the required network paths.
3. Remote access: SSH authentication and permissions meet the installer's requirements for the relevant accounts.

A single-node or small test deployment can help validate installation parameters, but it does not prove that a multi-node production topology, network configuration, or high-availability design is correct.

4. Diagnose Failures by Installation Stage

When a GBase Database installation fails, identify the stage before changing configuration.

• Configuration validation: Check host-list syntax, required fields, and NodeID definitions.
• Remote distribution or login: Check SSH access, name resolution, account permissions, and connectivity.
• Cluster registration: Compare the configured roles with the nodes already installed and the cluster's actual state.

The key is not to assume that every failure comes from a mismatch between the three lists. Review the installer output and the relevant node logs to identify the actual cause.

5. What If the Cluster Is Already Partially Installed?

If the installation has already progressed partway, editing demo.options alone may not resolve the problem. The configuration file may no longer describe the state of the nodes already installed or registered.

First, document:

• Which nodes have been installed successfully
• Which services and roles are present on each node
• Which nodes failed and at what stage
• Whether the cluster has already registered those nodes

Then determine whether the appropriate recovery path is to rerun the installation or add nodes to the existing cluster. For a supported node-add operation, follow the release-specific procedure and configuration format, including gcChangeInfo.xml where required.

Avoid rebuilding the entire cluster or modifying registration settings until you understand the existing state and the supported recovery procedure.

Final Takeaway

For GBase Database(GBase 8a MPP Cluster), demo.options is more than an installation parameter file. It describes how hosts are assigned to cluster roles.

Map the hosts first, validate connectivity and identifiers, and only then start the installation. A few minutes spent checking the role map can prevent much more expensive troubleshooting later.

Always confirm the exact configuration rules against the documentation for your GBase Database release.