Configure XRegion Service

Learn how to configure the XRegion Service in a Multi-Region Oracle NoSQL Database

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 data store and it is recommended to deploy it close to the local data store. To know more about agent and agent groups, see Cross-Region Service in the Concepts Guide.

You can achieve horizontal scalability by dividing the shards across multiple XRegion Service agents based on the CPU and memory of the host node of the agent and the latency and throughput requirements of the application. The mapping of data store shards to XRegion Service agents is determined in a round-robin manner in order to balance the load of agents.

Note: Each XRegion Service agent will map to at least one shard. If users configure more agents than the number of shards, the XRegion Service agent would not be able to start.

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:

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:

Attribute	Description
`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`.

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.

To add horizontal scalability to your agents, do the following:

Identify a host node for the agent. It is recommended that the agent will be the only process running on that node.
Download the Oracle NoSQL Database bundle in the host node identified above and extract the contents of the Oracle NoSQL Database package (kv-M.N.O.zip or kv-M.N.O.tar.gz) to $KVHOME. Unzipping the package installs the Oracle NoSQL Database.
```
unzip kv-ee-26.1.14.zip
```
Create a home directory for the XRegion Service.
Create a JSON config file in the home directory created in the above step.

Note: Steps to create a config file is described in Steps to configure XRegion Service. The agentId starts with 0 and is incremented by one. For example if "agentGroupSize" : 2, and there is already one agent and you are adding the second one, then the value of agentId is 1.

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"
      ]
    }
  ]
}