NkBASE is designed to be integrated into riak_core based distributed Erlang applications. All of the riak_core related aspects, like adding and removing nodes, would be common to NkBASE and your application.
NkBASE includes however all the tools you need to manager the cluster, in case you need it or for developing purposes. You can use these tools, your own, or direct riak_core calls.
NkBASE can be started as a standard OTP aplication, or calling nkbase_app:start/0 directly. Only in the second case, NkBASE will create the data directory and start all required dependencies, specially riak_core itself.
NkBASE will use the platform_data_dir config parameter of riak_core, and will add the directory nkbase_data there in case you start the persistent (leveldb) backend.
The strong consistency system will not be started automatically. See Strong Consistency Mode for more information.
The default log level will be read from the lager application config options. You can change the console level calling nkbase_util:loglevel/0.
Once the first node has started, you can add more nodes to the cluster (for a quick, developer multiple node start, see Quick Start).
In the second node, start NkBASE (be careful not to start the consensus system) and call nkbase_admin:join/1, for example:
> nkbase_admin:join("[email protected]").
Success: staged join request for '[email protected]' to "[email protected]"
okYou can repeat this operation for any number of nodes.
Then, you must get the current cluster plan calling nkbase_admin:cluster_plan/0. You will see all actions that the cluster must perform to add these nodes. If everything looks ok, call nkbase_admin:cluster_commit/0 to perform the modifications.
You can use nkbase_admin:leave/0,1 to instruct the cluster to abandon a current node, and nkbase_admin:force_remove/1 in case of crashed or not available nodes. You can also replace hosts calling nkbase_admin:replace/2 and nkbase_admin:force_replace/2.
At any moment, you can call nkbase_admin:print_info/0 to show in screen a summary of all the cluster related information:
> nkbase_admin:print_info().
==================================================================
UP services: [nkbase]
All members: ['[email protected]','[email protected]','[email protected]',
'[email protected]','[email protected]']
Active members: ['[email protected]','[email protected]','[email protected]',
'[email protected]','[email protected]']
Ready members: ['[email protected]','[email protected]','[email protected]',
'[email protected]','[email protected]']
Partitions owned by '[email protected]':
+---------+-------------------------------------------------+--+
| type | index |id|
+---------+-------------------------------------------------+--+
| primary | 0 |0 |
| primary |913438523331814323877303020447676887284957839360 |5 |
|secondary|182687704666362864775460604089535377456991567872 |1 |
|secondary|365375409332725729550921208179070754913983135744 |2 |
|secondary|548063113999088594326381812268606132370974703616 |3 |
|secondary|730750818665451459101842416358141509827966271488 |4 |
|secondary|1096126227998177188652763624537212264741949407232|6 |
|secondary|1278813932664540053428224228626747642198940975104|7 |
| stopped | -- |--|
+---------+-------------------------------------------------+--+
--------------------------- Owners -------------------------------
[{0,'[email protected]'},
{1,'[email protected]'},
{2,'[email protected]'},
{3,'[email protected]'},
{4,'[email protected]'},
{5,'[email protected]'},
{6,'[email protected]'},
{7,'[email protected]'}]
----------------------------- All VNodes -------------------------
[{nkbase_vnode,0,<0.211.0>},
{nkbase_vnode,1,<0.724.0>},
{nkbase_vnode,2,<0.742.0>},
{nkbase_vnode,3,<0.759.0>},
{nkbase_vnode,4,<0.779.0>},
{nkbase_vnode,5,<0.297.0>},
{nkbase_vnode,6,<0.796.0>},
{nkbase_vnode,7,<0.814.0>}]
----------------------------- Transfers -------------------------
'[email protected]' waiting to handoff 7 partitions
'[email protected]' waiting to handoff 7 partitions
'[email protected]' waiting to handoff 6 partitions
Active Transfers:
================================= Membership ==================================
Status Ring Pending Node
-------------------------------------------------------------------------------
valid 25.0% -- '[email protected]'
valid 25.0% -- '[email protected]'
valid 25.0% -- '[email protected]'
valid 12.5% -- '[email protected]'
valid 12.5% -- '[email protected]'
-------------------------------------------------------------------------------
Valid:5 / Leaving:0 / Exiting:0 / Joining:0 / Down:0
================================== Claimant ===================================
Claimant: '[email protected]'
Status: up
Ring Ready: true
============================== Ownership Handoff ==============================
No pending changes.
============================== Unreachable Nodes ==============================
All nodes are up and reachable
----------------------------- Handoff -------------------------
Each cell indicates active transfers and, in parenthesis, the number of all known transfers.
The 'Total' column is the sum of the active transfers.
+------------------+-----+---------+------+------+------+
| Node |Total|Ownership|Resize|Hinted|Repair|
+------------------+-----+---------+------+------+------+
| [email protected] | 0 | | |0 (10)| |
| [email protected] | 0 | | |0 (6) | |
| [email protected] | 0 | | |0 (6) | |
| [email protected] | 0 | | |0 (9) | |
| [email protected] | 0 | | |0 (9) | |
+------------------+-----+---------+------+------+------+
No ongoing transfers.
============================== Consensus System ===============================
Enabled: true
Active: true
Ring Ready: true
Validation: strong (trusted majority required)
Metadata: best-effort replication (asynchronous)
================================== Ensembles ==================================
Ensemble Quorum Nodes Leader
-------------------------------------------------------------------------------
root 0 / 1 1 / 1 --
ok
Have a look at nkbase_admin.erl for more detailed information functions.