Writing a gbase.yml configuration from scratch is easier when you understand why each section exists. Instead of copying a template and changing IP addresses, this guide walks through the configuration of a three-node, single-HA-group deployment for GBase Database(GBase 8c).

The example covers the environment, control plane, GTM, coordinators, and data nodes, explaining the purpose of each component along the way.

1. Start with the Environment Configuration

Every deployment begins with the env section. It defines the package location, installation directory, software version, installation user, and SSH settings.

env: cluster_type: multiple-nodes pkg_path: /home/gbase/gbase_package prefix: /home/gbase/gbase_db version: V6_S1.0.0_B20 user: gbase port: 22 third_ssh: false

Before proceeding, verify three things:

  • pkg_path points to the extracted GBase Database installation package.
  • prefix is an empty installation directory owned by the gbase user.
  • version matches the actual package version.

The multiple-nodes setting describes the distributed deployment mode, not the number of physical hosts.

2. Configure the Control Plane: gha_server and DCS

The next section defines the cluster management components.

A single-HA-group deployment uses two gha_server instances and three DCS nodes.

gha_server: - gha_server1: { host: 10.x.x.6, port: 20001 } - gha_server2: { host: 10.x.x.8, port: 20001 } dcs: - { host: 10.x.x.6, port: 2379 } - { host: 10.x.x.7, port: 2379 } - { host: 10.x.x.8, port: 2379 }

The two gha_server instances provide management-service redundancy, while the three DCS nodes provide an odd-sized quorum configuration.

Three DCS nodes allow the cluster to maintain a majority when one node becomes unavailable.

Check that all three DCS nodes can communicate with one another and that their configured addresses match the actual control-plane network.

3. Configure GTM Primary and Standby

GTM handles global transaction management. This example defines one primary and one standby instance.

gtm: - gtm1: { host: 100.x.x.6, agent_host: 10.x.x.6, role: primary, port: 6666, agent_port: 36667 } - gtm2: { host: 100.x.x.7, agent_host: 10.x.x.7, role: standby, port: 6666, agent_port: 46667 }

Notice the two different network addresses:

  • host: The data-plane address used for database communication.
  • agent_host: The control-plane address used for communication with management components.

The two GTM instances have different agent_port values, even though their database service ports are both 6666.

This separation is important when configuring dual-NIC servers. Verify that the data-plane and control-plane addresses are reachable through their intended networks.

4. Configure the Coordinator Nodes

The coordinator layer provides SQL entry points for client connections.

A three-node single-HA-group deployment uses three CN instances. CN instances are configured as primary entry points rather than using the GTM-style primary/standby role arrangement.

The following shows the first CN configuration:

coordinator: - cn1: { host: 100.x.x.8, agent_host: 10.x.x.8, role: primary, port: 5432, proxy_port: 6001, agent_port: 8003 } # Add cn2 and cn3 using their actual host and agent_host addresses. # Follow the official single-HA-group example for their port assignments.

Do not stop after defining cn1. Complete all three coordinator entries using the actual addresses and port assignments for your environment.

The coordinators provide parallel SQL entry points, while data consistency and replication are handled at the data-node layer.

5. Configure the DN Group and Three Replicas

This is the most important part of the single-HA-group configuration.

The example defines one DN group containing three instances: one primary and two standby replicas.

datanode: - dn1: - dn1_1: { role: primary, port: 15432, proxy_port: 7001, agent_port: 27002, az: 'az1' } - dn1_2: { role: standby, port: 15432, proxy_port: 17001, agent_port: 27002, az: 'az1' } - dn1_3: { role: standby, port: 15432, proxy_port: 17001, agent_port: 27002, az: 'az2' }

The three instances have different responsibilities:

  • dn1_1: Primary DN.
  • dn1_2: First standby replica.
  • dn1_3: Second standby replica.

The az field defines the availability-zone placement.

In this example, two replicas are placed in az1, while the third is placed in az2.

This arrangement can tolerate an individual host failure, assuming the remaining nodes and replication state are healthy. However, losing the entire az1 zone removes two of the three replicas, so the remaining zone cannot retain a majority.

Availability-zone placement should therefore reflect the actual failure-domain requirements of the production environment.

6. Review the Configuration Before Installation

Writing the YAML file is only the first step. Before installing GBase Database(GBase 8c), review the configuration systematically.

Four checks are particularly important:

Check 1: Host addresses

Verify every host and agent_host entry. Make sure each address belongs to the intended network and that the corresponding nodes can communicate.

Check 2: Port assignments

Review GTM, CN, and DN service ports, proxy ports, and agent ports. Check for conflicts between instances running on the same host.

Check 3: Availability zones

Confirm that all DN replicas have the intended az assignments and that the distribution matches the failure-domain design.

Check 4: Installation directory

Make sure prefix is empty and has the correct ownership and permissions.

Also verify the YAML syntax and indentation. YAML is indentation-sensitive, and an incorrectly nested DN group can prevent the installer from interpreting the intended topology.

7. Why Configuration Accuracy Matters

The gbase.yml file is more than an installation parameter list. It declares the intended GBase Database cluster architecture.

A missing DN replica, incorrect port, or misplaced availability-zone setting can change the resulting deployment.

A successful environment check does not guarantee that the configuration describes the correct topology.

The recommended workflow is:

  1. Select the official single-HA-group configuration example.
  2. Replace IP addresses, hostnames, and directories.
  3. Complete all GTM, CN, and DN entries.
  4. Verify replica counts, ports, and availability zones.
  5. Check YAML syntax and installation directory state.
  6. Run the pre-installation checks before starting deployment.

Once the configuration is correct, the installation process becomes much more predictable.

The goal is not simply to make gha_ctl install succeed. It is to make sure GBase Database(GBase 8c) is deployed with the architecture you actually designed.