README.md

   1 # RIC xApp Manager
   2
   3 Provides a flexible and secure way for deploying and managing various RIC xApp applications.
   4
   5 ## Communication Interfaces (draft for R0)
   6 * Northbound (External)
   7   * RESTful API
   8 * Southbound (internal)
   9   * Helm  (Package manager for Kubernetes)
  10
  11 ## REST services for XApp managements
  12 ```sh
  13 Action                      URL                                 Method
  14
  15 Deploy                      /ric/v1/xapps                       POST
  16 Undeploy                    /ric/v1/xapps/{xappName}            DELETE
  17 Query Xapp Status           /ric/v1/xapps/{xappName}            GET
  18 Query Xapp Instance Status  /ric/v1/xapps/instances/{xappName}  GET
  19 Query All Xapp Status       /ric/v1/xapps                       GET
  20 Health Check                /ric/v1/health                      GET
  21 ```
  22
  23 ## REST services for subscriptions (resthooks)
  24 ```sh
  25 Action                      URL                                 Method
  26
  27 Add A Subscription          /ric/v1/subscriptions               POST
  28 Update A Subscription       /ric/v1/subscriptions/{id}          PUT
  29 Delete A Subscription       /ric/v1/subscriptions/{id}          DELETE
  30 Get A Subscription          /ric/v1/subscriptions               GET
  31 Get All Subscriptions       /ric/v1/subscriptions/{id}          GET
  32 ```
  33
  34 ## Used RIC platform services
  35 TBD later
  36
  37 ## Prerequisites
  38 Make sure that following tools are properly installed and configured
  39 * GO (golang) development and runtime tools
  40 * mdclog (com/log)
  41 * Docker
  42 * Kubernates and related tools (kubectl and helm)
  43 * Xapp Docker repo (either local or remote)
  44 * Xapp Helm charts
  45 * ...
  46
  47 ## Building go binary and docker container for xApp Manager
  48  ```sh
  49 # Run following command. Make sure that mdclog is installed and found in the standard library path
  50 make docker-build
  51 ```
  52
  53 ## Running xApp Manager unit tests
  54  ```sh
  55 # Run following command
  56 make test
  57 ```
  58
  59 ## Running xApp Manager locally
  60 ```sh
  61 # Now run the xApp manager
  62 build/appmgr -f config/appmgr.yaml
  63 ```
  64
  65 # Running Docker container of xApp manager
  66 ```sh
  67 make docker-run
  68 ```
  69
  70 # Deploy, undeploying xApps and querying status (using CURL command)
  71 ```sh
  72 # Deploy a new xApp instance with the name 'dummy-xapp'
  73 curl -H "Content-Type: application/json" -X POST http://172.17.0.3:8080/ric/v1/xapps -d '{"name": "dummy-xapp"}'
  74 ```
  75
  76 ```sh
  77 # Query the status of all xApp applications
  78 curl -H "Content-Type: application/json" http://localhost:8080/ric/v1/xapps
  79 % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
  80                                  Dload  Upload   Total   Spent    Left  Speed
  81 100    95  100    95    0     0  95000      0 --:--:-- --:--:-- --:--:-- 95000
  82 [
  83     {
  84         "name": "dummy-xapp",
  85         "status": "DEPLOYED",
  86         "version": "1.0",
  87         "instances": [
  88             {
  89                 "name": "dummy-xapp-8984fc9fd-8jq9q",
  90                 "status": "Running",
  91                 "ip": "10.99.213.161",
  92                 "port": 80,
  93                 "txMessages": "[]",
  94                 "rxMessages": "[]"
  95             },
  96             {
  97                 "name": "dummy-xapp-8984fc9fd-zq47z",
  98                 "status": "Running",
  99                 "ip": "10.99.213.161",
 100                 "port": 80,
 101                 "txMessages": "[]",
 102                 "rxMessages": "[]"
 103             },
 104             {
 105                 "name": "dummy-xapp-8984fc9fd-zzxjj",
 106                 "status": "Running",
 107                 "ip": "10.99.213.161",
 108                 "port": 80,
 109                 "txMessages": "[]",
 110                 "rxMessages": "[]"
 111             }
 112         ]
 113     }
 114 ]
 115 ```
 116 ```sh
 117 # Query the status of a sigle xApp (using the xApp name)
 118 curl -H "Content-Type: application/json"  http://localhost:8080/ric/v1/xapps/dummy-xapp
 119 % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
 120                                  Dload  Upload   Total   Spent    Left  Speed
 121 100    95  100    95    0     0  95000      0 --:--:-- --:--:-- --:--:-- 95000
 122 {
 123     "name": "dummy-xapp",
 124     "status": "DEPLOYED",
 125     "version": "1.0",
 126     "instances": [
 127         {
 128             "name": "dummy-xapp-8984fc9fd-8jq9q",
 129             "status": "Running",
 130             "ip": "10.99.213.161",
 131             "port": 80,
 132             "txMessages": "[]",
 133             "rxMessages": "[]"
 134         },
 135         {
 136             "name": "dummy-xapp-8984fc9fd-zq47z",
 137             "status": "Running",
 138             "ip": "10.99.213.161",
 139             "port": 80,
 140             "txMessages": "[]",
 141             "rxMessages": "[]"
 142         },
 143         {
 144             "name": "dummy-xapp-8984fc9fd-zzxjj",
 145             "status": "Running",
 146             "ip": "10.99.213.161",
 147             "port": 80,
 148             "txMessages": "[]",
 149             "rxMessages": "[]"
 150         }
 151     ]
 152 }
 153 ```
 154 ```sh
 155 # Query the status of a sigle xApp instance (using the xApp instance name)
 156 curl -H "Content-Type: application/json"  http://localhost:8080/ric/v1/xapps/dummy-xapp
 157 % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
 158                                  Dload  Upload   Total   Spent    Left  Speed
 159 100    95  100    95    0     0  95000      0 --:--:-- --:--:-- --:--:-- 95000
 160 {
 161     "name": "dummy-xapp-8984fc9fd-8jq9q",
 162     "status": "Running",
 163     "ip": "10.99.213.161",
 164     "port": 80,
 165     "txMessages": "[]",
 166     "rxMessages": "[]"
 167 }
 168 ```
 169 ```sh
 170 # Undeploy xApp by name
 171 curl -H "Content-Type: application/json"  -X DELETE http://localhost:8080/ric/v1/xapps/dummy-xapp
 172 ```
 173
 174 # Health Check Probes (using CURL command)
 175 ```sh
 176 # Health Check using CURL
 177 curl -H "Content-Type: application/json" http://10.244.1.47:8080/ric/v1/health --verbose
 178 *   Trying 10.244.1.47...
 179 * TCP_NODELAY set
 180 * Connected to 10.244.1.47 (10.244.1.47) port 8080 (#0)
 181 > GET /ric/v1/health HTTP/1.1
 182 > Host: 10.244.1.47:8080
 183 > User-Agent: curl/7.58.0
 184 > Accept: */*
 185 > Content-Type: application/json
 186 >
 187 < HTTP/1.1 200 OK
 188 < Content-Type: application/json
 189 < Date: Sun, 24 Mar 2019 11:13:59 GMT
 190 < Content-Length: 0
 191 <
 192 * Connection #0 to host 10.244.1.47 left intact
 193 ```
 194
 195 # Subsciptions: List, create, update and delete (using CURL command)
 196 ```sh
 197 # Add a new subscription
 198 curl -H "Content-Type: application/json" http://172.17.0.3:8080/ric/v1/subscriptions -X POST -d '{"maxRetries": 3, "retryTimer": 5, "eventType":"Created", "targetUrl": "http://192.168.0.12:8088/"}'
 199
 200   % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
 201                                  Dload  Upload   Total   Spent    Left  Speed
 202 100   169  100    70  100    99  17500  24750 --:--:-- --:--:-- --:--:-- 56333
 203 {
 204     "id": "1ILBltYYzEGzWRrVPZKmuUmhwcc",
 205     "version": 0,
 206     "eventType": "Created"
 207 }
 208 ```
 209 ```sh
 210 # List all subscriptions
 211 curl -H "Content-Type: application/json" http://172.17.0.3:8080/ric/v1/subscriptions
 212   % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
 213                                  Dload  Upload   Total   Spent    Left  Speed
 214 100   259  100   259    0     0   252k      0 --:--:-- --:--:-- --:--:--  252k
 215 [
 216     {
 217         "id": "1ILBZTtEVVtQmIZnh1OJdBP7bcR",
 218         "targetUrl": "http://192.168.0.12:8088/",
 219         "eventType": "Created",
 220         "maxRetries": 3,
 221         "retryTimer": 5
 222     },
 223     {
 224         "id": "1ILBltYYzEGzWRrVPZKmuUmhwcc",
 225         "targetUrl": "http://192.168.0.12:8088/",
 226         "eventType": "Created",
 227         "maxRetries": 3,
 228         "retryTimer": 5
 229     }
 230 ]
 231 ```
 232
 233 ```sh
 234 # Get a specific subscription by Id
 235 curl -H "Content-Type: application/json" http://172.17.0.3:8080/ric/v1/subscriptions/1ILBZTtEVVtQmIZnh1OJdBP7bcR
 236   % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
 237                                  Dload  Upload   Total   Spent    Left  Speed
 238 100   128  100   128    0     0   125k      0 --:--:-- --:--:-- --:--:--  125k
 239 {
 240     "id": "1ILBZTtEVVtQmIZnh1OJdBP7bcR",
 241     "targetUrl": "http://192.168.0.12:8088/",
 242     "eventType": "Created",
 243     "maxRetries": 3,
 244     "retryTimer": 5
 245 }
 246 ```
 247
 248 ```sh
 249 # Delete a specific subscription by Id
 250 curl -H "Content-Type: application/json" http://172.17.0.3:8080/ric/v1/subscriptions/1ILBZTtEVVtQmIZnh1OJdBP7bcR -X DELETE
 251   % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
 252                                  Dload  Upload   Total   Spent    Left  Speed
 253   0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
 254 ```
 255
 256 ```sh
 257 # Example of subscription notification POSTed to targetUrl provided by the client
 258
 259 {
 260         "id": "1ILBltYYzEGzWRrVPZKmuUmhwcc",
 261         "version": 0,
 262         "eventType": "Created",
 263         "xapp": {
 264                 "name": "dummy-xapp",
 265                 "status": "DEPLOYED",
 266                 "version": "1.0",
 267                 "instances": [
 268                         {
 269                                 "name": "dummy-xapp-8984fc9fd-lh7r2",
 270                                 "status": "ContainerCreating",
 271                                 "ip": "10.104.73.185",
 272                                 "port": 80,
 273                                 "txMessages": "[]",
 274                                 "rxMessages": "[]"
 275                         },
 276                         {
 277                                 "name": "dummy-xapp-8984fc9fd-lzrdk",
 278                                 "status": "Pending",
 279                                 "ip": "10.104.73.185",
 280                                 "port": 80,
 281                                 "txMessages": "[]",
 282                                 "rxMessages": "[]"
 283                         },
 284                         {
 285                                 "name": "dummy-xapp-8984fc9fd-xfjcn",
 286                                 "status": "Pending",
 287                                 "ip": "10.104.73.185",
 288                                 "port": 80,
 289                                 "txMessages": "[]",
 290                                 "rxMessages": "[]"
 291                         }
 292                 ]
 293         }
 294 }
 295 ```
 296
 297 # Using xapp manager CLI (appmgrcli) to manage xapps (deploy, get, undeploy, etc)
 298
 299 Run command *appmgrcli help* for short usage instructions, or read the
 300 script source; the instructions can be found as plain text near the
 301 beginning.
 302
 303 Unlike direct curl commands, using the *appmgrcli* validates some of
 304 the parameters, and there is usually less to type...
 305
 306 The host and port where the xapp manager is running are given by
 307 options *-h* and *-p*, or you can define environment variables
 308 APPMGR_HOST and APPMGR_PORT to specify them (recommended). The
 309 following examples assume they have been specified.
 310
 311 ```sh
 312 # Deploy a xapp
 313
 314 $ appmgrcli deploy dummy-xapp
 315 {
 316     "name": "dummy-xapp",
 317     "status": "DEPLOYED",
 318     "version": "1.0",
 319     "instances": [
 320         {
 321             "name": "dummy-xapp-667dfc9bfb-wd5m9",
 322             "status": "Pending",
 323             "ip": "",
 324             "port": 0,
 325             "txMessages": "",
 326             "rxMessages": ""
 327         }
 328     ]
 329 }
 330
 331 # Undeploy
 332
 333 $ appmgrcli undeploy dummy-xapp
 334 dummy-xapp undeployed
 335
 336 # Add some subscriptions
 337
 338 $ appmgrcli subscriptions add https://kukkuu.reset created 500 600
 339 {
 340     "id": "1IoQqEI24sPfLkq8prmMqk6Oz1I",
 341     "version": 0,
 342     "eventType": "created"
 343 }
 344 $ appmgrcli subscriptions add https://facebook.com all 10 4
 345 {
 346     "id": "1IoR85ZwgiNiIn82phUR6qJmBvq",
 347     "version": 0,
 348     "eventType": "all"
 349 }
 350
 351 # list and delete (also shows using abbreviations):
 352
 353
 354 $ appmgrcli subs list
 355 [
 356     {
 357         "id": "1IoQqEI24sPfLkq8prmMqk6Oz1I",
 358         "targetUrl": "https://kukkuu.reset",
 359         "eventType": "created",
 360         "maxRetries": 500,
 361         "retryTimer": 600
 362     },
 363     {
 364         "id": "1IoR85ZwgiNiIn82phUR6qJmBvq",
 365         "targetUrl": "https://facebook.com",
 366         "eventType": "all",
 367         "maxRetries": 10,
 368         "retryTimer": 4
 369     }
 370 ]
 371
 372 $ appmgrcli subs del 1IoR85ZwgiNiIn82phUR6qJmBvq
 373 Subscription 1IoR85ZwgiNiIn82phUR6qJmBvq deleted
 374
 375 $ appmgrcli subs list
 376 [
 377     {
 378         "id": "1IoQqEI24sPfLkq8prmMqk6Oz1I",
 379         "targetUrl": "https://kukkuu.reset",
 380         "eventType": "created",
 381         "maxRetries": 500,
 382         "retryTimer": 600
 383     }
 384 ]
 385
 386 ```
 387
 388 # Additional info
 389 ```sh
 390 Todo
 391 ```