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 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
andagentId
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 theagentGroupSize
is set to 1 and theagentId
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"
]
}
]
}