summaryrefslogtreecommitdiffstats
path: root/docs/apex/APEX-Introduction.rst
blob: 8c9b34b578220b16c76e3713764ef87e78a6e3f1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0


A short Introduction to APEX
****************************

.. contents::
    :depth: 3

Introduction to APEX
^^^^^^^^^^^^^^^^^^^^

      .. container:: sectionbody

         .. container:: paragraph

            APEX stand for Adaptive Policy EXecution. It is a
            lightweight engine for execution of policies. APEX allows
            you to specify logic as a policy, logic that you can adapt
            on the fly as your system executes. The APEX policies you
            design can be really simple, with a single snippet of logic,
            or can be very complex, with many states and tasks. APEX
            policies can even be designed to self-adapt at execution
            time, the choice is yours!

         .. container:: imageblock

            .. container:: content

               |Simple APEX Overview|

            .. container:: title

               Figure 1. Simple APEX Overview

         .. container:: paragraph

            The Adaptive Policy Engine in APEX runs your policies. These
            policies are triggered by incoming events. The logic of the
            policies executes and produces a response event. The
            *Incoming Context* on the incoming event and the *Outgoing
            Context* on the outgoing event are simply the fields and
            attributes of the event. You design the policies that APEX
            executes and the trigger and action events that your
            policies accept and produce. Events are fed in and sent out
            as JSON or XML events over Kafka, a Websocket, a file or
            named pipe, or even standard input. If you run APEX as a
            library in your application, you can even feed and receive
            events over a Java API.

         .. container:: imageblock

            .. container:: content

               |APEX States and Context|

            .. container:: title

               Figure 2. APEX States and Context

         .. container:: paragraph

            You design your policy as a chain of states, with each state
            being fed by the state before. The simplest policy can have
            just one state. We provide specific support for the
            four-state `MEDA (Match Establish Decide
            Act) <https://ieeexplore.ieee.org/document/7502880>`__
            policy state model and the three-state `ECA (Event Condition
            Action) <https://en.wikipedia.org/wiki/Event_condition_action>`__
            policy state model. APEX is fully distributed. You can
            decide how many APEX engine instances to run for your
            application and on which real or virtual hosts to run them.

         .. container:: paragraph

            In APEX, you also have control of the *Context* used by your
            policies. Context is simply the state information and data
            used by your policies. You define what context your policies
            use and what the scope of that context is. *Policy Context*
            is private to a particular policy and is accessible only to
            whatever APEX engines are running that particular policy.
            *Global Context* is available to all policies. *External
            Context* is read-only context such as weather or topology
            information that is provided by other systems. APEX keeps
            context coordinated across all the the instances running a
            particular policy. If a policy running in an APEX engine
            changes the value of a piece of context, that value is
            available to all other APEX engines that use that piece of
            context. APEX takes care of distribution, locking, writing
            of context to persistent storage, and monitoring of context.

         .. container:: imageblock

            .. container:: content

               |The APEX Eco-System|

            .. container:: title

               Figure 3. The APEX Eco-System

         .. container:: paragraph

            The APEX engine (AP-EN) is available as a Java library for
            inclusion in your application, as a microservice running in
            a Docker container, or as a stand-alone service available
            for integration into your system. APEX also includes a
            policy editor (AP-AUTH) that allows you to design your
            policies and a web-based policy management console you use
            to deploy policies and to keep track of the state of
            policies and context in policies. Context handling (AP-CTX)
            is integrated into the APEX engine and policy deployment
            (AP-DEP) is provided as a servlet running under a web
            framework such as `Apache
            Tomcat <http://tomcat.apache.org/>`__.

APEX Configuration
^^^^^^^^^^^^^^^^^^

      .. container:: sectionbody

         .. container:: paragraph

            An APEX engine can be configured to use various combinations
            of event input handlers, event output handlers, event
            protocols, context handlers, and logic executors. The system
            is built using a plugin architecture. Each configuration
            option is realized by a plugin, which can be loaded and
            configured when the engine is started. New plugins can be
            added to the system at any time, though to benefit from a
            new plugin, an engine will need to be restarted.

         .. container:: imageblock

            .. container:: content

               |APEX Configuration Matrix|

            .. container:: title

               Figure 4. APEX Configuration Matrix

         .. container:: paragraph

            The APEX distribution already comes with a number of
            plugins. The figure above shows the provided plugins. Any
            combination of input, output, event protocol, context
            handlers, and executors is possible.

APEX Policy Matrix
^^^^^^^^^^^^^^^^^^

      .. container:: sectionbody

         .. container:: paragraph

            APEX offers a lot of flexibility for defining, deploying,
            and executing policies. Based on a theoretic model, it
            supports virtually any policy model and supports translation of
            legacy policies into the APEX execution format. However, the
            most important aspect for using APEX is to decide what
            policy is needed, what underlying policy concepts should be
            used, and how the decision logic should be realized. Once
            these aspects are decided, APEX can be used to execute the
            policies. If the policy evolves, say from a simple decision
            table to a fully adaptable policy, only the policy
            definition requires change. APEX supports all of that.

         .. container:: paragraph

            The figure below shows a (non-exhaustive) matrix, which will
            help to decide what policy is required to solve your
            problem. Read the matrix from left to right choosing one
            cell in each column.

         .. container:: imageblock

            .. container:: content

               |APEX Policy Matrix|

            .. container:: title

               Figure 5. APEX Policy Matrix

         .. container:: paragraph

            The policy can support one of a number of stimuli with an
            associated purpose/model of the policy, for instance:

         .. container:: ulist

            -  Configuration, i.e. what should happen. An example is an
               event that states an intended network configuration and
               the policy should provide the detailed actions for it.
               The policy can be realized for instance as an obligation
               policy, a promise or an intent.

            -  Report, i.e. something did happen. An example is an event
               about an error or fault and the policy needs to repair
               that problem. The policy would usually be an obligation,
               utility function, or goal policy.

            -  Monitoring, i.e. something does happen. An example is a
               notification about certain network conditions, to which
               the policy might (or might not) react. The policy will
               mitigate the monitored events or permit (deny) related
               actions as an obligation or authorization.

            -  Analysis, i.e. why did something happen. An example is an
               analytic component sends insights of a situation
               requiring a policy to act on it. The policy can solve the
               problem, escalate it, or delegate it as a refrain or
               delegation policy.

            -  Prediction, i.e. what will happen next. An example are
               events that a policy uses to predict a future network
               condition. The policy can prevent or enforce the
               prediction as an adaptive policy, a utility function, or
               a goal.

            -  Feedback, i.e. why did something happen or not happen.
               Similar to analysis, but here the feedback will be in the
               input event and the policy needs to do something with that
               information. Feedback can be related to history or
               experience, for instance a previous policy execution. The
               policy needs to be context-aware or be a meta-policy.

         .. container:: paragraph

            Once the purpose of the policy is decided, the next step is
            to look into what context information the policy will
            require to do its job. This can range from very simple to a
            lot of different information, for instance:

         .. container:: ulist

            -  No context, nothing but a trigger event, e.g. a string or
               a number, is required

            -  Event context, the incoming event provides all
               information (more than a string or number) for the policy

            -  Policy context (read only), the policy has access to
               additional information related to its class but cannot
               change/alter them

            -  Policy context (read and write), the policy has access to
               additional information related to its class and can alter
               this information (for instance to record historic
               information)

            -  Global context (read only), the policy has access to
               additional information of any kind but cannot
               change/alter them

            -  Global context (read and write), the policy
               has access to additional information of any kind and can
               alter this information (for instance to record historic
               information)

         .. container:: paragraph

            The next step is to decide how the policy should do its job,
            i.e. what flavor it has, how many states are needed, and how
            many tasks. There are many possible combinations, for
            instance:

         .. container:: ulist

            -  Simple / God: a simple policy with 1 state and 1 task,
               which is doing everything for the decision-making. This
               is the ideal policy for simple situation, e.g. deciding
               on configuration parameters or simple access control.

            -  Simple sequence: a simple policy with a number of states
               each having a single task. This is a very good policy for
               simple decision-making with different steps. For
               instance, a classic action policy (ECA) would have 3
               states (E, C, and A) with some logic (1 task) in each
               state.

            -  Simple selective: a policy with 1 state but more than one
               task. Here, the appropriate task (and it’s logic) will be
               selected at execution time. This policy is very good for
               dealing with similar (or the same) situation in different
               contexts. For instance, the tasks can be related to
               available external software, or to current work load on
               the compute node, or to time of day.

            -  Selective: any number of states having any number of
               tasks (usually more than 1 task). This is a combination
               of the two policies above, for instance an ECA policy
               with more than one task in E, C, and A.

            -  Classic directed: a policy with more than one state, each
               having one task, but a non-sequential execution. This
               means that the sequence of the states is not pre-defined
               in the policy (as would be for all cases above) but
               calculated at runtime. This can be good to realize
               decision trees based on contextual information.

            -  Super Adaptive: using the full potential of the APEX
               policy model, states and tasks and state execution are
               fully flexible and calculated at runtime (per policy
               execution). This policy is very close to a general
               programming system (with only a few limitations), but can
               solve very hard problems.

         .. container:: paragraph

            The final step is to select a response that the policy
            creates. Possible responses have been discussed in the
            literature for a very long time. A few examples are:

         .. container:: ulist

            -  Obligation (deontic for what should happen)

            -  Authorization (e.g. for rule-based or other access
               control or security systems)

            -  Intent (instead of providing detailed actions the
               response is an intent statement and a further system
               processes that)

            -  Delegation (hand the problem over to someone else,
               possibly with some information or instructions)

            -  Fail / Error (the policy has encountered a problem, and
               reports it)

            -  Feedback (why did the policy make a certain decision)

Flexible Deployment
^^^^^^^^^^^^^^^^^^^

      .. container:: sectionbody

         .. container:: paragraph

            APEX can be deployed in various ways. The following figure
            shows a few of these deployment options. Engine and (policy)
            executors are named UPe (universal policy engine, APEX
            engine) and UPx (universal policy executor, the APEX
            internal state machine executor).

         .. container:: imageblock

            .. container:: content

               |APEX Deployment Options|

            .. container:: title

               Figure 6. APEX Deployment Options

         .. container:: olist loweralpha

            a. For an interface or class

               .. container:: ulist

                  -  Either UPx or UPe as association

            b. For an application

               .. container:: ulist

                  -  UPx as object for single policies

                  -  UPe as object for multiple policies

            c. For a component (as service)

               .. container:: ulist

                  -  UPe as service for requests

                  -  UPec as service for requests

            d. As a service (PolaS)

               .. container:: ulist

                  -  One or more UPe with service i/f

                  -  One or more Upec/UPec with service i/f

                  -  One or more Upec/UPec with service i/f

            e. In a control loop

               .. container:: ulist

                  -  UPe as decision making part

                  -  UPec as decision making part

            f. On cloud compute nodes

               .. container:: ulist

                  -  Nodes with only UPe or Upec

                  -  Nodes with any combination of UPe, UPec

            g. A cloud example

               .. container:: ulist

                  -  Left: 2 UPec managing several UPe on different
                     cloud nodes

                  -  Right: 2 large UPec with different UPe/UPec
                     deployments

Flexible Clustering
^^^^^^^^^^^^^^^^^^^

      .. container:: sectionbody

         .. container:: paragraph

            APEX can be clustered in various ways. The following figure
            shows a few of these clustering options. Cluster, engine and
            (policy) executors are named UPec (universal policy
            cluster), UPe (universal policy engine, APEX engine) and UPx
            (universal policy executor, the APEX internal state machine
            executor).

         .. container:: imageblock

            .. container:: content

               |APEX Clustering Options|

            .. container:: title

               Figure 7. APEX Clustering Options

         .. container:: olist loweralpha

            a. Single source/target, single UPx

               .. container:: ulist

                  -  Simple forward

            b. Multiple sources/targets, single UPx

               .. container:: ulist

                  -  Simple forward

            c. Single source/target, multiple UPx

               .. container:: ulist

                  -  Multithreading (MT) in UPe

            d. Multiple sources/targets, multiple UPx instances

               .. container:: ulist

                  -  Simple forward & MT in UPe

            e. Multiple non-MT UPe in UPec

               .. container:: ulist

                  -  Simple event routing

            f. Multiple MT UPe in UPec

               .. container:: ulist

                  -  Simple event routing

            g. Mixed UPe in UPec

               .. container:: ulist

                  -  Simple event routing

            h. Multiple non-MT UPec in UPec

               .. container:: ulist

                  -  Intelligent event routing

            i. Multiple mixed UPec in UPec

               .. container:: ulist

                  -  Intelligent event routing

         .. container:: olist loweralpha

            k. Mix of UPec in multiple UPec

               .. container:: ulist

                  -  External intelligent event routing

                  -  Optimized with UPec internal routing

Resources
^^^^^^^^^

      .. container:: sectionbody

         .. container:: ulist

            -  APEX Documentation hosted on Github:
               https://docs.onap.org/projects/onap-policy-parent/en/latest/apex/apex.html

            -  APEX source code repository hosted by ONAP:
               https://github.com/onap/policy-apex-pdp

            -  Issue Management (source and documentation, ONAP JIRA,
               requires a Linux Foundation ID):
               https://jira.onap.org/projects/POLICY/issues

.. container::
   :name: footer

   .. container::
      :name: footer-text

      2.0.0-SNAPSHOT
      Last updated 2018-09-04 16:04:24 IST

.. |Simple APEX Overview| image:: images/apex-intro/ApexSimple.png
.. |APEX States and Context| image:: images/apex-intro/ApexStatesAndContext.png
.. |The APEX Eco-System| image:: images/apex-intro/ApexEcosystem.png
.. |APEX Configuration Matrix| image:: images/apex-intro/ApexEngineConfig.png
.. |APEX Policy Matrix| image:: images/apex-intro/ApexPolicyMatrix.png
.. |APEX Deployment Options| image:: images/apex-intro/UpeeDeploymentOptions.png
.. |APEX Clustering Options| image:: images/apex-intro/UpeeClusterOptions.png