1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
5 A short Introduction to APEX
6 ****************************
14 .. container:: sectionbody
16 .. container:: paragraph
18 APEX stand for Adaptive Policy EXecution. It is a
19 lightweight engine for execution of policies. APEX allows
20 you to specify logic as a policy, logic that you can adapt
21 on the fly as your system executes. The APEX policies you
22 design can be really simple, with a single snippet of logic,
23 or can be very complex, with many states and tasks. APEX
24 policies can even be designed to self-adapt at execution
25 time, the choice is yours!
27 .. container:: imageblock
29 .. container:: content
31 |Simple APEX Overview|
35 Figure 1. Simple APEX Overview
37 .. container:: paragraph
39 The Adaptive Policy Engine in APEX runs your policies. These
40 policies are triggered by incoming events. The logic of the
41 policies executes and produces a response event. The
42 *Incoming Context* on the incoming event and the *Outgoing
43 Context* on the outgoing event are simply the fields and
44 attributes of the event. You design the policies that APEX
45 executes and the trigger and action events that your
46 policies accept and produce. Events are fed in and sent out
47 as JSON or XML events over Kafka, a Websocket, a file or
48 named pipe, or even standard input. If you run APEX as a
49 library in your application, you can even feed and receive
50 events over a Java API.
52 .. container:: imageblock
54 .. container:: content
56 |APEX States and Context|
60 Figure 2. APEX States and Context
62 .. container:: paragraph
64 You design your policy as a chain of states, with each state
65 being fed by the state before. The simplest policy can have
66 just one state. We provide specific support for the
67 four-state `MEDA (Match Establish Decide
68 Act) https://ieeexplore.ieee.org/document/7502880`
69 policy state model and the three-state `ECA (Event Condition
70 Action) <https://en.wikipedia.org/wiki/Event_condition_action>`__
71 policy state model. APEX is fully distributed. You can
72 decide how many APEX engine instances to run for your
73 application and on which real or virtual hosts to run them.
75 .. container:: paragraph
77 In APEX, you also have control of the *Context* used by your
78 policies. Context is simply the state information and data
79 used by your policies. You define what context your policies
80 use and what the scope of that context is. *Policy Context*
81 is private to a particular policy and is accessible only to
82 whatever APEX engines are running that particular policy.
83 *Global Context* is available to all policies. *External
84 Context* is read-only context such as weather or topology
85 information that is provided by other systems. APEX keeps
86 context coordinated across all the the instances running a
87 particular policy. If a policy running in an APEX engine
88 changes the value of a piece of context, that value is
89 available to all other APEX engines that use that piece of
90 context. APEX takes care of distribution, locking, writing
91 of context to persistent storage, and monitoring of context.
93 .. container:: imageblock
95 .. container:: content
101 Figure 3. The APEX Eco-System
103 .. container:: paragraph
105 The APEX engine (AP-EN) is available as a Java library for
106 inclusion in your application, as a microservice running in
107 a Docker container, or as a stand-alone service available
108 for integration into your system. APEX also includes a
109 policy editor (AP-AUTH) that allows you to design your
110 policies and a web-based policy management console you use
111 to deploy policies and to keep track of the state of
112 policies and context in policies. Context handling (AP-CTX)
113 is integrated into the APEX engine and policy deployment
114 (AP-DEP) is provided as a servlet running under a web
115 framework such as `Apache
116 Tomcat <http://tomcat.apache.org/>`__.
121 .. container:: sectionbody
123 .. container:: paragraph
125 An APEX engine can be configured to use various combinations
126 of event input handlers, event output handlers, event
127 protocols, context handlers, and logic executors. The system
128 is built using a plugin architecture. Each configuration
129 option is realized by a plugin, which can be loaded and
130 configured when the engine is started. New plugins can be
131 added to the system at any time, though to benefit from a
132 new plugin, an engine will need to be restarted.
134 .. container:: imageblock
136 .. container:: content
138 |APEX Configuration Matrix|
142 Figure 4. APEX Configuration Matrix
144 .. container:: paragraph
146 The APEX distribution already comes with a number of
147 plugins. The figure above shows the provided plugins. Any
148 combination of input, output, event protocol, context
149 handlers, and executors is possible.
154 .. container:: sectionbody
156 .. container:: paragraph
158 APEX offers a lot of flexibility for defining, deploying,
159 and executing policies. Based on a theoretic model, it
160 supports virtually any policy model and supports translation of
161 legacy policies into the APEX execution format. However, the
162 most important aspect for using APEX is to decide what
163 policy is needed, what underlying policy concepts should be
164 used, and how the decision logic should be realized. Once
165 these aspects are decided, APEX can be used to execute the
166 policies. If the policy evolves, say from a simple decision
167 table to a fully adaptable policy, only the policy
168 definition requires change. APEX supports all of that.
170 .. container:: paragraph
172 The figure below shows a (non-exhaustive) matrix, which will
173 help to decide what policy is required to solve your
174 problem. Read the matrix from left to right choosing one
177 .. container:: imageblock
179 .. container:: content
185 Figure 5. APEX Policy Matrix
187 .. container:: paragraph
189 The policy can support one of a number of stimuli with an
190 associated purpose/model of the policy, for instance:
194 - Configuration, i.e. what should happen. An example is an
195 event that states an intended network configuration and
196 the policy should provide the detailed actions for it.
197 The policy can be realized for instance as an obligation
198 policy, a promise or an intent.
200 - Report, i.e. something did happen. An example is an event
201 about an error or fault and the policy needs to repair
202 that problem. The policy would usually be an obligation,
203 utility function, or goal policy.
205 - Monitoring, i.e. something does happen. An example is a
206 notification about certain network conditions, to which
207 the policy might (or might not) react. The policy will
208 mitigate the monitored events or permit (deny) related
209 actions as an obligation or authorization.
211 - Analysis, i.e. why did something happen. An example is an
212 analytic component sends insights of a situation
213 requiring a policy to act on it. The policy can solve the
214 problem, escalate it, or delegate it as a refrain or
217 - Prediction, i.e. what will happen next. An example are
218 events that a policy uses to predict a future network
219 condition. The policy can prevent or enforce the
220 prediction as an adaptive policy, a utility function, or
223 - Feedback, i.e. why did something happen or not happen.
224 Similar to analysis, but here the feedback will be in the
225 input event and the policy needs to do something with that
226 information. Feedback can be related to history or
227 experience, for instance a previous policy execution. The
228 policy needs to be context-aware or be a meta-policy.
230 .. container:: paragraph
232 Once the purpose of the policy is decided, the next step is
233 to look into what context information the policy will
234 require to do its job. This can range from very simple to a
235 lot of different information, for instance:
239 - No context, nothing but a trigger event, e.g. a string or
240 a number, is required
242 - Event context, the incoming event provides all
243 information (more than a string or number) for the policy
245 - Policy context (read only), the policy has access to
246 additional information related to its class but cannot
249 - Policy context (read and write), the policy has access to
250 additional information related to its class and can alter
251 this information (for instance to record historic
254 - Global context (read only), the policy has access to
255 additional information of any kind but cannot
258 - Global context (read and write), the policy
259 has access to additional information of any kind and can
260 alter this information (for instance to record historic
263 .. container:: paragraph
265 The next step is to decide how the policy should do its job,
266 i.e. what flavor it has, how many states are needed, and how
267 many tasks. There are many possible combinations, for
272 - Simple / God: a simple policy with 1 state and 1 task,
273 which is doing everything for the decision-making. This
274 is the ideal policy for simple situation, e.g. deciding
275 on configuration parameters or simple access control.
277 - Simple sequence: a simple policy with a number of states
278 each having a single task. This is a very good policy for
279 simple decision-making with different steps. For
280 instance, a classic action policy (ECA) would have 3
281 states (E, C, and A) with some logic (1 task) in each
284 - Simple selective: a policy with 1 state but more than one
285 task. Here, the appropriate task (and it’s logic) will be
286 selected at execution time. This policy is very good for
287 dealing with similar (or the same) situation in different
288 contexts. For instance, the tasks can be related to
289 available external software, or to current work load on
290 the compute node, or to time of day.
292 - Selective: any number of states having any number of
293 tasks (usually more than 1 task). This is a combination
294 of the two policies above, for instance an ECA policy
295 with more than one task in E, C, and A.
297 - Classic directed: a policy with more than one state, each
298 having one task, but a non-sequential execution. This
299 means that the sequence of the states is not pre-defined
300 in the policy (as would be for all cases above) but
301 calculated at runtime. This can be good to realize
302 decision trees based on contextual information.
304 - Super Adaptive: using the full potential of the APEX
305 policy model, states and tasks and state execution are
306 fully flexible and calculated at runtime (per policy
307 execution). This policy is very close to a general
308 programming system (with only a few limitations), but can
309 solve very hard problems.
311 .. container:: paragraph
313 The final step is to select a response that the policy
314 creates. Possible responses have been discussed in the
315 literature for a very long time. A few examples are:
319 - Obligation (deontic for what should happen)
321 - Authorization (e.g. for rule-based or other access
322 control or security systems)
324 - Intent (instead of providing detailed actions the
325 response is an intent statement and a further system
328 - Delegation (hand the problem over to someone else,
329 possibly with some information or instructions)
331 - Fail / Error (the policy has encountered a problem, and
334 - Feedback (why did the policy make a certain decision)
339 .. container:: sectionbody
341 .. container:: paragraph
343 APEX can be deployed in various ways. The following figure
344 shows a few of these deployment options. Engine and (policy)
345 executors are named UPe (universal policy engine, APEX
346 engine) and UPx (universal policy executor, the APEX
347 internal state machine executor).
349 .. container:: imageblock
351 .. container:: content
353 |APEX Deployment Options|
357 Figure 6. APEX Deployment Options
359 .. container:: olist loweralpha
361 a. For an interface or class
365 - Either UPx or UPe as association
367 b. For an application
371 - UPx as object for single policies
373 - UPe as object for multiple policies
375 c. For a component (as service)
379 - UPe as service for requests
381 - UPec as service for requests
383 d. As a service (PolaS)
387 - One or more UPe with service i/f
389 - One or more Upec/UPec with service i/f
391 - One or more Upec/UPec with service i/f
397 - UPe as decision making part
399 - UPec as decision making part
401 f. On cloud compute nodes
405 - Nodes with only UPe or Upec
407 - Nodes with any combination of UPe, UPec
413 - Left: 2 UPec managing several UPe on different
416 - Right: 2 large UPec with different UPe/UPec
422 .. container:: sectionbody
424 .. container:: paragraph
426 APEX can be clustered in various ways. The following figure
427 shows a few of these clustering options. Cluster, engine and
428 (policy) executors are named UPec (universal policy
429 cluster), UPe (universal policy engine, APEX engine) and UPx
430 (universal policy executor, the APEX internal state machine
433 .. container:: imageblock
435 .. container:: content
437 |APEX Clustering Options|
441 Figure 7. APEX Clustering Options
443 .. container:: olist loweralpha
445 a. Single source/target, single UPx
451 b. Multiple sources/targets, single UPx
457 c. Single source/target, multiple UPx
461 - Multithreading (MT) in UPe
463 d. Multiple sources/targets, multiple UPx instances
467 - Simple forward & MT in UPe
469 e. Multiple non-MT UPe in UPec
473 - Simple event routing
475 f. Multiple MT UPe in UPec
479 - Simple event routing
485 - Simple event routing
487 h. Multiple non-MT UPec in UPec
491 - Intelligent event routing
493 i. Multiple mixed UPec in UPec
497 - Intelligent event routing
499 .. container:: olist loweralpha
501 k. Mix of UPec in multiple UPec
505 - External intelligent event routing
507 - Optimized with UPec internal routing
512 .. container:: sectionbody
516 - APEX Documentation hosted on Github:
517 https://docs.onap.org/projects/onap-policy-parent/en/latest/apex/apex.html
519 - APEX source code repository hosted by ONAP:
520 https://github.com/onap/policy-apex-pdp
522 - Issue Management (source and documentation, ONAP JIRA,
523 requires a Linux Foundation ID):
524 https://jira.onap.org/projects/POLICY/issues
533 Last updated 2018-09-04 16:04:24 IST
535 .. |Simple APEX Overview| image:: images/apex-intro/ApexSimple.png
536 .. |APEX States and Context| image:: images/apex-intro/ApexStatesAndContext.png
537 .. |The APEX Eco-System| image:: images/apex-intro/ApexEcosystem.png
538 .. |APEX Configuration Matrix| image:: images/apex-intro/ApexEngineConfig.png
539 .. |APEX Policy Matrix| image:: images/apex-intro/ApexPolicyMatrix.png
540 .. |APEX Deployment Options| image:: images/apex-intro/UpeeDeploymentOptions.png
541 .. |APEX Clustering Options| image:: images/apex-intro/UpeeClusterOptions.png