aca93d542915360cc5701bb8a736bd5c75ae48cc
[ric-plt/submgr.git] / docs / user-guide.rst
1 ..
2 ..  Copyright (c) 2019 AT&T Intellectual Property.
3 ..  Copyright (c) 2019 Nokia.
4 ..
5 ..  Licensed under the Creative Commons Attribution 4.0 International
6 ..  Public License (the "License"); you may not use this file except
7 ..  in compliance with the License. You may obtain a copy of the License at
8 ..
9 ..    https://creativecommons.org/licenses/by/4.0/
10 ..
11 ..  Unless required by applicable law or agreed to in writing, documentation
12 ..  distributed under the License is distributed on an "AS IS" BASIS,
13 ..  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 ..
15 ..  See the License for the specific language governing permissions and
16 ..  limitations under the License.
17 ..
18
19 User-Guide (new)
20 ================
21
22 .. contents::
23    :depth: 3
24    :local:
25
26 Overview
27 --------
28 Subscription Manager is a basic platform service in RIC. It is responsible for managing E2 subscriptions from xApps to the
29 E2 Node (eNodeB or gNodeB).
30
31 xApp can subscribe and unsubscribe messages from E2 Node through Subscription Manager. Subscription Manager manages subscriptions
32 and message routing of the subscribed messages between E2 Termination and xApps. If one xApp has already made a subscription
33 and then another xApp initiates identical subscription, Subscription Manager does not forward the subscription to E2 Node but merges the
34 subscriptions internally. In merge case Subscription Manager just updates the message routing information to Routing Manager and
35 sends response to xApp.
36
37 Interface between xApp and Subscription Manager is HTTP based REST interface. Interface codes are generated with help of Swagger from a
38 yaml definition file. REST interface is used also between Subscription Manager and Routing Manager. Subscription Manager and
39 E2 Termination interface is based on RMR messages. xApp should use also Swagger generated code when it implements subscription REST
40 interface towards Subscription Manager.
41
42     .. image:: images/PlaceInRICSoftwareArchitecture.png
43       :width: 600
44       :alt: Place in RIC's software architecture picture
45
46
47 One xApp generated REST subscription message can contain multiple E2 subscriptions. For every E2 subscription in the message there is also
48 xApp generated xApp instance id. In E2 interface there can be only one ongoing E2 subscription or subscription delete procedure towards
49 E2 Node at any time. That is because Subscription Manager is able to merge new E2 subscriptions only which those it has already received
50 successful response from E2 Node. E2 subscriptions and delete subscriptions may be therefore queued in Subscription Manager.
51
52 Subscription Manager may need to do reties towards E2 Node during subscribe or subscription delete procedure. Retries will increase completion
53 time of the procedure. This needs to be considered in xApp's implementation. Subscription Manager sends REST notification to xApp for every
54 completed E2 subscription procedure regardless is the E2 subscription successful or not. Notification is not sent for E2 subscription delete
55 procedures. Subscription Manager allocates globally unique REST request id for each new REST subscription request. That is returned to xApp in
56 response. When xApp wants to delete REST subscription, xApp need to use the same id in deletion request.
57
58 Subscription Manager allocates unique id also for the E2 subscriptions (E2 instance id). The id called 'InstanceId' in E2 specification.
59 In successful case the REST notification contains the id generated for the REST request, xApp instance id and E2 instance id. From xApp point
60 of view xApp instance id identifies received REST notification for the E2 subscription in the REST request. REST notification contains also Subscription
61 Manager generated E2 instance id. xApp can use that to map received E2 Indication message to E2 subscription. If E2 subscription procedure is unsuccessful
62 then E2 instance id is 0 and the notification contains non-zero error cause string.
63
64 xApp need to be able preserve Subscription Manager allocated REST request id over xApp restart. The id is needed for deletion of the REST
65 subscription and if there is need to resend the same REST request.  
66
67 Three different type of subscriptions are supported. REPORT, POLICY and INSERT. REPORT and INSERT works the same way from subscription point of view.
68 REPORT and INSERT type REST subscription request can contain content for multiple E2 subscriptions. POLICY subscription can also contain content for multiple
69 E2 subscriptions but using in that way may not be feasible. REPORT, POLICY and INSERT type subscriptions in the same REST request are not supported supported
70 in Subscription Manager.
71
72 REPORT and INSERT type subscription can contain content for multiple E2 subscriptions. If there is need to resend the same REST request, the request must
73 contain Subscription Manager allocated id for the REST request, which was returned to xApp when the request was sent first time. The request must also
74 contain the same content as first time. Reason for xApp to resend the same request could be timeout or some failure which is not permanent in E2 Node or
75 xApp restart. In retry cases Subscription Manager retries the E2 subscriptions which does not exist in its records. For others Subscription Manager
76 returns successful REST notification without sending any messages to E2 Node. One REST Subscription request can contain E2 subscriptions to only one E2 Node.
77
78 If there is need to change REPORT or INSERT type subscription then previously made subscription need to be deleted first. If there are any REPORT or INSERT
79 type E2 subscription which need to change frequently, it is not good idea to bundle them with other REPORT or INSERT type E2 subscriptions in the same REST
80 subscription request.
81
82 POLICY type subscription can contain content for multiple E2 subscriptions but it may not be feasible as POLICY subscription may change. Idea in POLICY
83 subscription is that xApp can send changed contend to E2 Node without making new subscription but just send update. In such case it is not good idea to bundle
84 the POLICY type E2 subscription with any other POLICY type E2 subscriptions in the same REST subscription request.
85
86 In xApp restart case only mandatory thing what is required xApp to be able preserve is the Subscription Manager allocated REST requests ids. That is if xApp
87 can generate the equal requests otherwise as were done first time before restart. xApp can resent the same REST requests to Subscription Manager as first time
88 before restart. REST request id must be placed in the REST request. That is the only way for Subscription Manager to identify already made subscriptions in it
89 records and work as expected, i.e.  not run into problems and return successful REST notifications to xApp without sending any messages to E2 Node.
90
91 Architecture
92 ------------
93
94   * Message routing
95
96       Subscribed messages from E2 Node are transported to RIC inside RIC Indication message. RIC Indication message is transported to xApp
97       inside RMR message in Payload field of the RMR message. RMR message is routed to xApp based on SubId field (E2 instance id) in
98       the RMR header. 
99
100       Subscription Manager allocates unique E2 instance id for every E2 subscription during subscription procedure. Subscription Manager
101       puts allocated E2 instance id to InstanceId field in the ASN.1 packed RIC Subscription Request message which is sent to E2 Node. That
102       E2 instance id is then used for the E2 subscription in RIC and E2 Node as long the E2 subscription lives. xApp gets the
103       allocated E2 instance id in REST notification message when E2 subscription procedure is completed.
104       
105       Subscribed messages are routed to xApps based on InstanceId in E2 Indication message. InstanceId is placed in the SubId field of the RMR
106       message header when E2 Termination sends the subscribed message to xApp.
107
108       RIC Subscription Request and RIC Subscription delete Request messages are pre configured to be routed to E2 Termination and responses
109       to those messages back to Subscription Manager.
110
111       Subscription Manager allocates RIC Requestor Id for E2 interface communication. Currently the id value is always 123. E2 Node gets the Request
112       of the xApp who makes the first subscription. E2 Node uses Subscription Manager allocated RIC Requestor ID in all RIC Indication messages it sends
113       to RIC for the subscription. In merge case subscription in E2 Node is created only for the first requestor.
114
115   * Subscription procedure
116       
117     * Successful case
118
119       xApp sends REST Subscription Request message to Subscription Manager. The request can contain multiple E2 subscriptions. It contains also
120       xApp generated xApp instance id for every E2 subscription. Subscription Manager checks does the message contain Subscription Manager allocated
121       REST request id for the request. When xApp sends the request first time there is no REST request id and Subscription Manager allocates it.
122
123       Then Subscription Manager makes simple validation for data in the request and copies data to Golang data types. When all data is copied successfully
124       Subscription Manager sends successful respond to the REST request. Response contains Subscription Manager allocated REST request id.
125       Then Subscription Manager sends route create request to Routing Manager over REST interface. When route is created successfully, Subscription Manager
126       ASN.1 encodes the E2 messages and forwards those to E2 Termination. When RIC Subscription Response arrives from E2 Termination
127       Subscription Manager forwards REST notification to xApp. The notification contains REST request id, xApp instance id and E2 instance id.
128       
129       Subscription Manager supervises route creation and RIC Subscription Request with a timer.
130
131       RIC Indication messages which are used to transport subscribed messages from E2 Node are routed from E2 Termination to xApps directly using
132       the routes created during Subscription procedure.
133
134       Subscription Manager supports REPORT, POLICY and INSERT type subscriptions (E2 RICActionTypes). CONTROL is not supported. POLICY type
135       subscription can be updated. In update case signaling sequence is the same as above, except route is not created to Routing manager.
136       xApp uses initially allocated REST request id, xApp instance id in update case. Route in POLICY type subscription case is needed
137       only that Error Indication could be to xApp, but it is not used currently. RIC Subscription Request message contains list of ActionsToBeSetup
138       information elements. The list cannot have REPORT, POLICY or INSERT action types at the same time. Subscription Manager checks actions types
139       in the message. If different action types is found the REST request is not accepted.
140
141
142     .. image:: images/Successful_Subscription.png
143       :width: 600
144       :alt: Successful subscription picture
145
146
147     * Failure case
148
149       Failure can happen already before REST request reaches Subscription Manager. Swagger make value checks for the message passed to it.
150       If values are does not accepted then send function returns "unknown error".
151
152       If failure happens when Subscription Manager validates the REST request then error is returned instantly and processing of request is
153       stopped. xApp receives bad request (HTTP response code 400) response.
154
155       If failure response is received from E2 Node then REST notification is forwarded to xApp with appropriate error cause. The notification
156       contains REST request id, xApp instance id and zero E2 instance id.
157
158     .. image:: images/Subscription_Failure.png
159       :width: 600
160       :alt: Subscription failure picture
161
162     * Timeout in Subscription Manager
163
164       In case of timeout in Subscription Manager, Subscription Manager may resend the RIC Subscription Request to E2 Node. By default Subscription
165       Manager retries twice. If there is no response after retries, Subscription Manager sends unsuccessful REST notification to xApp. The notification
166       contains REST request id, xApp instance id and zero E2 instance id.
167
168     * Timeout in xApp
169
170       xApp can resend the same REST Subscription Request if request timeouts.
171
172       xApp may resend the same request if it does not receive expected notification in expected time. If xApp resends the same request while Subscription
173       Manager is still processing previous request then Subscription Manager responds accepts the request and continues processing previous request.
174
175     .. image:: images/Subscription_Timeout.png
176       :width: 600
177       :alt: Subscription timeout picture
178
179   * Subscription delete procedure
180
181     * Successful case
182
183       xApp sends REST Subscription Delete Request message to Subscription Manager. xApp must use the same REST request id which it received in REST Subscription
184       Response. REST delete request will delete all successfully subscribed E2 subscriptions which was subscribed earlier when the REST request id was created.
185       When Subscription Manager receives REST Subscription Delete Request it check has it such REST subscription. If it has then Subscription Manager sends successful
186       response to xApp and starts sending E2 delete requests to E2 Termination one by one. When RIC Subscription Delete Response arrives from E2 Termination to
187       Subscription Manager, Subscription Manager request route deletion from Routing Manager. xApp does not get any notification about deleted E2 subscriptions. 
188       
189       Subscription Manager supervises RIC Subscription Deletion Request and route delete with a timer.
190
191     .. image:: images/Successful_Subscription_Delete.png
192       :width: 600
193       :alt: Successful subscription delete picture
194
195     * Failure case
196
197       Delete procedure cannot fail from xApp point of view. Subscription Manager always responds with successful REST Subscription Response to xApp.
198       E2 Node could respond with delete failure in case the subscription which Subscription Manager wants to delete does not exist. In this case delete procedure
199       ends there.
200
201     .. image:: images/Subscription_Delete_Failure.png
202       :width: 600
203       :alt: Subscription delete failure picture
204
205     * Timeout in Subscription Manager
206
207       In case of timeout in Subscription Manager, Subscription Manager may resend the RIC Subscription Delete Request to E2 Node. By default Subscription Manager
208       retries twice. If there is no response after retry, Subscription Manager stops trying.
209
210     * Timeout in xApp
211
212       xApp can resend the same REST Subscription Delete Request if request timeouts.
213
214     .. image:: images/Subscription_Delete_Timeout.png
215       :width: 600
216       :alt: Subscription delete timeout picture
217
218     * Unknown REST request id
219
220       If Subscription Manager receives RIC Subscription Delete Request for a REST request id which does not exist, Subscription Manager sends
221       successful REST response to xApp.
222
223   * Subscription merge procedure
224
225     * Successful case
226
227       Merge is possible only for REPORT type subscription. It is possible only when Action Type and Event Trigger Definition of subscriptions are equal.
228
229       xApp sends REST Subscription Request message to Subscription Manager. The request can contain multiple E2 subscriptions as in normal Subscription
230       procedure but some of the E2 subscriptions in the list are already subscribed from E2 Node. For those which are not yet subscribed Subscription Manager
231       applies normal Subscription procedure. E2 subscriptions in the list which are already subscribed are just assigned to existing subscriptions and Subscription
232       Manager just sends route create to Routing Manager and then forwards successful REST notification to xApp for the E2 subscriptions. The notification
233       contains REST request id, xApp instance id and E2 instance id.
234
235       One thing to note! REST Subscription request and returned REST notification goes through different TCP ports. For that reason there is no guarantee that
236       response for REST Subscription request arrives to xApp before first REST notification. That is possible mostly in merge case where subscription already exist
237       in Subscription Manager records. Successful REST notification is returned to xApp without making subscription from E2 Node which would cause some delay before
238       REST notification can be sent.
239       
240       Route create is supervised with a timer.
241
242       ``Only REPORT type subscriptions can be be merged.``
243
244     .. image:: images/Successful_Subscription_Merge.png
245       :width: 600
246       :alt: Successful subscription merge picture
247
248     * Failure case
249
250       Failure can happen already before REST request reaches Subscription Manager. Swagger make value checks for the message passed to it.
251       If values are does not accept then send function returns "unknown error".
252
253       If failure happens when Subscription Manager validates the REST request then error is returned instantly and processing of request is
254       stopped. xApp receives bad request (HTTP response code 400) response.
255       
256       If error happens during route create then Subscription Manager forwards REST notification toxApp with appropriate error cause. The notification contains
257       also REST request id, xApp instance id and zero E2 instance id.
258
259     * Timeout in Subscription Manager
260
261       Timeout can come only in route create during merge operation. If error happens during route create then Subscription Manager forwards REST
262       notification toxApp with appropriate error cause. The notification contains also REST request id, xApp instance id and zero E2 instance id.
263
264     * Timeout in xApp
265
266       xApp can resend the same REST Subscription Request if request timeouts.
267
268   * Subscription delete merge procedure
269
270     * Successful case
271
272       xApp sends REST Subscription Delete Request message to Subscription Manager. If delete concerns merged subscription, Subscription Manager
273       responds with REST Subscription Delete Response to xApp and then sends route delete request to Routing manager.
274       
275       Subscription Manager supervises route delete with a timer.
276
277     .. image:: images/Successful_Subscription_Delete_Merge.png
278       :width: 600
279       :alt: Successful subscription delete merge picture
280
281     * Failure case
282
283       Delete procedure cannot fail from xApp point of view. Subscription Manager always responds with successful REST Subscription Delete Response to xApp.
284
285     * Timeout in Subscription Manager
286
287       Timeout can only happen in route delete to Routing manager. Subscription Manager always responds with successful REST Subscription Delete Response to xApp.
288
289     * Timeout in xApp
290
291       xApp can resend the same REST Delete Request if request timeouts.
292
293   * xApp restart
294
295     When xApp is restarted for any reason it may resend REST subscription requests for subscriptions which have already been subscribed. If REPORT or INSERT type
296     subscription already exists and RMR endpoint of requesting xApp is attached to subscription then successful response is sent to xApp directly without
297     updating Routing Manager and E2 Node. If POLICY type subscription already exists, request is forwarded to E2 Node and successful response is sent to xApp.
298     E2 Node is expected to accept duplicate POLICY type requests. In restart IP address of the xApp may change but domain service address name does not.
299     RMR message routing uses domain service address name.
300
301   * Subscription Manager restart
302
303     Subscription Manager stores REST request ids, E2 subscriptions and their mapping to REST request ids in db (SDL). In start up Subscription Manager restores REST request
304     ids, E2 subscriptions and their mapping from db. For E2 subscriptions which were not successfully completed, Subscription Manager sends delete request to E2 Node and
305     removes routes created for those. In restart case xApp may need to resend the same REST request to get all E2 subscriptions completed.
306     
307     Restoring subscriptions from db can be disable via submgr-config.yaml file by setting "readSubsFromDb": "false".
308
309 Metrics
310 -------
311  Subscription Manager adds following statistic counters:
312
313  Subscription create counters:
314                 - SubReqFromXapp: The total number of SubscriptionRequest messages received from xApp
315                 - SubRespToXapp: The total number of SubscriptionResponse messages sent to xApp
316                 - SubFailToXapp: The total number of SubscriptionFailure messages sent to xApp
317                 - SubReqToE2: The total number of SubscriptionRequest messages sent to E2Term
318                 - SubReReqToE2: The total number of SubscriptionRequest messages resent to E2Term
319                 - SubRespFromE2: The total number of SubscriptionResponse messages from E2Term
320                 - SubFailFromE2: The total number of SubscriptionFailure messages from E2Term
321                 - SubReqTimerExpiry: The total number of SubscriptionRequest timer expires
322                 - RouteCreateFail: The total number of subscription route create failure
323                 - RouteCreateUpdateFail: The total number of subscription route create update failure
324                 - MergedSubscriptions: The total number of merged Subscriptions
325
326  Subscription delete counters:
327                 - SubDelReqFromXapp: The total number of SubscriptionDeleteResponse messages received from xApp
328                 - SubDelRespToXapp: The total number of SubscriptionDeleteResponse messages sent to xApp
329                 - SubDelReqToE2: The total number of SubscriptionDeleteRequest messages sent to E2Term
330                 - SubDelReReqToE2: The total number of SubscriptionDeleteRequest messages resent to E2Term
331                 - SubDelRespFromE2: The total number of SubscriptionDeleteResponse messages from E2Term
332                 - SubDelFailFromE2: The total number of SubscriptionDeleteFailure messages from E2Term
333                 - SubDelReqTimerExpiry: The total number of SubscriptionDeleteRequest timer expires
334                 - RouteDeleteFail: The total number of subscription route delete failure
335                 - RouteDeleteUpdateFail: The total number of subscription route delete update failure
336                 - UnmergedSubscriptions: The total number of unmerged Subscriptions
337
338  SDL failure counters:
339                 - SDLWriteFailure: The total number of SDL write failures
340                 - SDLReadFailure: The total number of SDL read failures
341                 - SDLRemoveFailure: The total number of SDL read failures
342
343 Configurable parameters
344 -----------------------
345  Subscription Manager has following configurable parameters.
346    - Retry timeout for RIC Subscription Request message
347       - e2tSubReqTimeout_ms: 2000 is the default value
348
349    - Retry timeout for RIC Subscription Delete Request message
350       - e2tSubDelReqTime_ms: 2000 is the default value
351
352    - Waiting time for RIC Subscription Response and RIC Subscription Delete Response messages
353       - e2tRecvMsgTimeout_ms: 2000 is the default value
354
355    - Try count for RIC Subscription Request message   
356       - e2tMaxSubReqTryCount: 2 is the default value
357
358    - Try count for RIC Subscription Delete Request message   
359       - e2tMaxSubDelReqTryCount: 2 is the default value
360    
361    - Are subscriptions read from database in Subscription Manager startup
362       - readSubsFromDb: "true"  is the default value
363  
364  The parameters can be changed on the fly via Kubernetes Configmap. Default parameters values are defined in Helm chart
365
366  Use following command to open Subscription Manager's Configmap in Nano editor. First change parameter and then store the
367  change by pressing first Ctrl + o. Close editor by pressing the Ctrl + x. The change is visible in Subscription Manager's
368  log after some 20 - 30 seconds.
369  
370  .. code-block:: none
371
372   KUBE_EDITOR="nano" kubectl edit cm configmap-ricplt-submgr-submgrcfg -n ricplt
373
374 REST interface for debugging and testing
375 ----------------------------------------
376  Give following commands to get Subscription Manager pod's IP address
377
378  .. code-block:: none
379
380   kubectl get pods -A | grep submgr
381   
382   ricplt        submgr-75bccb84b6-n9vnt          1/1     Running             0          81m
383
384   Syntax: kubectl exec -t -n ricplt <add-submgr-pod-name> -- cat /etc/hosts | grep submgr | awk '{print $1}'
385   
386   Example: kubectl exec -t -n ricplt submgr-75bccb84b6-n9vnt -- cat /etc/hosts | grep submgr | awk '{print $1}'
387
388   10.244.0.181
389
390  Get metrics
391
392  .. code-block:: none
393
394   Example: curl -s GET "http://10.244.0.181:8080/ric/v1/metrics"
395
396  Get subscriptions
397
398  .. code-block:: none
399
400   Example: curl -X GET "http://10.244.0.181:8088/ric/v1/subscriptions"
401
402  Delete single subscription from db
403
404  .. code-block:: none
405
406   Syntax: curl -X POST "http://10.244.0.181:8080/ric/v1/test/deletesubid={SubscriptionId}"
407   
408   Example: curl -X POST "http://10.244.0.181:8080/ric/v1/test/deletesubid=1"
409
410  Remove all subscriptions from db
411
412  .. code-block:: none
413
414   Example: curl -X POST "http://10.244.0.181:8080/ric/v1/test/emptydb"
415
416  Make Subscription Manager restart
417
418  .. code-block:: none
419
420   Example: curl -X POST "http://10.244.0.181:8080/ric/v1/test/restart"
421
422  Use this command to get Subscription Manager's log writings
423
424  .. code-block:: none
425
426    Example: kubectl logs -n ricplt submgr-75bccb84b6-n9vnt
427
428  Logger level in configmap.yaml file in Helm chart is by default 2. It means that only info logs are printed.
429  To see debug log writings it has to be changed to 4.
430
431  .. code-block:: none
432
433     "logger":
434       "level": 4
435
436 RAN services explained
437 ----------------------
438   RIC hosted xApps may use the following RAN services from a RAN node:
439
440   *  REPORT: RIC requests that RAN sends a REPORT message to RIC and continues further call processing in RAN after each occurrence of a defined SUBSCRIPTION
441   *  INSERT: RIC requests that RAN sends an INSERT message to RIC and suspends further call processing in RAN after each occurrence of a defined SUBSCRIPTION
442   *  CONTROL: RIC sends a Control message to RAN to initiate or resume call processing in RAN
443   *  POLICY: RIC requests that RAN executes a specific POLICY during call processing in RAN after each occurrence of a defined SUBSCRIPTION
444
445 Supported E2 procedures and RAN services
446 ----------------------------------------
447     * RIC Subscription procedure with following RIC action types:
448
449       - REPORT
450       - POLICY
451       - INSERT
452
453     * RIC Subscription Delete procedure
454
455     * Merge and delete of equal REPORT type subscriptions.
456
457 Recommendations for xApps
458 -------------------------
459
460    * Recommended retry delay in xApp
461
462      Subscription Manager makes two retries for E2 subscriptions and E2 subscription deletions. xApp should not retry before it has received REST notification for
463      all E2 subscriptions sent in REST subscription request. Maximum time to complete all E2 subscriptions in Subscription Manager can be calculated like this:
464      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
465      default 2 seconds. There can be only one ongoing E2 subscription request towards per E2 Node other requests are queued in Subscription Manager.