Initial version with full functionality
[ric-plt/appmgr.git] / 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 ```