| .. 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://www.researchgate.net/publication/303564082_Apex_An_Engine_for_Dynamic_Adaptive_Policy_Execution>`__ |
| 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://ericsson.github.io/apex-docs |
| |
| - APEX source code repository hosted by ONAP: |
| https://gerrit.onap.org/r/#/admin/projects/policy/apex-pdp |
| |
| - Issue Management (source and documentation, ONAP JIRA, |
| requires a Linux Foundation ID): |
| https://jira.onap.org/projects/POLICY/issues |
| |
| - List of APEX publications: |
| https://ericsson.github.io/apex-docs/apex-publications.html |
| |
| .. 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 |
| |