docs/platform/architecture.rst

   1 .. This work is licensed under a
   2 .. Creative Commons Attribution 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4 .. _architecture:
   5
   6
   7 Architecture
   8 ------------
   9
  10 .. contents::
  11     :depth: 3
  12
  13 POLICY is a subsystem of ONAP that maintains, distributes, and operates on the
  14 set of rules that underlie ONAP's control, orchestration, and management
  15 functions.
  16
  17 POLICY provides a logically centralized environment for the creation and
  18 management of policies, including conditional rules.  This provides the
  19 capability to **create** and **validate** policies/rules, **identify
  20 overlaps**, **resolve conflicts**, and **derive** additional policies as
  21 needed.  Policies are used to **control**, **influence**, and help **ensure
  22 compliance** with goals.  Policies can support infrastructure, products and
  23 services, operation automation, and security.  Users, including network and
  24 service designers, operations engineers, and security experts, can easily
  25 **create**, **change**, and **manage** policy rules from the POLICY Manager
  26 in the ONAP Portal.
  27
  28 The figure below represents the target POLICY Architecture.
  29
  30 .. image:: PolicyTargetArchitecture.png
  31
  32
  33 The figure below represents the current POLICY Architecture.
  34
  35 .. image:: PolicyR1Architecture.png
  36
  37
  38 A policy is defined to create a condition, requirement, constraint, decision,
  39 or a need that must be provided, evaluated, maintained, and/or enforced.  The
  40 policy is validated and corrected for any conflicts, and then placed in the
  41 appropriate repository, and made available for use by other subsystems and
  42 components.  Alternately, some policies are directly distributed to policy
  43 decision engines such as Drools or XACML.   In this manner, the constraints,
  44 decisions and actions to be taken are distributed.
  45
  46
  47 System Architecture
  48 ^^^^^^^^^^^^^^^^^^^
  49
  50 ONAP POLICY is composed of several subcomponents: the **Policy Administration
  51 Point (PAP)**, which offers interfaces for policy creation, and two types of
  52 **Policy Decision Point (PDP)**, each based on a specific rules technology.
  53 PDP-X is based on XACML technology and PDP-D is based on Drools technology.
  54 PDP-X is **stateless** and can be deployed as a resource pool of PDP-X servers.
  55 The number of servers can be grown to increase both capacity (horizontal
  56 scalability) and to increase availability. The PDP-D is **stateful**, as it
  57 utilizes Drools in its native, stateful way and transactions persist so long as
  58 the PDP-D is active. Persistent Drools sessions, state management, local and
  59 geo-redundancy have been deactivated for the initial release of ONAP POLICY
  60 and can be turned on in a future release. Additional instances of XACML/Drools
  61 engines and assigned roles/purposes may also be added in the future to
  62 provide a flexible, expandable policy capability.
  63
  64 As illustrated in the Figure below, the POLICY components are supported by a
  65 number of interfaces and subsystems. The ONAP Portal provides a human
  66 interface for the creation, management and deployment of policies.  It is a
  67 web-based system that utilizes internal APIs in the PAP.
  68
  69 .. image:: PolicyArchitectureDetails.png
  70
  71
  72 .. image:: PolicyArchitectureDetailsKey.png
  73
  74
  75 The PAP provides interfaces for the management of policies.  It utilizes the
  76 XACML database to store policies, which are then distributed to the PDPs.
  77
  78 The XACML and Drools databases are hosted in a MariaDB cluster. The XACML
  79 database is used to persist policies and policy dictionaries and provide a
  80 point for PDPs to retrieve policies.  The XACML database also has tables used
  81 for node state management, detection of node failure and failover. As indicated
  82 above, the state management tables will only include entries for the PAP and
  83 PDP-X as the testing is not yet complete for the PDP-D.
  84
  85 The PDP-X receives deployed policies and has interfaces to handle XACML policy
  86 transactions. These transactions are stateless and once complete, they are
  87 removed from memory.  If a policy that is deployed to the PDP-X is of an
  88 operational nature it will contain Drools rules and Java executables. These
  89 artifacts are processed into Maven artifacts and pushed to the Maven
  90 repository. The PDP-D is then notified a new policy has been deployed.
  91
  92 When the PDP-D is notified a new policy has been deployed, it downloads it from
  93 the Maven repository and assigns it to an internal controller.  This controller
  94 provides the external Closed Loop interfaces to the DMaaP message bus over
  95 which events and messages are exchanged with external systems.  As events or
  96 messages arrive at the PDP-D, they are assigned to the appropriate controller
  97 and a Drools session is either created or retrieved from memory.  The events,
  98 messages or facts are passed to the Drools session and the corresponding rule
  99 is fired, resulting in a change of internal session state and possibly actions
 100 taken in response to the rule processing. Response messages and requests are
 101 passed by the controller back over the DMaaP message bus to the appropriate
 102 system. The Drools session can also have timers and autonomous events. In a
 103 future release the PDP-D can enable the node state management and session
 104 persistence in the Drools DB.
 105
 106 Casablanca Additions to Architecture
 107 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 108 The Casablanca Release introduced two new applications into the Architecture:
 109 The Policy SDC Distribution Application and the Apex PDP Engine. These are not
 110 depicted in the picture above.
 111
 112 The Policy SDC Service Distribution application connects to SDC Service
 113 Distribution notification flow to automatically create policies. It is
 114 integrated with the current API. For more details on this applications
 115 documentation, please see :ref:`apex-doc` for more information.
 116
 117 The Apex PDP Engine was ingested into the platform. This integration was as is
 118 and did not formalize the Apex engine into the current policy API creation and
 119 distribution flows. For more details on the Apex PDP Engine, please see
 120 :ref:`policy-ssd-doc` for more information.
 121
 122 Further integration of these components is planned for Dublin release.
 123
 124 Policy Creation
 125 ^^^^^^^^^^^^^^^
 126 The Policy Creation component of the Policy subsystem enables creation of new
 127 policies and modification of existing polices, both during the design phase
 128 and during runtime.  Policy Creation is targeted to be integrated to a unified
 129 Service Design and Creation (SDC) environment.
 130
 131 A policy can be defined at a high level to create a condition, requirement,
 132 constraint, decision or a need that must be provided, evaluated, maintained,
 133 and/or enforced. A policy can also be defined at a lower or functional level,
 134 such as a machine-readable rule or software condition/assertion which enables
 135 actions to be taken based on a trigger or request, specific to particular
 136 selected conditions in effect at that time.
 137
 138 Some examples of types of policies are:
 139
 140 * VNF placement - rules governing where VNFs should be placed, including
 141   affinity rules
 142 * Data and feed management - what data to collect and when, retention periods,
 143   and when to send alarms about issues
 144 * Access control - who (or what) can have access to which data
 145 * Trigger conditions and actions - what conditions are actionable, and what to
 146   do under those conditions
 147 * Interactions - how interactions between change management and
 148   fault/performance management are handled (for example, should closed loops be
 149   disabled during maintenance?)
 150
 151
 152 Policy Distribution To PDPs
 153 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 154
 155 After a policy has been initially created or an existing policy has been
 156 modified, the Policy Distribution Framework sends the policy from the
 157 repository to its points of use, which include Policy Decision Points (PDPs)
 158 and Policy enforcement points (DCAE, Controllers, etc), before the policy is
 159 actually needed.
 160
 161 The decisions and actions taken by the policy are distributed.  Policies are
 162 distributed either in conjunction with installation packages (for example,
 163 related to service instantiation) or independently, if unrelated to a
 164 particular service.  Some policies can be configured (e.g., configuring policy
 165 parameters within microservices), while other polices are delivered to policy
 166 engines such as XAMCL and Drools.  With this methodology, policies will already
 167 be available when needed by a component, minimizing real-time requests to a
 168 central policy engine or PDP (Policy Decision Point). This improves scalability
 169 and reduces latency.
 170
 171 Separate notifications or events communicate the link or URL for a policy to
 172 the components that need it.  Then, when a component needs the policy, it uses
 173 the link to fetch it. Components in some cases might also publish events
 174 indicating that they need new policies, eliciting a response with updated links
 175 or URLs. Also, in some cases, policies can indicate to components that they
 176 should subscribe to one or more policies, so that they receive automatic
 177 updates to those policies as they become available.
 178
 179
 180 Policy Decision and Enforcement
 181 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 182
 183 Run-time policy enforcement is performed by ONAP subsystems that are
 184 policy-enabled or can respond to commands from a policy-enabled element such as
 185 a PDP. For example, policy rules for data collection are enforced by the data
 186 collection functionality of DCAE. Analytic policy rules, identification of
 187 anomalous or abnormal conditions, and publication of events signaling detection
 188 of such conditions are enforced by DCAE analytic applications. Policy rules for
 189 associated remedial actions, or for further diagnostics, are enforced by the
 190 correct component in a control loop such as the MSO, a Controller, or DCAE.
 191 Policy engines such as XACML and Drools also enforce policies and can trigger
 192 other components as a result (for example, causing a controller to take
 193 specific actions specified by the policy).  Additionally, some policies
 194 ("Guard Policies") may enforce checks against decided actions.
 195
 196
 197 Policy Unification and Organization
 198 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 199 Because the POLICY framework is expandable and multipurpose, it is likely to
 200 contain many types of policies which require organization according to some
 201 useful dimensions.  Users can define attributes that specify the scope of
 202 policies, and these attributes can be extended to the policy-enabled functions
 203 and components. Useful policy organizing dimensions might include:
 204
 205 * Policy type or category (taxonomical)
 206 * Policy life cycle
 207 * Policy ownership or administrative domain
 208 * Geographic area or location,
 209 * Technology type
 210 * Policy language and version
 211 * Security level or other security-related values, specifiers, or limiters
 212
 213 Attributes can be specified for each dimension. In addition to being defined
 214 for individual policies themselves, these attributes can be used to define the
 215 scope of these additional additional policy-related functions:
 216
 217 * Policy events or requests/triggers
 218 * Policy decision, enforcement, or other functions
 219 * Virtual functions of any type
 220
 221 Policy writers can define attributes so that policy events or requests
 222 self-indicate their scope. The scope is then examined by a suitable function
 223 and subsequently acted upon accordingly. Policy decisions and enforcement
 224 functions can self-indicate their scope of decision-making, enforcement, or
 225 other capabilities. Virtual functions can be automatically attached to the
 226 appropriate POLICY Framework and distribution mechanisms.
 227
 228
 229 .. image:: PolicySummary.png
 230
 231 End of Document
 232