GBase Database(GBase 8c) uses a single YAML configuration file, gbase.yml, as the input for cluster deployment. The three official deployment layouts share the same basic structure but differ in how high-availability components, coordinators, and data nodes are defined.

Once you understand how these YAML sections map to the cluster architecture, configuring a deployment becomes much more predictable. Instead of copying an existing configuration and deleting fields, you can select the correct topology and describe it explicitly.

This tutorial compares the three layouts and explains the key differences in their gbase.yml configurations.

1. Start With the Shared YAML Structure

All three deployment layouts use the same six top-level sections:

  • gha_server
  • dcs
  • gtm
  • coordinator
  • datanode
  • env

The environment section also follows a common structure:

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

These settings define the cluster type, installation package location, installation directory, software version, deployment user, SSH port, and SSH configuration.

The important distinction is that the shared skeleton does not mean the three deployments have identical component layouts.

2. Compare the Three GBase Database Deployment Layouts

The main structural differences are concentrated in three areas:

Component Minimal layout Single-HA-group layout Default distributed layout
gha_server instances 1 2 1
Coordinator instances 1 3 2
DN groups 1 1 2
DN instances 1 3 6

The most important difference is the datanode section.

It determines how data nodes are grouped, how instances are assigned primary or standby roles, and how the cluster's data topology is organized.

Layout 1: Minimal Single-Node Deployment

The minimal layout contains one DN group with one primary instance.

datanode: - dn1: - dn1_1: role: primary port: 15432

This is the simplest topology and is suitable for initial deployment and functional validation.

There is only one data node instance, so this configuration does not provide data-node redundancy.

Layout 2: Single-HA-Group Deployment

The single-HA-group layout keeps one DN group but introduces three instances:

  • One primary.
  • Two standby instances.
  • Three availability-zone assignments. 
datanode: - dn1: - dn1_1: { role: primary, port: 15432, az: 'az1' } - dn1_2: { role: standby, port: 15432, az: 'az1' } - dn1_3: { role: standby, port: 15432, az: 'az2' }

The key difference is that all three instances belong to dn1.

The role field distinguishes primary and standby instances, while az identifies their availability-zone placement.

This layout introduces high availability without changing the number of DN groups.

Layout 3: Default Distributed Deployment

The default distributed layout introduces two DN groups, each containing three instances.

datanode: - dn1: - dn1_1: { role: primary, port: 15432 } - dn1_2: { role: standby, port: 15433 } - dn1_3: { role: standby, port: 15433 } - dn2: - dn2_1: { role: primary, port: 20010 } - dn2_2: { role: standby, port: 20010 } - dn2_3: { role: standby, port: 20010 }

There are six DN instances in total:

  • dn1 contains one primary and two standby instances.
  • dn2 contains one primary and two standby instances.

Notice two important differences from the single-HA-group example.

First, the official distributed example does not declare az.

Second, it does not declare proxy_port.

These differences matter when selecting the correct configuration template. Do not assume that fields from one topology can be copied into another without checking the corresponding deployment specification.

3. Understand the Difference Between DN Groups and DN Instances

This is the most important concept when reading gbase.yml.

A DN group is not the same as a DN instance.

For example:

datanode: - dn1: - dn1_1: { role: primary, port: 15432 } - dn1_2: { role: standby, port: 15433 } - dn1_3: { role: standby, port: 15433 }

Here, dn1 represents one DN group, while dn1_1, dn1_2, and dn1_3 represent its three instances.

Adding another instance to an existing group and introducing another DN group are different topology operations.

This distinction is essential for GBase Database capacity planning and future cluster expansion.

4. Run the Pre-installation and Deployment Commands in Order

After editing gbase.yml, follow the deployment sequence.

First, perform the SSH and user preparation checks:

cd /home/gbase/gbase_package/script/ ./gha_preinstall -s \ --root-passwd="***" \ --set-user-passwd="***" \ -f /home/gbase/gbase.yml

Next, run the comprehensive environment checks:

./gha_preinstall -i A \ -f /home/gbase/gbase.yml

Then execute the environment configuration and repair stage:

./gha_preinstall -i B \ -f /home/gbase/gbase.yml

Finally, install the cluster:

./gha_ctl install -p /home/gbase/ -c gbase

Each stage has a different purpose:

  1. -s prepares SSH access and user configuration.
  2. -i A performs the comprehensive pre-installation checks.
  3. -i B executes the supported automatic environment adjustments.
  4. gha_ctl install starts the cluster installation process.

Do not treat these commands as interchangeable. Complete the required checks and configuration steps before starting installation.

5. Two Configuration Details That Are Easy to Miss

Detail 1: Do Not Mix Fields Between Deployment Templates

The default distributed example does not contain proxy_port or az.

Avoid copying another topology and deleting fields based on assumptions. Additional fields are not guaranteed to be ignored by the configuration parser or deployment process.

Start with the official example matching your target architecture, then modify the values required by your environment.

Detail 2: Assign host and agent_host According to the Network Design

The host and agent_host fields must reflect the actual dual-NIC network plan.

In the deployment design described here:

  • host corresponds to the data-plane network.
  • agent_host corresponds to the control-plane network.

Reversing these assignments can cause network interface validation to fail at A11.

Check the actual IP assignments and routing configuration on every host before generating the final YAML file.

6. Treat gbase.yml as Deployment Documentation

The biggest advantage of a declarative deployment configuration is repeatability.

For GBase Database(GBase 8c), gbase.yml describes the intended cluster structure:

  • Which hosts participate in the deployment.
  • Which components run on each host.
  • How coordinator instances are organized.
  • How DN groups and instances are structured.
  • Which roles and ports are assigned.

A deployment should not depend on undocumented assumptions or manual changes made during installation.

When the YAML configuration accurately reflects the intended topology, it becomes more than an installation input. It becomes a technical record of the architecture.

The key to reliable GBase Database deployment is understanding the topology before editing the YAML—not trying to fix the topology after installation.