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