Configure XRegion Service

Before creating any MR Table, you must deploy an XRegion Service. In simple terms, this is also called an agent. The XRegion Service runs independently with the local KVStore and it is recommended to deploy it close to the local KVStore. To know more about agent and agent groups, see Cross-Region Service in the Concepts Guide.

Steps:

To configure the XRegion Service, execute the following tasks in each region:

Create a home directory for the XRegion Service.

Create a JSON config file in the home directory created in the step 1. The structure of the json.config file is shown below.

{
  "path" : "<entire path to the home directory for the XRegion Service>",
  "agentGroupSize" : <number of service agents>,
  "agentId" : <agent id using 0-based numbering>,
  "region" : "<local region name>",
  "store" : "<local store name>",
  "helpers" : [ 
    "<host1>:<port>",
    "<host2>:<port>",
    …
    "<hostn>:<port>"
  ],
  "security" : "<entire path to the security file of the local store>",
  "regions" : [ 
    {
        "name" : "<remote region name>",
        "store" : "<remote store name>",
        "security" : "<entire path to the security file of the remote store>",
        "helpers" : [
            "<host1>:<port>",
            "<host2>:<port>",
            …
            "<hostn>:<port>
         ]
    },
    {
        "name" : "<remote region name>",
        "store" : "<remote store name>",
        "security" : "<entire path to the security file of the remote store>",
        "helpers" : [ 
            "<host1>:<port>",
            "<host2>:<port>",
            …
            "<hostn>:<port>
        ]
    }, 
    ...
  ]
  "durability" : "<durability setting>"
}

Where each attribute in the json.config file is explained below:

path This is the root directory of the XRegion Service. The agents use this directory to dump logs, statistics and other auxiliary files. The directory shall be readable and writable to the agents.

agentGroupSize and agentId

Specifies the number of service agents and the Agent ID in the agent group. The Agent ID is specified as numbers starting from 0. These details are used to form a group of agents that serve the local region. Forming a group of agents achieves horizontal scalability.

Note:

The current release supports only a single service for each local region. Therefore the agentGroupSize is set to 1 and the agentId is set to 0.

security Specifies the security file used by the agent. This attribute must be defined for the local store as well as the remote stores.

region Specifies the local region name defined for the region where you are configuring the agent.

store Specifies the name of the store in the local region.

helpers Specifies the list of host and port numbers used for configuring the local store. These helper hosts are those you used to create a KV client. For XRegion Service to connect to the local and remote regions, each region's firewall must be configured to open the registry port and HA ports.

regions

After defining the local region, you must define a list of remote regions. At least one remote region shall be defined in order to create an MR Table.

Specifies the region name, store name, and helper hosts for each remote region you want to include.

Note:

The remote region names listed here must be same as the local region names defined for them.

durability

This is an optional parameter. It specifies the durability setting for Master commit synchronization. The possible values are:

COMMIT_NO_SYNC
COMMIT_SYNC
COMMIT_WRITE_NO_SYNC

The default durability setting is COMMIT_NO_SYNC.

Grant the following privileges to the XRegion Service Agent:
- Write permission to system table
- Read and Write permission to all the user tables
```
— create role for the agent -- 
CREATE ROLE <Agent Role>

— grant privileges to the role --   
GRANT WRITE_SYSTEM_TABLE to <Agent Role>
GRANT READ_ANY_TABLE to <Agent Role>
GRANT INSERT_ANY_TABLE to <Agent Role>

— grant role to the agent user -- 
GRANT <Agent Role> to user <Agent User>
```
Note:
This step is required only for secure KVStores. In a non-secure KVStore setup, this step can be skipped.

Example:

Create a json.config file for each proposed region, Frankfurt and London.

# Contents of the configuration file in the 'fra' Region
{
  "path": "<path to the json config file>",
  "agentGroupSize": 1,
  "agentId": 0,
  "region": "fra",
  "store": "<storename at the fra region>",
  "security": "<path to the security file>",
  "helpers": [
    "host1:5000",
    "host2:5000",
    "host3:5000"
  ],
  "regions": [
    {
      "name": "lnd",
      "store": "<storename at the lnd region>",
      "security": "<path to the security file>",
      "helpers": [
        "host4:5000",
        "host5:5000",
        "host6:5000"
      ]
    }
  ]
}

# Contents of the configuration file in the 'lnd' Region
{
  "path": "<path to the json config file>",
  "agentGroupSize": 1,
  "agentId": 0,
  "region": "lnd",
  "store": "<storename at the lnd region>",
  "security": "<path to the security file>",
  "helpers": [
    "host4:5000",
    "host5:5000",
    "host6:5000"
  ],
  "regions": [
    {
      "name": "fra",
      "store": "<storename at the fra region>",
      "security": "<path to the security file>",
      "helpers": [
        "host1:5000",
        "host2:5000",
        "host3:5000"
      ]
    }
  ]
}