summaryrefslogtreecommitdiffstats
path: root/docs/APEX-Introduction.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/APEX-Introduction.rst')
-rw-r--r--docs/APEX-Introduction.rst545
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
-