Each XRegion Service group consists of a group of independent XRegion Service agents, and each agent in the group is running on a host node and is responsible to handle one or more shards of the data store. The agents in XRegion Service Group are completely independent of each other, that is, each agent does not talk directly to any other agent in the group. Any agent can be shut down and restarted without impacting other agents. It is recommended that you add XRegion Service agents on individual hosts that do not contain any Storage Node configured.

Steps:

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

1. Create a home directory for the XRegion Service.
2. 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.
   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.

3. Grant the following privileges to the XRegion Service Agent:
   • CREATE_ANY_TABLE
   • Write permission to system table
   • Read and Write permission to all the user tables
   • DELETE_ANY_TABLE

   Note:

   Inserting data into a Multi-Region table (using a put operation) requires both INSERT and DELETE privileges.

   — create role for the agent -- 
   CREATE ROLE <Agent Role>
   
   — grant privileges to the role --   
   GRANT CREATE_ANY_TABLE to <Agent Role>
   GRANT WRITE_SYSTEM_TABLE to <Agent Role>
   GRANT READ_ANY_TABLE to <Agent Role>
   GRANT INSERT_ANY_TABLE to <Agent Role>
   GRANT DELETE_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 data stores. In a non-secure data store setup, this step can be skipped.

Adding additional XRegion Service Agents

You can achieve horizontal scalability by adding more XRegion Service agents in a group.

Example:

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

# Contents of the configuration file in the host1 in 'fra' Region
{
  "path": "<path to the json config file>",
  "agentGroupSize": 2,
  "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 host7 in 'fra' Region. 
# This host is used only to run an additional XRegion agent 
{
  "path": "<path to the json config file>",
  "agentGroupSize": 2,
  "agentId": 1,
  "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": 2,
  "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"
      ]
    }
  ]
}

# Contents of the configuration file in host 8 in the 'lnd' Region, 
# This host is used only to run an additional XRegion agent
{
  "path": "<path to the json config file>",
  "agentGroupSize": 2,
  "agentId": 1,
  "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"
      ]
    }
  ]
}