X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fplatform%2Farchitecture.rst;h=19f774c655b43db6024537cb5fb8658cd10f4f83;hb=1bf4549aff20757f3daf8678958f0d56107cd9e6;hp=fd46637fd1a3312402045a576ede8ba05a6e8106;hpb=5ed4e8533a28ae96755a091ae16aa5fd4bea5150;p=policy%2Fengine.git

diff --git a/docs/platform/architecture.rst b/docs/platform/architecture.rst
index fd46637fd..19f774c65 100644
--- a/docs/platform/architecture.rst
+++ b/docs/platform/architecture.rst
@@ -1,7 +1,231 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. This work is licensed under a
+.. Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 
 
 Architecture
 ------------
-Describe the architecture and design of the platform component.
+
+.. contents::
+    :depth: 3
+
+POLICY is a subsystem of ONAP that maintains, distributes, and operates on the
+set of rules that underlie ONAP’s control, orchestration, and management
+functions.
+
+POLICY provides a logically centralized environment for the creation and
+management of policies, including conditional rules.  This provides the
+capability to **create** and **validate** policies/rules, **identify
+overlaps**, **resolve conflicts**, and **derive** additional policies as
+needed.  Policies are used to **control**, **influence**, and help **ensure
+compliance** with goals.  Policies can support infrastructure, products and
+services, operation automation, and security.  Users, including network and
+service designers, operations engineers, and security experts, can easily
+**create**, **change**, and **manage** policy rules from the POLICY Manager
+in the ONAP Portal.
+
+The figure below represents the target POLICY Architecture.
+
+.. image:: PolicyTargetArchitecture.png
+
+
+The figure below represents the current POLICY Architecture.
+
+.. image:: PolicyR1Architecture.png
+
+
+A policy is defined to create a condition, requirement, constraint, decision,
+or a need that must be provided, evaluated, maintained, and/or enforced.  The
+policy is validated and corrected for any conflicts, and then placed in the
+appropriate repository, and made available for use by other subsystems and
+components.  Alternately, some policies are directly distributed to policy
+decision engines such as Drools or XACML.   In this manner, the constraints,
+decisions and actions to be taken are distributed.
+
+
+System Architecture
+^^^^^^^^^^^^^^^^^^^
+
+ONAP POLICY is composed of several subcomponents: the **Policy Administration
+Point (PAP)**, which offers interfaces for policy creation, and two types of
+**Policy Decision Point (PDP)**, each based on a specific rules technology.
+PDP-X is based on XACML technology and PDP-D is based on Drools technology.
+PDP-X is **stateless** and can be deployed as a resource pool of PDP-X servers.
+The number of servers can be grown to increase both capacity (horizontal
+scalability) and to increase availability. The PDP-D is **stateful**, as it
+utilizes Drools in its native, stateful way and transactions persist so long as
+the PDP-D is active. Persistent Drools sessions, state management, local and
+geo-redundancy have been deactivated for the initial release of ONAP POLICY
+and can be turned on in a future release. Additional instances of XACML/Drools
+engines and assigned roles/purposes may also be added in the future to
+provide a flexible, expandable policy capability.
+
+As illustrated in the Figure below, the POLICY components are supported by a
+number of interfaces and subsystems. The ONAP Portal provides a human
+interface for the creation, management and deployment of policies.  It is a
+web-based system that utilizes internal APIs in the PAP.
+
+.. image:: PolicyArchitectureDetails.png
+
+
+.. image:: PolicyArchitectureDetailsKey.png
+
+
+The PAP provides interfaces for the management of policies.  It utilizes the
+XACML database to store policies, which are then distributed to the PDPs.
+
+The XACML and Drools databases are hosted in a MariaDB cluster. The XACML
+database is used to persist policies and policy dictionaries and provide a
+point for PDPs to retrieve policies.  The XACML database also has tables used
+for node state management, detection of node failure and failover. As indicated
+above, the state management tables will only include entries for the PAP and
+PDP-X as the testing is not yet complete for the PDP-D.
+
+The PDP-X receives deployed policies and has interfaces to handle XACML policy
+transactions. These transactions are stateless and once complete, they are
+removed from memory.  If a policy that is deployed to the PDP-X is of an
+operational nature it will contain Drools rules and Java executables. These
+artifacts are processed into Maven artifacts and pushed to the Maven
+repository. The PDP-D is then notified a new policy has been deployed.
+
+When the PDP-D is notified a new policy has been deployed, it downloads it from
+the Maven repository and assigns it to an internal controller.  This controller
+provides the external Closed Loop interfaces to the DMaaP message bus over
+which events and messages are exchanged with external systems.  As events or
+messages arrive at the PDP-D, they are assigned to the appropriate controller
+and a Drools session is either created or retrieved from memory.  The events,
+messages or facts are passed to the Drools session and the corresponding rule
+is fired, resulting in a change of internal session state and possibly actions
+taken in response to the rule processing. Response messages and requests are
+passed by the controller back over the DMaaP message bus to the appropriate
+system. The Drools session can also have timers and autonomous events. In a
+future release the PDP-D can enable the node state management and session
+persistence in the Drools DB.
+
+Casablanca Additions to Architecture
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The Casablanca Release introduced two new applications into the Architecture:
+The Policy SDC Distribution Application and the Apex PDP Engine. These are not
+depicted in the picture above.
+
+The Policy SDC Service Distribution application connects to SDC Service
+Distribution notification flow to automatically create policies. It is
+integrated with the current API. For more details on this applications
+documentation, please see :ref:`apex-doc` for more information.
+
+The Apex PDP Engine was ingested into the platform. This integration was as is
+and did not formalize the Apex engine into the current policy API creation and
+distribution flows. For more details on the Apex PDP Engine, please see
+:ref:`policy-ssd-doc` for more information.
+
+Further integration of these components is planned for Dublin release.
+
+Policy Creation
+^^^^^^^^^^^^^^^
+The Policy Creation component of the Policy subsystem enables creation of new
+policies and modification of existing polices, both during the design phase
+and during runtime.  Policy Creation is targeted to be integrated to a unified
+Service Design and Creation (SDC) environment.
+
+A policy can be defined at a high level to create a condition, requirement,
+constraint, decision or a need that must be provided, evaluated, maintained,
+and/or enforced. A policy can also be defined at a lower or functional level,
+such as a machine-readable rule or software condition/assertion which enables
+actions to be taken based on a trigger or request, specific to particular
+selected conditions in effect at that time.
+
+Some examples of types of policies are:
+
+* VNF placement — rules governing where VNFs should be placed, including
+  affinity rules
+* Data and feed management — what data to collect and when, retention periods,
+  and when to send alarms about issues
+* Access control — who (or what) can have access to which data
+* Trigger conditions and actions — what conditions are actionable, and what to
+  do under those conditions
+* Interactions — how interactions between change management and
+  fault/performance management are handled (for example, should closed loops be
+  disabled during maintenance?)
+
+
+Policy Distribution To PDPs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After a policy has been initially created or an existing policy has been
+modified, the Policy Distribution Framework sends the policy from the
+repository to its points of use, which include Policy Decision Points (PDPs)
+and Policy enforcement points (DCAE, Controllers, etc), before the policy is
+actually needed.
+
+The decisions and actions taken by the policy are distributed.  Policies are
+distributed either in conjunction with installation packages (for example,
+related to service instantiation) or independently, if unrelated to a
+particular service.  Some policies can be configured (e.g., configuring policy
+parameters within microservices), while other polices are delivered to policy
+engines such as XAMCL and Drools.  With this methodology, policies will already
+be available when needed by a component, minimizing real-time requests to a
+central policy engine or PDP (Policy Decision Point). This improves scalability
+and reduces latency.
+
+Separate notifications or events communicate the link or URL for a policy to
+the components that need it.  Then, when a component needs the policy, it uses
+the link to fetch it. Components in some cases might also publish events
+indicating that they need new policies, eliciting a response with updated links
+or URLs. Also, in some cases, policies can indicate to components that they
+should subscribe to one or more policies, so that they receive automatic
+updates to those policies as they become available.
+
+
+Policy Decision and Enforcement
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Run-time policy enforcement is performed by ONAP subsystems that are
+policy-enabled or can respond to commands from a policy-enabled element such as
+a PDP. For example, policy rules for data collection are enforced by the data
+collection functionality of DCAE. Analytic policy rules, identification of
+anomalous or abnormal conditions, and publication of events signaling detection
+of such conditions are enforced by DCAE analytic applications. Policy rules for
+associated remedial actions, or for further diagnostics, are enforced by the
+correct component in a control loop such as the MSO, a Controller, or DCAE.
+Policy engines such as XACML and Drools also enforce policies and can trigger
+other components as a result (for example, causing a controller to take
+specific actions specified by the policy).  Additionally, some policies
+(“Guard Policies”) may enforce checks against decided actions.
+
+
+Policy Unification and Organization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Because the POLICY framework is expandable and multipurpose, it is likely to
+contain many types of policies which require organization according to some
+useful dimensions.  Users can define attributes that specify the scope of
+policies, and these attributes can be extended to the policy-enabled functions
+and components. Useful policy organizing dimensions might include:
+
+* Policy type or category (taxonomical)
+* Policy life cycle
+* Policy ownership or administrative domain
+* Geographic area or location,
+* Technology type
+* Policy language and version
+* Security level or other security-related values, specifiers, or limiters
+
+Attributes can be specified for each dimension. In addition to being defined
+for individual policies themselves, these attributes can be used to define the
+scope of these additional additional policy-related functions:
+
+* Policy events or requests/triggers
+* Policy decision, enforcement, or other functions
+* Virtual functions of any type
+
+Policy writers can define attributes so that policy events or requests
+self-indicate their scope. The scope is then examined by a suitable function
+and subsequently acted upon accordingly. Policy decisions and enforcement
+functions can self-indicate their scope of decision-making, enforcement, or
+other capabilities. Virtual functions can be automatically attached to the
+appropriate POLICY Framework and distribution mechanisms.
+
+
+.. image:: PolicySummary.png
+
+End of Document
+