Managing a Cluster's JSON File

Please note that the .json file details shared on this page apply to Spock version 4.0; .json management techniques are the same for earlier versions, but file content and organization will differ.

Each pgEdge Platform cluster has a .json cluster configuration file located in the cluster directory under the pgEdge Platform installation. The file is named cluster_name.json, and contains configuration details for the cluster. You can use a cluster configuration file when deploying or modifying a cluster to simplify the process.

If you have not yet deployed a cluster but wish to, you can use the pgedge cluster json-template command to create a .json template file and define the configuration of your replication cluster. After creating and modifying the template, you can use it to create a pgEdge cluster that matches the definition. The command syntax to create a template is:

./pgedge cluster json-template cluster_name db_name node_count db_superuser password pg_version port

When you invoke the command, specify the following values for the arguments:

• cluster_name is the name of the cluster. A directory with this same name will be created in the cluster directory; the file describing the cluster configuration will be named cluster_name.json.
• db_name is the name of your PostgreSQL database.
• node_count specifies the number of nodes that will be in the cluster. Nodes will be named n1, n2, n3, etc.
• db_superuser specifies the username of the PostgreSQL database owner/superuser that will be created for this database.
• password is the password of the database superuser.
• pg_version specifies the PostgreSQL version of the database; choose from versions 14, 15, and 16.
• port specifies the port number of the first node created in this cluster.

Example: Creating a JSON Cluster Configuration File

The pgEdge Platform cluster json-template command creates a JSON file that you can modify and use to deploy a pgEdge cluster. To create a template, first, install the pgEdge Platform (opens in a new tab), and then navigate into the pgedge directory and invoke the following command:

./pgedge cluster json-template demo lcdb 3 lcusr 1safepassword 16 6432

The command creates a file named demo.json in cluster/demo directory that describes a 3 node cluster that replicates a PostgreSQL 16 database named lcdb. The first node of the cluster (n1) is listening on port 6432; when you edit the .json file, you'll specify the port numbers that will be used by n2 and n3. The database superuser is named lcusr, and the associated password is 1safepassword.

The resulting demo.json file will look like this:

{
   "json_version":1.0,
   "cluster_name":"cluster1",
   "log_level":"info",
   "update_date":"2024-07-11 08:56:55GMT",
   "pgedge":{
      "pg_version":"16",
      "auto_start":"off",
      "spock":{
         "spock_version":"4.0",
         "auto_ddl":"off"
      },
      "databases":[
         {
            "db_name":"lcdb",
            "db_user":"lcusr",
            "db_password":"lcpasswd"
         }
      ]
   },
   "backrest":{
      "stanza":"demo_stanza",
      "repo1-path":"/var/lib/pgbackrest",
      "repo1-retention-full":"7",
      "log-level-console":"info",
      "repo1-cipher-type":"aes-256-cbc"
   },
   "node_groups":[
      {
         "ssh":{
            "os_user":"pgedge",
            "private_key":""
         },
         "name":"n1",
         "is_active":"on",
         "public_ip":"12.34.56.78",
         "private_ip":"10.1.2.3",
         "port":"6432",
         "path":"/home/pgedge/demo/n1",
         "sub_nodes":[
         ]
      },
      {
         "ssh":{
            "os_user":"pgedge",
            "private_key":""
         },
         "name":"n2",
         "is_active":"on",
         "public_ip":"12.34.56.34",
         "private_ip":"10.1.2.5",
         "port":"6432",
         "path":"/home/pgedge/demo/n2",
         "sub_nodes":[
         ]
      }
   ]
}
 

Modifying a JSON Cluster Configuration File

Properties within the cluster configuration file describe a cluster:

Validating a JSON File

After updating the .json file, you can use the pgedge cluster json-validate command to verify that your file is structured properly. The syntax is:

    ./pgedge cluster json-validate cluster_name

For example, the following command validates the .json file that creates a cluster named demo.

    ./pgedge cluster json-validate demo
    JSON defines a 3 node cluster

Note: The validate command checks only the structure of the .json file; it does not validate the values you provide.