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