docs/user-guide-RMR.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
  20 ==========
  21
  22 .. contents::
  23    :depth: 3
  24    :local:
  25
  26 ``RMR based interface between xApp and Subscription Manager which is explained in this User-Guide is deprecated and will be removed in the future.
  27 See second User-Guide which explains new REST based interface.``
  28
  29 Overview
  30 --------
  31 Subscription Manager is a basic platform service in RIC. It is responsible for managing E2 subscriptions from xApps to the
  32 Radio Access Network (RAN).
  33
  34 xApp can subscribe and unsubscribe messages from gNodeB through Subscription Manager. Subscription Manager manages the subscriptions
  35 and message routing of the subscribed messages between E2 Termination and xApps. If one xApp has already made a subscription and then
  36 another xApp initiates identical subscription, Subscription Manager does not forward the subscription to gNodeB but merges the
  37 subscriptions internally. In merge case Subscription Manager just updates the message routing information to Routing Manager and
  38 sends response to xApp.
  39
  40 There can be only one ongoing RIC Subscription or RIC Subscription Delete procedure towards RAN at any time. That is because Subscription
  41 Manager is able to merge new subscriptions only which those it has already received successful response from RAN. Subscriptions
  42 and delete subscriptions are therefore queued in Subscription Manager. Subscription Manager may need to do reties during subscribe or
  43 unsubscribe procedure. This needs to be considered when retries are implemented in xApp side, as it can increase completion time of the
  44 procedure. xApp's retry delay should not be too short.
  45
  46     .. image:: images/PlaceInRICSoftwareArchitecture_RMR.png
  47       :width: 600
  48       :alt: Place in RIC's software architecture picture
  49
  50 Architecture
  51 ------------
  52
  53   * Message routing
  54
  55       Subscribed messages from RAN are transported to RIC inside RIC Indication message. RIC Indication message is transported to xApp
  56       inside RMR message, in Payload field of the RMR message. RMR message is routed to xApp based on SubId field (subscription id) in
  57       the RMR header. Same routing mechanism is used also for response messages from Subscription Manager to xApp. Subscription Manager is
  58       not able to respond to xApp if route for subscription has not been created.
  59
  60       When xApp sends message to Subscription Manager it sets -1 in SubId field in the RMR header. It means that messages are routed based
  61       on message type (Mtype filed in RMR header). RIC Subscription Request and RIC Subscription delete Request messages are pre configured
  62       to be routed to Subscription Manager.
  63
  64       Subscription Manager allocates unique RIC Request Sequence Number for every subscription during Subscription procedure. Subscription
  65       Manager replaces existing ASN.1 decoded RIC Request Sequence Number in the RIC Subscription Request message allocated by the xApp.
  66       That sequence number (subscription id) is then used for the subscription in RIC and RAN as long the subscription lives. xApp gets
  67       the sequence number in RIC Subscription Response message from Subscription manager based on the message types.
  68
  69       Subscribed messages are routed to xApps based on sequence number. Sequence number is placed in the SubId field of the RMR message
  70       header when E2 Termination sends the subscribed message to xApp. When xApp wants to delete the subscription, the same sequence number
  71       must be included in the ASN.1 encoded RIC Subscription Delete Request message sent to Subscription Manager.
  72
  73       Subscription Manager allocates and substitutes RIC Requestor ID for E2 interface communication. Currently the ID value is always 123.
  74       RAN gets the Request of the xApp who makes the first subscription. RAN uses Subscription Manager allocated Requestor ID in all RIC
  75       Indication messages it sends to RIC for the subscription.  Subscription Manager returns the same RIC Requestor ID in response message
  76       to xApp as was in the request. In merge case subscription is created only for the first requestor.
  77
  78       TransactionId (Xid) in RMR message header is used to track messages between xApp and Subscription Manager. xApp allocates it. Subscription
  79       Manager returns TransactionId received from xApp in response message to xApp. xApp uses it to map response messages to request messages
  80       it sends.
  81
  82   * Subscription procedure
  83
  84     * Successful case
  85
  86       xApp sends RIC Subscription Request message to Subscription Manager. Subscription Manager validates request types in the message and sends
  87       route create to Routing Manager over REST interface. When route is created successfully Subscription Manager forwards request to E2
  88       Termination. When RIC Subscription Response arrives from E2 Termination Subscription Manager forwards it to xApp.
  89
  90       Subscription Manager supervises route create and RIC Subscription Request with a timer.
  91
  92       RIC Indication messages which are used to transport subscribed messages from RAN are routed from E2 Termination to xApps
  93       directly using the routes created during Subscription procedure.
  94
  95       Subscription Manager supports REPORT, POLICY and INSERT type subscriptions (RICActionTypes). CONTROL is not supported. POLICY type
  96       subscription can be updated. In update case signaling sequence is the same as above, except route is not created to Routing manager.
  97       xApp uses initially allocated TransactionId and RIC Request Sequence Number in update case. Route in POLICY type subscription case is needed
  98       only that Subscription Manager can send response messages to xApp. RIC Subscription Request message contains list of RICaction-ToBeSetup-ItemIEs.
  99       The list cannot have REPORT, POLICY, INSERT action types at the same time. Subscription Manager checks actions types in the message.
 100       If both action types is found the message is dropped.
 101
 102
 103     .. image:: images/Successful_Subscription_ASN.1.png
 104       :width: 600
 105       :alt: Successful subscription picture
 106
 107
 108     * Failure case
 109
 110       In failure case Subscription Manager checks the failure cause and acts based on that. If failure cause is "duplicate" Subscription
 111       Manager sends delete to RAN and then resends the same subscription. If failure cause is such that Subscription manager cannot do
 112       anything to fix the problem, it sends delete to RAN and sends RIC Subscription Failure to xApp. Subscription Manager may retry RIC
 113       Subscription Request and RIC Subscription Delete messages also in this case before it responds to xApp.
 114
 115     .. image:: images/Subscription_Failure_ASN.1.png
 116       :width: 600
 117       :alt: Subscription failure picture
 118
 119     * Timeout in Subscription Manager
 120
 121      In case of timeout in Subscription Manager, Subscription Manager may resend the RIC Subscription Request to RAN. If there is no response
 122       after retry, Subscription Manager shall NOT send any response to xApp. xApp may retry RIC Subscription Request, if it wishes to do so.
 123       Subscription Manager does no handle the retry if Subscription Manager has ongoing subscription procedure for the same subscription.
 124       Subscription just drops the request.
 125
 126     * Timeout in xApp
 127
 128       xApp may resend the same request if there is no response in expected time. If xApp resends the same request while processing of previous
 129       request has not been completed in Subscription Manager then Subscription Manager drops the new request, makes a log writing and continues
 130       processing previous request.
 131
 132     .. image:: images/Subscription_Timeout_ASN.1.png
 133       :width: 600
 134       :alt: Subscription timeout picture
 135
 136   * Subscription delete procedure
 137
 138     * Successful case
 139
 140       xApp sends RIC Subscription Delete Request message to Subscription Manager. xApp must use the same RIC Request Sequence Number which
 141       it received in RIC Subscription Response message when subscription is deleted. When Subscription Manager receives RIC Subscription
 142       Delete Request message, Subscription Manager first forwards the request to E2 Termination. When RIC Subscription Delete Response arrives
 143       from E2 Termination to Subscription Manager, Subscription Manager forwards it to xApp and then request route deletion from Routing Manager.
 144
 145       Subscription Manager supervises RIC Subscription Deletion Request and route delete with a timer.
 146
 147     .. image:: images/Successful_Subscription_Delete_ASN.1.png
 148       :width: 600
 149       :alt: Successful subscription delete picture
 150
 151     * Failure case
 152
 153       Delete procedure cannot fail from xApp point of view. Subscription Manager always responds with RIC Subscription Delete Response to xApp.
 154
 155     .. image:: images/Subscription_Delete_Failure_ASN.1.png
 156       :width: 600
 157       :alt: Subscription delete failure picture
 158
 159     * Timeout in Subscription Manager
 160
 161       In case of timeout in Subscription Manager, Subscription Manager may resend the RIC Subscription Delete Request to RAN. If there is no
 162       response after retry, Subscription Manager responds to xApp with RIC Subscription Delete Response.
 163
 164     * Timeout in xApp
 165
 166       xApp may resend the same request if there is no response in expected time. If xApp resends the same request while processing of previous
 167       request has not been completed in Subscription Manager then Subscription Manager drops the new request, makes a log writing and continues
 168       processing previous request.
 169
 170     .. image:: images/Subscription_Delete_Timeout_ASN.1.png
 171       :width: 600
 172       :alt: Subscription delete timeout picture
 173
 174     * Unknown subscription
 175
 176       If Subscription Manager receives RIC Subscription Delete Request for a subscription which does not exist, Subscription Manager cannot respond
 177       to xApp as there is no route for the subscription.
 178
 179   * Subscription merge procedure
 180
 181     * Successful case
 182
 183       xApp sends RIC Subscription Request message to Subscription Manager. Subscription Manager checks is the Subscription mergeable. If not,
 184       Subscription Manager continues with normal Subscription procedure. If Subscription is mergeable, Subscription Manager sends route create
 185       to Routing Manager and then responds with RIC Subscription Response to xApp.
 186
 187       Route create is supervised with a timer.
 188
 189       Merge for REPORT type subscription is possible if Action Type and Event Trigger Definition of subscriptions are equal.
 190
 191       ``Only REPORT type subscriptions can be be merged.``
 192
 193     .. image:: images/Successful_Subscription_Merge_ASN.1.png
 194       :width: 600
 195       :alt: Successful subscription merge picture
 196
 197     * Failure case
 198
 199       Failure case is basically the same as in normal subscription procedure. Failure can come only from RAN when merge is not yet done.
 200       If error happens during route create Subscription Manager drops the RIC Subscription Request message and xApp does not get any response.
 201
 202     * Timeout in Subscription Manager
 203
 204       Timeout case is basically the same as in normal subscription procedure but timeout can come only in route create during merge operation.
 205       If error happens during route create, Subscription Manager drops the RIC Subscription Request message and xApp does not get any response.
 206
 207     * Timeout in xApp
 208
 209       xApp may resend the same request if there is no response in expected time. If xApp resends the same request while processing of previous
 210       request has not been completed in Subscription Manager then Subscription Manager drops the new request, makes a log writing and continues
 211       processing previous request.
 212
 213   * Subscription delete merge procedure
 214
 215     * Successful case
 216
 217       xApp sends RIC Subscription Delete Request message to Subscription Manager. If delete concerns merged subscription, Subscription Manager
 218       responds with RIC Subscription Delete Response to xApp and then sends route delete request to Routing manager.
 219
 220       Subscription Manager supervises route delete with a timer.
 221
 222     .. image:: images/Successful_Subscription_Delete_Merge_ASN.1.png
 223       :width: 600
 224       :alt: Successful subscription delete merge picture
 225
 226     * Failure case
 227
 228       Delete procedure cannot fail from xApp point of view. Subscription Manager responds with RIC Subscription Delete Response message to xApp.
 229
 230     * Timeout in Subscription Manager
 231
 232       Timeout can only happen in route delete to Routing manager. Subscription Manager responds with RIC Subscription Delete Response message to xApp.
 233
 234     * Timeout in xApp
 235
 236       xApp may resend the same request if there is no response in expected time. If xApp resends the same request while processing of previous
 237       request has not been completed in Subscription Manager then Subscription Manager drops the new request, makes a log writing and continues
 238       processing previous request.
 239
 240   * Unknown message
 241
 242      If Subscription Manager receives unknown message, Subscription Manager drops the message.
 243
 244   * xApp restart
 245
 246     When xApp is restarted for any reason it may resend subscription requests for subscriptions which have already been subscribed. If REPORT or INSERT type
 247     subscription already exists and RMR endpoint of requesting xApp is attached to subscription then successful response is sent to xApp directly without
 248     updating Routing Manager and BTS. If POLICY type subscription already exists, request is forwarded to BTS and successful response is sent to xApp.
 249     BTS is expected to accept duplicate POLICY type requests. In restart IP address of the xApp may change but domain service address name does not.
 250     RMR message routing uses domain service address name.
 251
 252   * Subscription Manager restart
 253
 254     Subscription Manager stores successfully described subscriptions from db (SDL). Subscriptions are restored from db in restart. For subscriptions which
 255     were not successfully completed, Subscription Manager sends delete request to BTS and removes routes created for those. Restoring subscriptions from
 256     db can be disable via submgr-config.yaml file by setting "readSubsFromDb": "false".
 257
 258 Metrics
 259 -------
 260  Subscription Manager adds following statistic counters:
 261
 262  Subscription create counters:
 263                 - SubReqFromXapp: The total number of SubscriptionRequest messages received from xApp
 264                 - SubRespToXapp: The total number of SubscriptionResponse messages sent to xApp
 265                 - SubFailToXapp: The total number of SubscriptionFailure messages sent to xApp
 266                 - SubReqToE2: The total number of SubscriptionRequest messages sent to E2Term
 267                 - SubReReqToE2: The total number of SubscriptionRequest messages resent to E2Term
 268                 - SubRespFromE2: The total number of SubscriptionResponse messages from E2Term
 269                 - SubFailFromE2: The total number of SubscriptionFailure messages from E2Term
 270                 - SubReqTimerExpiry: The total number of SubscriptionRequest timer expires
 271                 - RouteCreateFail: The total number of subscription route create failure
 272                 - RouteCreateUpdateFail: The total number of subscription route create update failure
 273                 - MergedSubscriptions: The total number of merged Subscriptions
 274
 275  Subscription delete counters:
 276                 - SubDelReqFromXapp: The total number of SubscriptionDeleteResponse messages received from xApp
 277                 - SubDelRespToXapp: The total number of SubscriptionDeleteResponse messages sent to xApp
 278                 - SubDelReqToE2: The total number of SubscriptionDeleteRequest messages sent to E2Term
 279                 - SubDelReReqToE2: The total number of SubscriptionDeleteRequest messages resent to E2Term
 280                 - SubDelRespFromE2: The total number of SubscriptionDeleteResponse messages from E2Term
 281                 - SubDelFailFromE2: The total number of SubscriptionDeleteFailure messages from E2Term
 282                 - SubDelReqTimerExpiry: The total number of SubscriptionDeleteRequest timer expires
 283                 - RouteDeleteFail: The total number of subscription route delete failure
 284                 - RouteDeleteUpdateFail: The total number of subscription route delete update failure
 285                 - UnmergedSubscriptions: The total number of unmerged Subscriptions
 286
 287  SDL failure counters:
 288                 - SDLWriteFailure: The total number of SDL write failures
 289                 - SDLReadFailure: The total number of SDL read failures
 290                 - SDLRemoveFailure: The total number of SDL read failures
 291
 292 Configurable parameters
 293 -----------------------
 294  Subscription Manager has following configurable parameters.
 295    - Retry timeout for RIC Subscription Request message
 296       - e2tSubReqTimeout_ms: 2000 is the default value
 297
 298    - Retry timeout for RIC Subscription Delete Request message
 299       - e2tSubDelReqTime_ms: 2000 is the default value
 300
 301    - Waiting time for RIC Subscription Response and RIC Subscription Delete Response messages
 302       - e2tRecvMsgTimeout_ms: 2000 is the default value
 303
 304    - Try count for RIC Subscription Request message
 305       - e2tMaxSubReqTryCount: 2 is the default value
 306
 307    - Try count for RIC Subscription Delete Request message
 308       - e2tMaxSubDelReqTryCount: 2 is the default value
 309
 310    - Are subscriptions read from database in Subscription Manager startup
 311       - readSubsFromDb: "true"  is the default value
 312
 313  The parameters can be changed on the fly via Kubernetes Configmap. Default parameters values are defined in Helm chart
 314
 315  Use following command to open Subscription Manager's Configmap in Nano editor. Firts change parameter and then store the
 316  change by pressing first Ctrl + o. Close editor by pressing the Ctrl + x. The change is visible in Subscription Manager's
 317  log after some 20 - 30 seconds.
 318
 319  .. code-block:: none
 320
 321   KUBE_EDITOR="nano" kubectl edit cm configmap-ricplt-submgr-submgrcfg -n ricplt
 322
 323 REST interface for debugging and testing
 324 ----------------------------------------
 325  Give following commands to get Subscription Manager pod's IP address
 326
 327  .. code-block:: none
 328
 329   kubectl get pods -A | grep submgr
 330
 331   ricplt        submgr-75bccb84b6-n9vnt          1/1     Running             0          81m
 332
 333   Syntax: kubectl exec -t -n ricplt <add-submgr-pod-name> -- cat /etc/hosts | grep submgr | awk '{print $1}'
 334
 335   Example: kubectl exec -t -n ricplt submgr-75bccb84b6-n9vnt -- cat /etc/hosts | grep submgr | awk '{print $1}'
 336
 337   10.244.0.181
 338
 339  Get metrics
 340
 341  .. code-block:: none
 342
 343   Example: curl -s GET "http://10.244.0.181:8080/ric/v1/metrics"
 344
 345  Get subscriptions
 346
 347  .. code-block:: none
 348
 349   Example: curl -X GET "http://10.244.0.181:8088/ric/v1/subscriptions"
 350
 351  Delete single subscription from db
 352
 353  .. code-block:: none
 354
 355   Syntax: curl -X POST "http://10.244.0.181:8080/ric/v1/test/deletesubid={SubscriptionId}"
 356
 357   Example: curl -X POST "http://10.244.0.181:8080/ric/v1/test/deletesubid=1"
 358
 359  Remove all subscriptions from db
 360
 361  .. code-block:: none
 362
 363   Example: curl -X POST "http://10.244.0.181:8080/ric/v1/test/emptydb"
 364
 365  Make Subscription Manager restart
 366
 367  .. code-block:: none
 368
 369   Example: curl -X POST "http://10.244.0.181:8080/ric/v1/test/restart"
 370
 371  Use this command to get Subscription Manager's log writings
 372
 373  .. code-block:: none
 374
 375    Example: kubectl logs -n ricplt submgr-75bccb84b6-n9vnt
 376
 377  Logger level in configmap.yaml file in Helm chart is by default 2. It means that only info logs are printed.
 378  To see debug log writings it has to be changed to 4.
 379
 380  .. code-block:: none
 381
 382     "logger":
 383       "level": 4
 384
 385 RAN services explained
 386 ----------------------
 387   RIC hosted xApps may use the following RAN services from a RAN node:
 388
 389   *  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
 390   *  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
 391   *  CONTROL: RIC sends a Control message to RAN to initiate or resume call processing in RAN
 392   *  POLICY: RIC requests that RAN executes a specific POLICY during call processing in RAN after each occurrence of a defined SUBSCRIPTION
 393
 394 Supported E2 procedures and RAN services
 395 ----------------------------------------
 396     * RIC Subscription procedure with following RIC action types:
 397
 398       - REPORT
 399       - POLICY
 400       - INSERT
 401
 402     * RIC Subscription Delete procedure
 403
 404     * Merge and delete of equal REPORT type subscriptions.
 405
 406 Recommendations for xApps
 407 -------------------------
 408
 409    * Recommended retry delay in xApp
 410
 411      Recommended retry delay for xApp is >= 5 seconds. Length of supervising timers in Subscription Manager for the requests it sends to BTS is by default 2
 412      seconds. Subscription Manager makes one retry by default. There can be only one ongoing request towards per RAN other requests are queued in Subscription
 413      Manager.