docs/apex/APEX-Introduction.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4
   5 A short Introduction to APEX
   6 *****************************
   7
   8 .. contents::
   9     :depth: 3
  10
  11 Introduction to APEX
  12 ^^^^^^^^^^^^^^^^^^^^
  13
  14       .. container:: sectionbody
  15
  16          .. container:: paragraph
  17
  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!
  26
  27          .. container:: imageblock
  28
  29             .. container:: content
  30
  31                |Simple APEX Overview|
  32
  33             .. container:: title
  34
  35                Figure 1. Simple APEX Overview
  36
  37          .. container:: paragraph
  38
  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.
  51
  52          .. container:: imageblock
  53
  54             .. container:: content
  55
  56                |APEX States and Context|
  57
  58             .. container:: title
  59
  60                Figure 2. APEX States and Context
  61
  62          .. container:: paragraph
  63
  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://www.researchgate.net/publication/303564082_Apex_An_Engine_for_Dynamic_Adaptive_Policy_Execution>`__
  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.
  74
  75          .. container:: paragraph
  76
  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.
  92
  93          .. container:: imageblock
  94
  95             .. container:: content
  96
  97                |The APEX Eco-System|
  98
  99             .. container:: title
 100
 101                Figure 3. The APEX Eco-System
 102
 103          .. container:: paragraph
 104
 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/>`__.
 117
 118 APEX Configuration
 119 ^^^^^^^^^^^^^^^^^^
 120
 121       .. container:: sectionbody
 122
 123          .. container:: paragraph
 124
 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.
 133
 134          .. container:: imageblock
 135
 136             .. container:: content
 137
 138                |APEX Configuration Matrix|
 139
 140             .. container:: title
 141
 142                Figure 4. APEX Configuration Matrix
 143
 144          .. container:: paragraph
 145
 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.
 150
 151 APEX Policy Matrix
 152 ^^^^^^^^^^^^^^^^^^
 153
 154       .. container:: sectionbody
 155
 156          .. container:: paragraph
 157
 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.
 169
 170          .. container:: paragraph
 171
 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
 175             cell in each column.
 176
 177          .. container:: imageblock
 178
 179             .. container:: content
 180
 181                |APEX Policy Matrix|
 182
 183             .. container:: title
 184
 185                Figure 5. APEX Policy Matrix
 186
 187          .. container:: paragraph
 188
 189             The policy can support one of a number of stimuli with an
 190             associated purpose/model of the policy, for instance:
 191
 192          .. container:: ulist
 193
 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.
 199
 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.
 204
 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.
 210
 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
 215                delegation policy.
 216
 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
 221                a goal.
 222
 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.
 229
 230          .. container:: paragraph
 231
 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:
 236
 237          .. container:: ulist
 238
 239             -  No context, nothing but a trigger event, e.g. a string or
 240                a number, is required
 241
 242             -  Event context, the incoming event provides all
 243                information (more than a string or number) for the policy
 244
 245             -  Policy context (read only), the policy has access to
 246                additional information related to its class but cannot
 247                change/alter them
 248
 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
 252                information)
 253
 254             -  Global context (read only), the policy has access to
 255                additional information of any kind but cannot
 256                change/alter them
 257
 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
 261                information)
 262
 263          .. container:: paragraph
 264
 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
 268             instance:
 269
 270          .. container:: ulist
 271
 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.
 276
 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
 282                state.
 283
 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.
 291
 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.
 296
 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.
 303
 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.
 310
 311          .. container:: paragraph
 312
 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:
 316
 317          .. container:: ulist
 318
 319             -  Obligation (deontic for what should happen)
 320
 321             -  Authorization (e.g. for rule-based or other access
 322                control or security systems)
 323
 324             -  Intent (instead of providing detailed actions the
 325                response is an intent statement and a further system
 326                processes that)
 327
 328             -  Delegation (hand the problem over to someone else,
 329                possibly with some information or instructions)
 330
 331             -  Fail / Error (the policy has encountered a problem, and
 332                reports it)
 333
 334             -  Feedback (why did the policy make a certain decision)
 335
 336 Flexible Deployment
 337 ^^^^^^^^^^^^^^^^^^^
 338
 339       .. container:: sectionbody
 340
 341          .. container:: paragraph
 342
 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).
 348
 349          .. container:: imageblock
 350
 351             .. container:: content
 352
 353                |APEX Deployment Options|
 354
 355             .. container:: title
 356
 357                Figure 6. APEX Deployment Options
 358
 359          .. container:: olist loweralpha
 360
 361             a. For an interface or class
 362
 363                .. container:: ulist
 364
 365                   -  Either UPx or UPe as association
 366
 367             b. For an application
 368
 369                .. container:: ulist
 370
 371                   -  UPx as object for single policies
 372
 373                   -  UPe as object for multiple policies
 374
 375             c. For a component (as service)
 376
 377                .. container:: ulist
 378
 379                   -  UPe as service for requests
 380
 381                   -  UPec as service for requests
 382
 383             d. As a service (PolaS)
 384
 385                .. container:: ulist
 386
 387                   -  One or more UPe with service i/f
 388
 389                   -  One or more Upec/UPec with service i/f
 390
 391                   -  One or more Upec/UPec with service i/f
 392
 393             e. In a control loop
 394
 395                .. container:: ulist
 396
 397                   -  UPe as decision making part
 398
 399                   -  UPec as decision making part
 400
 401             f. On cloud compute nodes
 402
 403                .. container:: ulist
 404
 405                   -  Nodes with only UPe or Upec
 406
 407                   -  Nodes with any combination of UPe, UPec
 408
 409             g. A cloud example
 410
 411                .. container:: ulist
 412
 413                   -  Left: 2 UPec managing several UPe on different
 414                      cloud nodes
 415
 416                   -  Right: 2 large UPec with different UPe/UPec
 417                      deployments
 418
 419 Flexible Clustering
 420 ^^^^^^^^^^^^^^^^^^^
 421
 422       .. container:: sectionbody
 423
 424          .. container:: paragraph
 425
 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
 431             executor).
 432
 433          .. container:: imageblock
 434
 435             .. container:: content
 436
 437                |APEX Clustering Options|
 438
 439             .. container:: title
 440
 441                Figure 7. APEX Clustering Options
 442
 443          .. container:: olist loweralpha
 444
 445             a. Single source/target, single UPx
 446
 447                .. container:: ulist
 448
 449                   -  Simple forward
 450
 451             b. Multiple sources/targets, single UPx
 452
 453                .. container:: ulist
 454
 455                   -  Simple forward
 456
 457             c. Single source/target, multiple UPx
 458
 459                .. container:: ulist
 460
 461                   -  Multithreading (MT) in UPe
 462
 463             d. Multiple sources/targets, multiple UPx instances
 464
 465                .. container:: ulist
 466
 467                   -  Simple forward & MT in UPe
 468
 469             e. Multiple non-MT UPe in UPec
 470
 471                .. container:: ulist
 472
 473                   -  Simple event routing
 474
 475             f. Multiple MT UPe in UPec
 476
 477                .. container:: ulist
 478
 479                   -  Simple event routing
 480
 481             g. Mixed UPe in UPec
 482
 483                .. container:: ulist
 484
 485                   -  Simple event routing
 486
 487             h. Multiple non-MT UPec in UPec
 488
 489                .. container:: ulist
 490
 491                   -  Intelligent event routing
 492
 493             i. Multiple mixed UPec in UPec
 494
 495                .. container:: ulist
 496
 497                   -  Intelligent event routing
 498
 499          .. container:: olist loweralpha
 500
 501             k. Mix of UPec in multiple UPec
 502
 503                .. container:: ulist
 504
 505                   -  External intelligent event routing
 506
 507                   -  Optimized with UPec internal routing
 508
 509 Resources
 510 ^^^^^^^^^
 511
 512       .. container:: sectionbody
 513
 514          .. container:: ulist
 515
 516             -  APEX Documentation hosted on Github:
 517                https://ericsson.github.io/apex-docs
 518
 519             -  APEX source code repository hosted by ONAP:
 520                https://gerrit.onap.org/r/#/admin/projects/policy/apex-pdp
 521
 522             -  Issue Management (source and documentation, ONAP JIRA,
 523                requires a Linux Foundation ID):
 524                https://jira.onap.org/projects/POLICY/issues
 525
 526             -  List of APEX publications:
 527                https://ericsson.github.io/apex-docs/apex-publications.html
 528
 529 .. container::
 530    :name: footer
 531
 532    .. container::
 533       :name: footer-text
 534
 535       2.0.0-SNAPSHOT
 536       Last updated 2018-09-04 16:04:24 IST
 537
 538 .. |Simple APEX Overview| image:: images/apex-intro/ApexSimple.png
 539 .. |APEX States and Context| image:: images/apex-intro/ApexStatesAndContext.png
 540 .. |The APEX Eco-System| image:: images/apex-intro/ApexEcosystem.png
 541 .. |APEX Configuration Matrix| image:: images/apex-intro/ApexEngineConfig.png
 542 .. |APEX Policy Matrix| image:: images/apex-intro/ApexPolicyMatrix.png
 543 .. |APEX Deployment Options| image:: images/apex-intro/UpeeDeploymentOptions.png
 544 .. |APEX Clustering Options| image:: images/apex-intro/UpeeClusterOptions.png
 545