diff options
Diffstat (limited to 'docs/APEX-Introduction.rst')
| -rw-r--r-- | docs/APEX-Introduction.rst | 545 |
1 files changed, 0 insertions, 545 deletions
diff --git a/docs/APEX-Introduction.rst b/docs/APEX-Introduction.rst deleted file mode 100644 index 90dd9e747..000000000 --- a/docs/APEX-Introduction.rst +++ /dev/null @@ -1,545 +0,0 @@ -.. 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 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 build 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 allows to translate - 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 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 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 - |