J release: Release container Image

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

diff --git a/docs/user-guide.rst b/docs/user-guide.rst
index 74dcf3e..a32e6f5 100755 (executable)
--- a/docs/user-guide.rst
+++ b/docs/user-guide.rst
@@ -381,6 +381,7 @@ Metrics
                - SubReqToE2: The total number of SubscriptionRequest messages sent to E2Term
                - SubReReqToE2: The total number of SubscriptionRequest messages resent to E2Term
                - SubRespFromE2: The total number of SubscriptionResponse messages from E2Term
                - SubReqToE2: The total number of SubscriptionRequest messages sent to E2Term
                - SubReReqToE2: The total number of SubscriptionRequest messages resent to E2Term
                - SubRespFromE2: The total number of SubscriptionResponse messages from E2Term

+               - PartialSubRespFromE2: The total number of partial SubscriptionResponse messages from E2Term

                - SubFailFromE2: The total number of SubscriptionFailure messages from E2Term
                - SubReqTimerExpiry: The total number of SubscriptionRequest timer expires
                - RouteCreateFail: The total number of subscription route create failure
                - SubFailFromE2: The total number of SubscriptionFailure messages from E2Term
                - SubReqTimerExpiry: The total number of SubscriptionRequest timer expires
                - RouteCreateFail: The total number of subscription route create failure


@@ -445,14 +446,21 @@ Configurable parameters
 
  The parameters can be changed on the fly via Kubernetes Configmap. Default parameters values are defined in Helm chart
 
 
  The parameters can be changed on the fly via Kubernetes Configmap. Default parameters values are defined in Helm chart
 

- Use following command to open Subscription Manager's Configmap in Nano editor. First change parameter and then store the
- change by pressing first Ctrl + o. Close editor by pressing the Ctrl + x. The change is visible in Subscription Manager's
- log after some 20 - 30 seconds. Note that some of the parameters maybe be useful just for testing purpose.
+ Use following command to open Subscription Manager's Configmap in editor. First change parameter and then store the
+ change. The change is visible in Subscription Manager's log after some 20 - 30 seconds. Note that some of the parameters
+ maybe be useful only for testing purpose.

  
  .. code-block:: none
 
  
  .. code-block:: none
 

+  Open in default editor:
+
+  kubectl edit cm configmap-ricplt-submgr-submgrcfg -n ricplt
+
+  Open in Nano editor:
+

   KUBE_EDITOR="nano" kubectl edit cm configmap-ricplt-submgr-submgrcfg -n ricplt
 
   KUBE_EDITOR="nano" kubectl edit cm configmap-ricplt-submgr-submgrcfg -n ricplt
 

+

 REST interface for debugging and testing
 ----------------------------------------
  Give following commands to get Subscription Manager pod's IP address
 REST interface for debugging and testing
 ----------------------------------------
  Give following commands to get Subscription Manager pod's IP address


@@ -462,20 +470,95 @@ REST interface for debugging and testing
   kubectl get pods -A -o wide | grep submgr
   ricplt        submgr-6d5f487777-2bc4t        1/1     Running   0       6d13h   10.244.0.181   my-ubuntu-18   <none>       <none>
 
   kubectl get pods -A -o wide | grep submgr
   ricplt        submgr-6d5f487777-2bc4t        1/1     Running   0       6d13h   10.244.0.181   my-ubuntu-18   <none>       <none>
 

+ Give following commands to get xApp's service names. xApp's Http Service Name is needed in some of the below commands.
+
+ .. code-block:: none
+
+  kubectl get services -n ricxapp | grep ueec
+  service-ricxapp-ueec-http   ClusterIP   10.101.161.66   <none>        8080/TCP            20s
+  service-ricxapp-ueec-rmr    ClusterIP   10.110.67.7     <none>        4560/TCP,4561/TCP   21s

 
  Get metrics
 
  .. code-block:: none
 
 
  Get metrics
 
  .. code-block:: none
 

-  Example: curl -s GET "http://10.244.0.181:8080/ric/v1/metrics"
+  Example: curl -X GET "http://10.244.0.181:8080/ric/v1/metrics"
+
+ Get all E2Nodes in subscription manager
+
+ .. code-block:: none
+
+  Example: curl -X GET "http://10.244.0.181:8080/ric/v1/get_all_e2nodes"
+
+ Get all REST subscriptions of one E2Node in Subscription manager
+
+ .. code-block:: none
+
+  Syntax: curl -X GET "10.244.0.181:8080/ric/v1/get_e2node_rest_subscriptions/{ranName}" 
+
+  Example: curl -X GET "10.244.0.181:8080/ric/v1/get_e2node_rest_subscriptions/gnb_208_092_303030" 
+
+ Get all xApps in subscription manager
+
+ .. code-block:: none
+
+  Example: curl -X GET "http://10.244.0.181:8080/ric/v1/get_all_xapps"

 
 

- Get REST subscriptions.
+ Get all subscriptions of a xApp in Subscription manager
+
+ .. code-block:: none
+
+  Syntax: curl -X GET "http://10.244.0.181:8080/ric/v1/get_xapp_rest_restsubscriptions/{xappHttpServiceName.ricxapp}"
+
+  Example: curl -X GET "http://10.244.0.181:8080/ric/v1/get_xapp_rest_restsubscriptions/service-ricxapp-ueec-http.ricxapp"
+
+ Get all E2 subscriptions of a REST subscription
+
+ .. code-block:: none
+
+  Syntax: curl -X GET "http://10.244.0.181:8080/ric/v1/get_e2subscriptions/{restSubId}"
+
+  Example: curl -X GET "http://10.244.0.181:8080/ric/v1/get_e2subscriptions/22znlx1XCYqhD0tDHIIqSauBCf3"
+
+ Delete all subscriptions of one E2Node. Deletion is done the same way as xApp would request deletion, i.e. subscription is tried to
+ delete also from E2 node and route(s) created for subscription is deleted. xApp will not get any information about subscription
+ deletion as it is not notified anyway!
+
+ .. code-block:: none
+
+  Syntax: curl -X DELETE "10.244.0.181:8080/ric/v1/delete_all_e2node_subscriptions/{ranName}"
+
+  Example: curl -X DELETE "10.244.0.181:8080/ric/v1/delete_all_e2node_subscriptions/gnb_208_092_303030"
+
+ Delete all subscriptions of a xApp. Deletion is done the same way as xApp would request deletion, i.e. subscription is tried to
+ delete also from E2 node and route(s) created for subscription is deleted. xApp will not get any information about subscription
+ deletion as it is not notified anyway!
+
+ .. code-block:: none
+
+  Syntax: curl -X DELETE "http://10.244.0.181:8080/ric/v1/delete_all_xapp_subscriptions/{xappHttpServiceName.ricxapp}"
+
+  Example: curl -X DELETE "http://10.244.0.181:8080/ric/v1/delete_all_xapp_subscriptions/service-ricxapp-ueec-http.ricxapp"
+
+ Delete one REST subscription like xApp does it. Note that port number is 8088 in this command! Deletion is done the same way as xApp
+ would request deletion, i.e. subscription is tried to delete also from E2 node and route(s) created for subscription is deleted. xApp
+ will not get any information about subscription deletion as it is not notified anyway!
+
+ .. code-block:: none
+
+  Syntax: curl -X DELETE "http://10.244.0.181:8088/ric/v1/subscriptions/{restSubId}" -H "accept: application/json"
+ 
+  Example: curl -X DELETE "http://10.244.0.181:8088/ric/v1/subscriptions/22znlx1XCYqhD0tDHIIqSauBCf3" -H "accept: application/json"
+
+ Below commands are mostly useful only for testing Subscription Manager, except the last command to get Subscription Manager's log writings.
+
+ Get all REST subscriptions.

 
  .. code-block:: none
 
   Example: curl -X GET "http://10.244.0.181:8080/ric/v1/restsubscriptions"
 
 
  .. code-block:: none
 
   Example: curl -X GET "http://10.244.0.181:8080/ric/v1/restsubscriptions"
 

- Get E2 subscriptions.
+ Get all E2 subscriptions.

 
  .. code-block:: none
 
 
  .. code-block:: none
 


@@ -497,7 +580,7 @@ REST interface for debugging and testing
 
   Example: curl -X POST "http://10.244.0.181:8080/ric/v1/test/emptydb"
 
 
   Example: curl -X POST "http://10.244.0.181:8080/ric/v1/test/emptydb"
 

- Make Subscription Manager restart.
+ Make Subscription Manager restart. Code executes Exit command and then Kubernetes restarts the pod.

 
  .. code-block:: none
 
 
  .. code-block:: none
 


@@ -547,3 +630,17 @@ Recommendations for xApps
      all E2 subscriptions sent in REST subscription request. Maximum time to complete all E2 subscriptions in Subscription Manager can be calculated like this:
      t >= 3 * 2s * count_of_subscriptions in the REST request. Length of supervising timers in Subscription Manager for the requests it sends to E2 Node is by
      default 2 seconds. There can be only one ongoing E2 subscription request towards per E2 Node other requests are queued in Subscription Manager.
      all E2 subscriptions sent in REST subscription request. Maximum time to complete all E2 subscriptions in Subscription Manager can be calculated like this:
      t >= 3 * 2s * count_of_subscriptions in the REST request. Length of supervising timers in Subscription Manager for the requests it sends to E2 Node is by
      default 2 seconds. There can be only one ongoing E2 subscription request towards per E2 Node other requests are queued in Subscription Manager.

+
+Special notes
+-------------
+ According to E2 specification E2Node may accept subscription partially. This in not properly supported in REST interface between xApp and Subscription Manager.
+ The interface specification yaml lacks ActionNotAdmittedList IE for RICSubscriptionResponse and RICSubscriptionFailure messages. That information in now embedded as
+ workaround in the descriptive error string as a valid JSON string. Missing ActionNotAdmittedList will be added in the REST interface in some coming update.
+
+ Example descriptive error string for RICSubscriptionResponse:
+
+   Error cause RICSubscriptionResponse partially accepted: ActionNotAdmittedList: [{\"ActionId\":1,\"Cause\":{\"Content\":1,\"Value\":8}}]
+
+ Example descriptive error string for RICSubscriptionFailure:
+
+   Error cause RICSubscriptionFailure: ActionNotAdmittedList: [{\"ActionId\":1,\"Cause\":{\"Content\":5,\"Value\":1}}]
\ No newline at end of file