Build related cleanup. Entrypoint to read config from correct place.
[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 * 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 ```