Configuration

The PTK configuration file is in the YAML format.

This file describes all the parameters of the topology configuration file.

When installing a database cluster, a user-supplied configuration file describing the cluster topology is required to tell PTK what structure the cluster should follow.

PTK provides the ability to create profiles interactively, and the interactive process can be accessed by running the following command:

ptk template create

You just need to follow the steps prompted by the terminal step by step to complete the configuration, and the config.yaml file will eventually be generated in the current folder.

Alternatively, if you want to generate a file with the default configuration without using interactive creation, you can run the following command:

ptk template > config.yaml

After running this command, the system will generate a config.yaml file, and you need to modify the values of the fields in the file according to your actual situation.

For non-interactive modification, sensitive fields such as user_password, db_password, ssh_option.password or ssh_option.passphrase must be encrypted using the encryption command provided by PTK.

ptk encrypt PASSWORD

Config

Database cluster topology configuration information

Examples:

• Simple configuration

# Cluster configuration information, in which db_port and ssh_option are reusable fields
global:
    cluster_name: cluster_simple # Cluster name, a unique identifier of the cluster managed by PTK
    db_password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= # The initial user password for the database, which is requested interactively during installation if not filled in the configuration file
# Configuration information of database instance servers in a cluster
db_servers:
    - host: <ip1> # IP address of the database instance server (only supporting IPv4)
    - host: <ip2> # IP address of the database instance server (only supporting IPv4)
# CM server list in a cluster
cm_servers: []

• Complex configuration

# Cluster configuration information, in which db_port and ssh_option are reusable fields
global:
    cluster_name: cluster_complex # Cluster name, a unique identifier of the cluster managed by PTK
    user: omm # System username for running a database
    group: omm # System user group for running a database
    db_password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= # Initial database user password. If this password is not specified in the configuration file, it needs to be entered during database installation according to the terminal prompts.
    base_dir: /opt/mogdb # Base directory of database installation. It is recommended that this directory that can be accessed by the SSH user in the configuration file and is automatically created by PTK.
    # List of additional new HBA entries
    extra_hba_conf:
        - type: host # Connection type, supports local/host/hostssl/hostnossl
          database: all # Specify the name of the database this record matches
          user: all # Specify the usernames of the database this record matches
          address: <ip3> # Required, specifies the address of the client machine this record matches
          method: sha256 # Specify the authentication method to use when a connection matches this record
    # MogDB HA component CM configuration information. If the CM component is not used, leave this field empty.
    cm_option:
        dir: /opt/mogdb/cm # CM installation directory
        cm_server_port: 15300 # Listening port of the CM server 
        db_service_vip: "" # Virtual IP address for the database to provide service.
# Configuration information of database instance servers in a cluster
db_servers:
    - host: <ip1> # IP address of the database instance server (only supporting IPv4)
      db_port: 27000 # Database port
      role: primary # Database instance role, if not filled in, PTK will randomly select one instance as the primary database, and the rest will be the backup database automatically.
      az_name: BJ # Available Zone (AZ) name
      az_priority: 1 # AZ priority. The lower the value, the higher the priority. The minimum value is 1
      # SSH login information. The login user should be root or a user who has the sudo permission.
      ssh_option:
        port: 22 # SSH server port
        user: root # SSH login user
        password: pTk6LIBsPVplOpmxQToCPT9+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U= # Password of the SSH login user
        conn_timeout: 5m0s # SSH login timeout. The supported unit can be minute(m) and second(s).
        exec_timeout: 5m0s # Timeout of performing a single command in SSH. The supported unit can be minute(m) and second(s).
    - host: <ip2> # IP address of the database instance server (only supporting IPv4)
      db_port: 27000 # Database port
      role: standby # Database instance role, if not filled in, PTK will randomly select one instance as the primary database, and the rest will be the backup database automatically.
      az_name: BJ # Available Zone (AZ) name
      az_priority: 1 # AZ priority. The lower the value, the higher the priority. The minimum value is 1
      # SSH login information. The login user should be root or a user who has the sudo permission.
      ssh_option:
        port: 22 # SSH server port
        user: root # SSH login user
        key_file: ~/.ssh/id_rsa # SSH login key file path
        conn_timeout: 5m0s # SSH login timeout. The supported unit can be minute(m) and second(s).
        exec_timeout: 5m0s # Timeout of performing a single command in SSH. The supported unit can be minute(m) and second(s).
    - host: <ip3> # IP address of the database instance server (only supporting IPv4)
      db_port: 27000 # Database port
      role: cascade_standby # Database instance role, if not filled in, PTK will randomly select one instance as the primary database, and the rest will be the backup database automatically.
      upstream_host: <ip2> # When the instance role is cascade_standby, this field indicates the IP address of the upstream standby server.
      az_name: SH # Available Zone (AZ) name
      az_priority: 2 # AZ priority. The lower the value, the higher the priority. The minimum value is 1
# CM server list in a cluster
cm_servers:
    - host: <ip1> # IP address of the CM server (only IPv4 is supported.)
      port: 15300 # Listening port of the CM server
      role: ""
    - host: <ip2> # IP address of the CM server (only IPv4 is supported.)
      port: 15300 # Listening port of the CM server
      role: ""

global

Data type: Global

Description: Cluster configuration information, in which db_port and ssh_option are reusable fields.

Reusable Fields

• If this field is set in instance-level configuration, the instance-level configuration prevails.
• If this field is not set in instance-level configuration, the global-level configuration prevails.

Added in: v0.1

db_servers

Data type: []DBServer

Description: Configuration information of database instance servers in a cluster

Added in: v0.1

cm_servers

Data type: []CMServer

Description: CM server list in a cluster

Added in: v0.5

Global

Global defines global parameters in a configuration file.

Appears in:

• Config.global

cluster_name

Data type: string

Description: Cluster name that is the unique identifier of a cluster

Added in: v0.1

user

Data type: string

Description: System username for running a database

If you want to deploy a set of primary and standby databases on the same server, you need to set up different users at the instance level to isolate the environment.

The default value is omm.

Added in: v0.1

group

Data type: string

Description: System user group for running a database

The value is the same as the system username by default.

Added in: v0.1

user_password

Data type: string

Description: System user password for running a database

This field is not supported in plaintext, it needs to be encrypted with ptk encrypt.

This field is left blank by default.

Added in: v0.1

db_password

Data type: string

Description: Initial database user password. If this password is not specified in the configuration file, it needs to be entered during database installation according to the terminal prompts.

This field is not supported in plaintext, it needs to be encrypted with ptk encrypt.

Added in: v0.1

db_port

Data type: int

Description: Database port

If you want to deploy a set of primary and standby databases on a single server, you need to set different port numbers at the instance level.

The default value is 26000.

Added in: v0.1

base_dir

Data type: string

Description: Base directory of database installation. It is recommended that base_dir should be created by PTK automatically and it can be accessed by SSH user configured in a configuration file.

If PTK is run by a non-root user during database installation, the common user does not have permission to create directories in the /opt directory. Therefore, the default directory /opt/mogdb cannot be created due to the permission issue. The user should specify a path that can be accessed by the execution user.

After this directory is specified, PTK will automatically create corresponding directories under the installation directory if any of the app_dir, data_dir, log_dir, and tool_dir parameters are not configured.

Without special requirements, you are required to set this parameter only during installation.

Note: if a cluster is deployed in a single server, set different installation directories at the instance level.

The default value is /opt/mogdb.

Added in: v0.1

app_dir

Data type: string

Description: Directory for storing database deployment file, startup script, and configuration file.

The default value is ${base_dir}/app.

Added in: v0.1

data_dir

Data type: string

Description: Data directory of a database

The default value is ${base_dir}/data.

Added in: v0.1

log_dir

Data type: string

Description: Directory for storing database run logs and operation logs

The default value is ${base_dir}/log.

Added in: v0.1

tool_dir

Data type: string

Description: Database tool directory

The default value is ${base_dir}/tool.

Added in: v0.1

tmp_dir

Data type: string

Description: Temporary directory of a database

Default value: If base_dir is not empty, this value is ${base_dir}/tmp. Otherwise, this value is /tmp.

Added in: v0.1

core_file_dir

Data type: string

Description: [discarded in v0.7 or later] This parameter has been discarded. Please manually set kernel.core_pattern after switching to the super user.

Added in: v0.1

ssh_option

Data type: SSHOption

Description: SSH login information.

Runs locally when not set.

Added in: v0.1

gs_initdb_opts

Data type: []string

Description: Used for the user to initialize the database. If the user does not configure the locale parameter. PTK will automatically configure no-locale by default. For details about the supported parameter list, see gs_initdb.

Examples:

• gs_initdb_opts example

gs_initdb_opts:
    - --locale=LOCALE
    - -E=UTF-8

Added in: v0.3

extra_hba_conf

Data type: []HBAConf

Description: List of additional new HBA entries

Added in: v1.5

cm_option

Data type: CMOption

Description: MogDB CM configuration information. If CM is not used, this field can be left blank.

This field takes effect in MogDB 3.0 or later.

Added in: v0.4

dss_option

Data type: DSSOption

Description: MogDB resource pooling installation configuration information, for non-resource pooling installations, this field is not required.

Added in: v1.1.0

env_map

Data type: map[string]string

Description: Users can add specific environment variables as needed, setting them in global will take effect for all instances, the instance level can be set individually, if the same key exists, the value at the instance level will override the value in global, there is no need to fill in the field

Added in: v1.2.0

HBAConf

Configuration of HBAConf HBA entries

Appears in:

• Global.extra_hba_conf

Examples:

• hba config

type: host # Connection type, supports local/host/hostssl/hostnossl
database: all # Specify the name of the database this record matches
user: all # Specify the usernames of the database this record matches
address: <ip3> # Required, specifies the address of the client machine this record matches.
method: sha256 # Specifies the authentication method to use when a connection matches this record.

type

Data type: string

Description: Connection type, supports local/host/hostssl/hostnossl

For details, see client-access-authentication

Default Value: host

Added in: v1.5.0

database

Data type: string

Description: Specify the name of the database this record matches

Default Value: all

Added in: v1.5.0

user

Data type: string

Description: Specify the usernames of the database this record matches

Default Value: all

Added in: v1.5.0

address

Data type: string

Description: Required, specifies the address of the client machine this record matches.

If only one IPv4 or IPv6 address is set and no CIDR mask is configured, the CIDR mask used for IPv4 is 32 and for IPv6 is 128

Added in: v1.5.0

method

Data type: string

Description: Specifies the authentication method to use when a connection matches this record.
Default Value: sha256

Added in: v1.5.0

option

Data type: string

Description: Follows the method field, which can be a field such as name=value that specifies options for the authentication method.

Added in: v1.5.0

DSSOption

Appears in:

• Global.dss_option

dir

Data type: string

Description: DSS installation directory

Default Value: $base_dir/dss

Added in: v1.1.0

dss_port

Data type: int

Description: Listening port of dssserver process

Default Value: 26010

Added in: v1.1.0

dms_port

Data type: int

Description: Communication port of DMS module in database

Default Value: 26020

Added in: v1.1.0

shm_key

Data type: int

Description: Shared Memory KEY, in the range [1, 64], if multiple DSS clusters are deployed on a single machine, make sure that this value is different

Default Value: 1

Added in: v1.1.0

log_level

Data type: int

Description: DSS log level, in the range [0, 4087]

Default Value: 519

Added in: v1.1.0

data_vg_name

Data type: string

Description: Data volume group name.

Default Value: data

Added in: v1.1.0

data_vg_path

Data type: string

Description: Data volume group path.

Added in: v1.1.0

cm_voting_vg_path

Data type: string

Description: CM voting volume path.

Added in: v1.1.0

cm_share_vg_path

Data type: string

Description: CM shared volume path.

Added in: v1.1.0

inst_vg_map

Data type: map[string]string

Description: Private volume path dictionary for each database instance, required for complete configuration of all instances.

Configuration rule: {IP: vg_path, ...}

Examples:

• inst_vg_map example

inst_vg_map:
    1.0.0.1: /dev/sdb
    1.0.0.2: /dev/sdc

Added in: v1.1.0

enable_ssl

Data type: bool

Description: Enable or disable SSL authentication.

Default Value: off

Range: on/off

Added in: v1.1.0

inter_connect_type

Data type: string

Description: Internal MES communication protocol type

Default Value: TCP

Range: TCP/RDMA

Added in: v1.1.0

ss_guc_config

Data type: map[string]string

Description: Resource pooling GUC parameter configuration.

Range: See openGauss docs

Added in: v1.1.0

CMOption

Appears in:

• Global.cm_option

dir

Data type: string

Description: CM installation directory

Default Value: $base_dir/cm

Added in: v0.4

cm_server_port

Data type: int

Description: Listening port of the CM server

Default Value: 15300

Added in: v0.4

db_service_vip

Data type: string

Description: Virtual IP address for the database to provide services

Added in: v0.4

cm_server_conf

Data type: map[string]string

Description: Configuration parameters supported in cm_server.conf. PTK does not verify the accuracy and validity of the parameter.

Example:

• cm server conf

cm_server_conf:
    key: value

Added in: v0.4

cm_agent_conf

Data type: map[string]string

Description: Configuration parameters supported in cm_agent.conf. PTK does not verify the accuracy and validity of the parameter.

Example:

• cm agent conf

cm_agent_conf:
    key: value

Added in: v0.4

CMServer

CMServer configuration information

Appears in:

• Config.cm_servers

host

Data type: string

Description: IP address of the CM server (only IPv4 is supported).

Added in: v0.5

ha_ips

Data type: []string

Description: Database redundant IPs, consistent with the ha_ips in the db_server corresponding to the current host

Added in: v1.1.0

port

Data type: int

Description: Listening port of the CM Server

global.cm_option.cm_server_port is used by default.

Added in: v0.5

ssh_option

Data type: SSHOption

Description: SSH login information. The login user must be root or a user who has the sudo permission. If this parameter is not set, operation is performed locally.

Runs locally when not set.

Added in: v0.5

serverFlag

DBServer

Configuration information of database instance servers in the DBServer cluster

Appears in:

• Config.db_servers

dn_name

Data type: string

Description: Name of a database instance that is uniquely identified. The value will be configured in application_name.

The default value is dn_.

Added in: v1.0

host

Data type: string

Description: IP address of the database instance server (only supporting IPv4)

Added in: v0.1

user

Data type: string

Description: User name of the OS for running the database

If a set of primary and standby databases are to be deployed on the same server, the field need to be set up for different users

The default values are consistent with the global.user

Added in: v0.5

group

Data type: string

Description: Operating system user group running the database

The default values are consistent with the global.group

Added in: v0.5

user_password

Data type: string

Description: Password of the operating system user running the database

This field is not supported in plaintext, it needs to be encrypted with ptk encrypt.

The default values are consistent with the global.user_password

Added in: v0.5

db_port

Data type: int

Description: Database port

The field is left blank by default. The global port 26000 is reused.

Added in: v0.1

ha_ips

Data type: []string

Description: Database redundant IPs, a maximum of one redundant IP is currently configured, and if this field is configured, all instances need to configure it.

Added in: v0.1

ha_port

Data type: int

Description: Log replication port of primary/standby database instances. The value is fixed at a database port plus 1. This field is not required to be filled in.

Added in: v0.1

role

Data type: string

Description:

Range:

• primary
• standby
• cascade_standby

Added in: v0.1

upstream_host

Data type: string

Description: When the instance role is cascade_standby, this field indicates the IP address of the upstream standby server.

Added in: v0.1

az_name

Data type: string

Description: AZ name

The default value is AZ1.

Added in: v0.1

az_priority

Data type: int

Description: AZ priority. The lower the value, the higher the priority. The minimum value is 1.

The default value is 1.

Added in: v0.1

xlog_dir

Data type: string

Description: Directory for storing database xlog.

This field is left blank by default. If this field is configured, the value cannot be the subdirectory of the data directory.

Added in: v0.1

db_conf

Data type: map[string]string

Description: You can configure the database parameters as you need. This field configuration information will be written into the postgresql.conf file before the database is started.

Examples:

• db config example

db_conf:
    key: value

Added in: v0.1

env_map

Data type: map[string]string

Description: You can add specific environment variables for this instance as you need.

Added in: v1.2.0

ssh_option

Data type: SSHOption

Description: SSH login information. The login user must be root or a user who has the sudo permission.

Runs locally when not set.

Added in: v0.1

SSHOption

SSHOption: SSH login supports password and key authentication. You need to choose at least one.

Appears in:

• Global.ssh_option
• CMServer.ssh_option
• DBServer.ssh_option
• SSHOption.proxy

Examples:

host: <ip>
port: 22
user: root
key_file: ~/.ssh/id_rsa

host

Data type: string

Description: IP address of the target server to be connected

This field is mandatory when the host works as a jump server.

When the server has the database installed, this field can be left blank. The IP address of db_server will be used.

This field is left blank by default.

Added in: v0.1

port

Data type: int

Description: SSH service port

The default value is 22.

Added in: v0.1

user

Data type: string

Description: SSH login user

The default value is root.

Added in: v0.1

password

Data type: string

Description: SSH login user password

This field is not supported in plaintext, it needs to be encrypted with ptk encrypt.

Examples:

• ssh password example

password: pTk6MTIxOGMxOTk8QT1CPT4+PXlnYW1DdHpXb2hCX3c3UW0wWXVkNlZwMGRCakpxRXd1WWdwQ0xDUWVrb0U=

Added in: v0.1

key_file

Data type: string

Description: Directory for storing SSH login key files

This field is left blank by default.

Examples:

• ssh key file example

key_file: ~/.ssh/id_rsa

Added in: v0.1

passphrase

Data type: string

Description: SSH login key file password

This field is not supported in plaintext, it needs to be encrypted with ptk encrypt.

This field is left blank by default.

Added in: v0.1

conn_timeout

Data type: Duration

Description: SSH login connection timeout duration. The value unit can be minute or second.

Default Value: "1m"

Added in: v0.1

exec_timeout

Data type: Duration

Description: Timeout duration for executing a single command in SSH mode. The supported unit can be minute and second.

Default Value: "10m"

Added in: v0.1

proxy

Data type: SSHOption

Description: Jump server login information. If the target server cannot be connected directly, you can use a jump server for connection.

Added in: v0.1