RIC:1060: Change in PTL

[ric-plt/sdl.git] / docs / user-guide.rst

diff --git a/docs/user-guide.rst b/docs/user-guide.rst
index a601b15..a1a2246 100644 (file)
--- a/docs/user-guide.rst
+++ b/docs/user-guide.rst
@@ -1,6 +1,6 @@
 ..
 ..  Copyright (c) 2019 AT&T Intellectual Property.
-..  Copyright (c) 2019 Nokia.
+..  Copyright (c) 2019-2022 Nokia.
 ..
 ..  Licensed under the Creative Commons Attribution 4.0 International
 ..  Public License (the "License"); you may not use this file except
@@ -238,12 +238,26 @@ configure database backend:
 * DBAAS_SERVICE_PORT
 * DBAAS_SERVICE_SENTINEL_PORT
 * DBAAS_MASTER_NAME
+* DBAAS_NODE_COUNT
+* DBAAS_CLUSTER_ADDR_LIST
 
 After DBaaS service is installed, environment variables are exposed to
 application containers. SDL library will automatically use these environment
 variables. If DBaaS service is not used, above environment variables needs to
 be set manually so that SDL backend can connect to correct database.
 
+When multiple Database (DB) service is used Nokia SEP deployments can have
+comma separated list of DB ports, sentinel master group names and DB service
+addresses:
+
+ DBAAS_CLUSTER_ADDR_LIST=<comma separated list of DB services>
+ DBAAS_MASTER_NAME=<comma separated list of DB sentinel master names>
+ DBAAS_SERVICE_PORT=<comma separated list of DB service ports>
+ DBAAS_SERVICE_SENTINEL_PORT=<comma separated list of Redis Sentinel ports>
+
+In RIC platform deployments above list type of environment variables will have
+a single value, because only one Database (DB) service is supported in RIC.
+
 **Examples**
 
 An example how environment variables can be set in bash shell, when standalone
@@ -252,17 +266,27 @@ port *6379*::
 
    export DBAAS_SERVICE_HOST=dbaas
    export DBAAS_SERVICE_PORT=6379
+   export DBAAS_NODE_COUNT=1
 
 Besides hostname, IPv4 and IPv6 addresses can be set to *DBAAS_SERVICE_HOST*.
 
 An example how environment variables can be set in bash shell, when Redis
-HA deployment is used. Please note that DBaaS does not support yet HA
-deployment option. Below environment variables are only in the form of an
-example to show how HA deployment would be configured::
+HA deployment is used::
 
-   export DBAAS_MASTER_NAME=my-master-sentinel
+   export DBAAS_MASTER_NAME=my-primary-sentinel
    export DBAAS_SERVICE_HOST=dbaas
    export DBAAS_SERVICE_SENTINEL_PORT=23550
+   export DBAAS_NODE_COUNT=3
+
+An example how environment variables can be set in bash shell, when Redis
+HA deployment with two DB service is used::
+
+   export DBAAS_CLUSTER_ADDR_LIST=dbaas-0,dbaas-1
+   export DBAAS_MASTER_NAME=my-dbaasmaster-0,my-dbaasmaster-1
+   export DBAAS_SERVICE_HOST=dbaas-0
+   export DBAAS_SERVICE_PORT=6379,6380
+   export DBAAS_SERVICE_SENTINEL_PORT=26379,26380
+   export DBAAS_NODE_COUNT=3
 
 .. raw:: pdf
 
@@ -417,11 +441,13 @@ There are two different supported deployment modes for SDL backend data
 storage:
 
 * Standalone (single DB node without redundancy)
-* Redundant (DB node pair working in master/slave redundancy model)
+* Redundant (DB node pair working in primary/replica redundancy model)
 
-SDL does not currently have any intelligent logic (e.g. dynamic scaling) on
-which storage node each namespace data is stored. This area might be developed
-further in the future.
+SDL supports also Redis sentinel based DB cluster where deployment has one or
+more DBAAS Redis sentinel group. Different DBAAS Redis sentinel groups
+can be used to distribute SDL DB operations to different SDL DB instances. When
+more than one DBAAS Redis sentinel group exits the selection of SDL DB instance
+is based on the namespace string hash calculation.
 
 SDL does not prevent backend data storage to be deployed in the same node with
 the SDL client. Such deployments are, however, typically used only in
@@ -495,6 +521,11 @@ Using SDL APIs
   operations. See waitReadyAsync() function
   `doxygen documentation <#doxygen-generated-sdl-api-documentation>`_
   for corresponding asynchronous API for details.
+* Use waitReady() function before doing first operation via synchronous
+  APIs to ensure that SDL and backend data storage are ready to handle
+  operations. See waitReady() function
+  `doxygen documentation <#doxygen-generated-sdl-api-documentation>`_
+  for corresponding synchronous API for details.
 * Avoid using heavy search functions (for example: *AsyncStorage::findKeys()*).
   Rather define your keys so that you know which keys should be read.
 
@@ -525,3 +556,21 @@ Data Management
 .. raw:: pdf
 
    PageBreak
+
+SDLCLI
+******
+
+There is a pre-installed *sdlcli* tool in DBaaS container. With this tool user
+can see statistics of database backend (Redis), check healthiness of DBaaS
+database backend, list database keys and get and set values into database.
+For example to see statistics give below command inside DBaaS container::
+
+    sdlcli statistics
+
+To check healthiness of database::
+
+    sdlcli healthcheck
+
+Use *sdlcli* help to get more information about available commands::
+
+    sdlcli --help