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
  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 Radio Access Network (RAN).
  30
  31 xApp can subscribe and unsubscribe messages from gNodeB through Subscription Manager. Subscription Manager manages the subscriptions
  32 and message routing of the subscribed messages between E2 Termination and xApps. If one xApp has already made a subscription and then
  33 another xApp initiates identical subscription, Subscription Manager does not forward the subscription to gNodeB 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 There can be only one ongoing RIC Subscription or RIC Subscription Delete procedure towards RAN at any time. That is because Subscription
  38 Manager is able to merge new subscriptions only which those it has already received successful response from RAN. Subscriptions
  39 and delete subscriptions are therefore queued in Subscription Manager. Subscription Manager may need to do reties during subscribe or
  40 unsubscribe procedure. This needs to be considered when retries are implemented in xApp side, as it can increase completion time of the
  41 procedure. xApp's retry delay should not be too short.
  42
  43     .. image:: images/PlaceInRICSoftwareArchitecture.png
  44       :width: 600
  45       :alt: Place in RIC's software architecture picture
  46
  47 Architecture
  48 ------------
  49
  50   * Message routing
  51
  52       Subscribed messages from RAN are transported to RIC inside RIC Indication message. RIC Indication message is transported to xApp
  53       inside RMR message, in Payload field of the RMR message. RMR message is routed to xApp based on SubId field (subscription id) in
  54       the RMR header. Same routing mechanism is used also for response messages from Subscription Manager to xApp. Subscription Manager is
  55       not able to respond to xApp if route for subscription has not been created.
  56
  57       When xApp sends message to Subscription Manager it sets -1 in SubId field in the RMR header. It means that messages are routed based
  58       on message type (Mtype filed in RMR header). RIC Subscription Request and RIC Subscription delete Request messages are pre configured
  59       to be routed to Subscription Manager.
  60
  61       Subscription Manager allocates unique RIC Request Sequence Number for every subscription during Subscription procedure. Subscription
  62       Manager replaces existing ASN.1 decoded RIC Request Sequence Number in the RIC Subscription Request message allocated by the xApp.
  63       That sequence number (subscription id) is then used for the subscription in RIC and RAN as long the subscription lives. xApp gets
  64       the sequence number in RIC Subscription Response message from Subscription manager based on the message types.
  65
  66       Subscribed messages are routed to xApps based on sequence number. Sequence number is placed in the SubId field of the RMR message
  67       header when E2 Termination sends the subscribed message to xApp. When xApp wants to delete the subscription, the same sequence number
  68       must be included in the ASN.1 encoded RIC Subscription Delete Request message sent to Subscription Manager.
  69
  70       Subscription Manager allocates RIC Requestor ID. Currently the ID value is always 123. In merge case subscription is created only for
  71       the first requestor. RAN gets the Request of the xApp who makes the first subscription. RAN uses Subscription Manager allocated Requestor
  72       ID in all RIC Indication messages it sends to RIC for the subscription.
  73
  74       TransactionId (Xid) in RMR message header is used to track messages between xApp and Subscription Manager. xApp allocates it. Subscription
  75       Manager returns TransactionId received from xApp in response message to xApp. xApp uses it to map response messages to request messages
  76       it sends.
  77
  78   * Subscription procedure
  79
  80     * Successful case
  81
  82       xApp sends RIC Subscription Request message to Subscription Manager. Subscription Manager validates request types in the message and sends
  83       route create to Routing Manager over REST interface. When route is created successfully Subscription Manager forwards request to E2
  84       Termination. When RIC Subscription Response arrives from E2 Termination Subscription Manager forwards it to xApp.
  85
  86       Subscription Manager supervises route create and RIC Subscription Request with a timer.
  87
  88       RIC Indication messages which are used to transport subscribed messages from RAN are routed from E2 Termination to xApps
  89       directly using the routes created during Subscription procedure.
  90
  91       Subscription Manager supports REPORT, POLICY and INSERT type subscriptions (RICActionTypes). CONTROL is not supported. POLICY type
  92       subscription can be updated. In update case signaling sequence is the same as above, except route is not created to Routing manager.
  93       xApp uses initially allocated TransactionId and RIC Request Sequence Number in update case. Route in POLICY type subscription case is needed
  94       only that Subscription Manager can send response messages to xApp. RIC Subscription Request message contains list of RICaction-ToBeSetup-ItemIEs.
  95       The list cannot have REPORT, POLICY, INSERT action types at the same time. Subscription Manager checks actions types in the message.
  96       If both action types is found the message is dropped.
  97
  98
  99     .. image:: images/Successful_Subscription.png
 100       :width: 600
 101       :alt: Successful subscription picture
 102
 103
 104     * Failure case
 105
 106       In failure case Subscription Manager checks the failure cause and acts based on that. If failure cause is "duplicate" Subscription
 107       Manager sends delete to RAN and then resends the same subscription. If failure cause is such that Subscription manager cannot do
 108       anything to fix the problem, it sends delete to RAN and sends RIC Subscription Failure to xApp. Subscription Manager may retry RIC
 109       Subscription Request and RIC Subscription Delete messages also in this case before it responds to xApp.
 110
 111     .. image:: images/Subscription_Failure.png
 112       :width: 600
 113       :alt: Subscription failure picture
 114
 115     * Timeout in Subscription Manager
 116
 117      In case of timeout in Subscription Manager, Subscription Manager may resend the RIC Subscription Request to RAN. If there is no response
 118       after retry, Subscription Manager shall NOT send any response to xApp. xApp may retry RIC Subscription Request, if it wishes to do so.
 119       Subscription Manager does no handle the retry if Subscription Manager has ongoing subscription procedure for the same subscription.
 120       Subscription just drops the request.
 121
 122     * Timeout in xApp
 123
 124       xApp may resend the same request if there is no response in expected time. If xApp resends the same request while processing of previous
 125       request has not been completed in Subscription Manager then Subscription Manager drops the new request, makes a log writing and continues
 126       processing previous request.
 127
 128     .. image:: images/Subscription_Timeout.png
 129       :width: 600
 130       :alt: Subscription timeout picture
 131
 132   * Subscription delete procedure
 133
 134     * Successful case
 135
 136       xApp sends RIC Subscription Delete Request message to Subscription Manager. xApp must use the same RIC Request Sequence Number which
 137       it received in RIC Subscription Response message when subscription is deleted. When Subscription Manager receives RIC Subscription
 138       Delete Request message, Subscription Manager first forwards the request to E2 Termination. When RIC Subscription Delete Response arrives
 139       from E2 Termination to Subscription Manager, Subscription Manager forwards it to xApp and then request route deletion from Routing Manager.
 140
 141       Subscription Manager supervises RIC Subscription Deletion Request and route delete with a timer.
 142
 143     .. image:: images/Successful_Subscription_Delete.png
 144       :width: 600
 145       :alt: Successful subscription delete picture
 146
 147     * Failure case
 148
 149       Delete procedure cannot fail from xApp point of view. Subscription Manager always responds with RIC Subscription Delete Response to xApp.
 150
 151     .. image:: images/Subscription_Delete_Failure.png
 152       :width: 600
 153       :alt: Subscription delete failure picture
 154
 155     * Timeout in Subscription Manager
 156
 157       In case of timeout in Subscription Manager, Subscription Manager may resend the RIC Subscription Delete Request to RAN. If there is no
 158       response after retry, Subscription Manager responds to xApp with RIC Subscription Delete Response.
 159
 160     * Timeout in xApp
 161
 162       xApp may resend the same request if there is no response in expected time. If xApp resends the same request while processing of previous
 163       request has not been completed in Subscription Manager then Subscription Manager drops the new request, makes a log writing and continues
 164       processing previous request.
 165
 166     .. image:: images/Subscription_Delete_Timeout.png
 167       :width: 600
 168       :alt: Subscription delete timeout picture
 169
 170     * Unknown subscription
 171
 172       If Subscription Manager receives RIC Subscription Delete Request for a subscription which does not exist, Subscription Manager cannot respond
 173       to xApp as there is no route for the subscription.
 174
 175   * Subscription merge procedure
 176
 177     * Successful case
 178
 179       xApp sends RIC Subscription Request message to Subscription Manager. Subscription Manager checks is the Subscription mergeable. If not,
 180       Subscription Manager continues with normal Subscription procedure. If Subscription is mergeable, Subscription Manager sends route create
 181       to Routing Manager and then responds with RIC Subscription Response to xApp.
 182
 183       Route create is supervised with a timer.
 184
 185       Merge for REPORT type subscription is possible if Action Type and Event Trigger Definition of subscriptions are equal.
 186
 187       ``Only REPORT type subscriptions can be be merged.``
 188
 189     .. image:: images/Successful_Subscription_Merge.png
 190       :width: 600
 191       :alt: Successful subscription merge picture
 192
 193     * Failure case
 194
 195       Failure case is basically the same as in normal subscription procedure. Failure can come only from RAN when merge is not yet done.
 196       If error happens during route create Subscription Manager drops the RIC Subscription Request message and xApp does not get any response.
 197
 198     * Timeout in Subscription Manager
 199
 200       Timeout case is basically the same as in normal subscription procedure but timeout can come only in route create during merge operation.
 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 xApp
 204
 205       xApp may resend the same request if there is no response in expected time. If xApp resends the same request while processing of previous
 206       request has not been completed in Subscription Manager then Subscription Manager drops the new request, makes a log writing and continues
 207       processing previous request.
 208
 209   * Subscription delete merge procedure
 210
 211     * Successful case
 212
 213       xApp sends RIC Subscription Delete Request message to Subscription Manager. If delete concerns merged subscription, Subscription Manager
 214       responds with RIC Subscription Delete Response to xApp and then sends route delete request to Routing manager.
 215
 216       Subscription Manager supervises route delete with a timer.
 217
 218     .. image:: images/Successful_Subscription_Delete_Merge.png
 219       :width: 600
 220       :alt: Successful subscription delete merge picture
 221
 222     * Failure case
 223
 224       Delete procedure cannot fail from xApp point of view. Subscription Manager responds with RIC Subscription Delete Response message to xApp.
 225
 226     * Timeout in Subscription Manager
 227
 228       Timeout can only happen in route delete to Routing manager. Subscription Manager responds with RIC Subscription Delete Response message to xApp.
 229
 230     * Timeout in xApp
 231
 232       xApp may resend the same request if there is no response in expected time. If xApp resends the same request while processing of previous
 233       request has not been completed in Subscription Manager then Subscription Manager drops the new request, makes a log writing and continues
 234       processing previous request.
 235
 236   * Unknown message
 237
 238      If Subscription Manager receives unknown message, Subscription Manager drops the message.
 239
 240   * xApp restart
 241
 242     When xApp is restarted for any reason it may resend subscription requests for subscriptions which have already been subscribed. If REPORT or INSERT type
 243     subscription already exists and RMR endpoint of requesting xApp is attached to subscription then successful response is sent to xApp directly without
 244     updating Routing Manager and BTS. If POLICY type subscription already exists, request is forwarded to BTS and successful response is sent to xApp.
 245     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.
 246     RMR message routing uses domain service address name.
 247
 248   * Subscription Manager restart
 249
 250     Subscription Manager stores successfully described subscriptions from db (SDL). Subscriptions are restored from db in restart. For subscriptions which
 251     were not successfully completed, Subscription Manager sends delete request to BTS and removes routes created for those. Restoring subscriptions from
 252     db can be disable via submgr-config.yaml file by setting "readSubsFromDb": "false".
 253
 254 REST interface for debugging and testing
 255 ----------------------------------------
 256  Give following commands to get Subscription Manager pod's IP address
 257
 258  .. code-block:: none
 259
 260   kubectl get pods -A | grep submgr
 261
 262   ricplt        submgr-75bccb84b6-n9vnt          1/1     Running             0          81m
 263
 264   Syntax: kubectl exec -t -n ricplt <add-submgr-pod-name> -- cat /etc/hosts | grep submgr | awk '{print $1}'
 265
 266   Example: kubectl exec -t -n ricplt submgr-75bccb84b6-n9vnt -- cat /etc/hosts | grep submgr | awk '{print $1}'
 267
 268   10.244.0.181
 269
 270  Get subscriptions
 271
 272  .. code-block:: none
 273
 274   Example: curl -X GET "http://10.244.0.181:8088/ric/v1/subscriptions"
 275
 276   []
 277
 278  Delete single subscription from db
 279
 280  .. code-block:: none
 281
 282   Syntax: curl -X POST "http://10.244.0.181:8080/ric/v1/test/deletesubid={SubscriptionId}"
 283
 284   Example: curl -X POST "http://10.244.0.181:8080/ric/v1/test/deletesubid=1"
 285
 286  Remove all subscriptions from db
 287
 288  .. code-block:: none
 289
 290   Example: curl -X POST "http://10.244.0.181:8080/ric/v1/test/emptydb"
 291
 292  Make Subscription Manager restart
 293
 294  .. code-block:: none
 295
 296   Example: curl -X POST "http://10.244.0.181:8080/ric/v1/test/restart"
 297
 298  Use this command to get Subscription Manager's log writings
 299
 300  .. code-block:: none
 301
 302    Example: kubectl logs -n ricplt submgr-75bccb84b6-n9vnt
 303
 304  Logger level in configmap.yaml file in Helm chart is by default 2. It means that only info logs are printed.
 305  To see debug log writings it has to be changed to 4.
 306
 307  .. code-block:: none
 308
 309     "logger":
 310       "level": 4
 311
 312 RAN services explained
 313 ----------------------
 314   RIC hosted xApps may use the following RAN services from a RAN node:
 315
 316   *  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
 317   *  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
 318   *  CONTROL: RIC sends a Control message to RAN to initiate or resume call processing in RAN
 319   *  POLICY: RIC requests that RAN executes a specific POLICY during call processing in RAN after each occurrence of a defined SUBSCRIPTION
 320
 321 Supported E2 procedures and RAN services
 322 ----------------------------------------
 323     * RIC Subscription procedure with following RIC action types:
 324
 325       - REPORT
 326       - POLICY
 327       - INSERT
 328
 329     * RIC Subscription Delete procedure
 330
 331     * Merge and delete of equal REPORT type subscriptions.
 332
 333 Recommendations for xApps
 334 -------------------------
 335
 336    * Recommended retry delay in xApp
 337
 338      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
 339      seconds. Subscription Manager makes one retry by default. There can be only one ongoing request towards per RAN other requests are queued in Subscription
 340      Manager.