Fix doc config files and dead links
[policy/parent.git] / docs / architecture / architecture.rst
index 5bd061e..69484ac 100644 (file)
@@ -1,8 +1,11 @@
 .. This work is licensed under a
 .. Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
-.. _architecture:
 
+.. DO NOT REMOVE THIS LABEL - EVEN IF IT GENERATES A WARNING
+.. _pf_architecture:
+
+.. THIS IS USED INTERNALLY IN POLICY ONLY
 .. _architecture-label:
 
 Policy Framework Architecture
@@ -17,6 +20,13 @@ mapping out the components, software structure, and execution ecosystem of the f
 .. contents::
     :depth: 6
 
+.. toctree::
+   :caption: References
+   :maxdepth: 1
+
+   tosca-policy-primer
+
+
 1. Overview
 ===========
 
@@ -144,7 +154,7 @@ The diagram below shows the architecture of the ONAP Policy Framework at its hig
 
 .. image:: images/PFHighestLevel.svg
 
-The *PolicyDevelopment* component implements the functionality for development of policy types and policies.
+The *PolicyAPI* component implements the functionality for CRUD of policy types and policies.
 *PolicyAdministration* is responsible for the deployment life cycle of policies as well as interworking with the
 mechanisms required to orchestrate the nodes and containers on which policies run. *PolicyAdministration* is also
 responsible for the administration of policies at run time; ensuring that policies are available to users, that policies
@@ -152,10 +162,10 @@ are executing correctly, and that the state and status of policies is monitored.
 running in the ONAP system and is responsible for making policy decisions and for managing the administrative state of
 the PDPs as directed by \ *PolicyAdministration.*
 
-*PolicyDevelopment* provides APIs that allow creation of policy artifacts and supporting information in the policy
+*PolicyAPI* provides APIs that allow creation of policy artifacts and supporting information in the policy
 database. *PolicyAdministration* reads those artifacts and the supporting information from the policy database whilst
 deploying policy artifacts. Once the policy artifacts are deployed, *PolicyAdministration* handles the run-time
-management of the PDPs on which the policies are running. *PolicyDevelopment* interacts with the database, and has
+management of the PDPs on which the policies are running. *PolicyAPI* interacts with the database, and has
 no programmatic interface with *PolicyAdministration*, *PolicyExecution* or any other run-time ONAP components.
 
 The diagram below shows a more detailed view of the architecture, as inspired by
@@ -163,10 +173,10 @@ The diagram below shows a more detailed view of the architecture, as inspired by
 
 .. image:: images/PFDesignAndAdmin.svg
 
-*PolicyDevelopment* provides a `CRUD <https://en.wikipedia.org/wiki/Create,_read,_update_and_delete>`__ API for policy
+*PolicyAPI* provides a `CRUD <https://en.wikipedia.org/wiki/Create,_read,_update_and_delete>`__ API for policy
 types and policies. The policy types and policy artifacts and their metadata (information about policies, policy types,
 and their interrelations) are stored in the *PolicyDB*. The *PolicyDevGUI*, PolicyDistribution, and other applications
-such as *CLAMP* can use the *PolicyDevelopment* API to create, update, delete, and read policy types and policies.
+such as *CLAMP* can use the *PolicyAPI* API to create, update, delete, and read policy types and policies.
 
 *PolicyAdministration* has two important functions:
 
@@ -225,7 +235,7 @@ for :ref:`Policy Administration Point (PAP) Architecture <pap-label>`.
 ---------------------------------
 
 This section describes the structure of and relations between the main concepts in the Policy Framework. This model is
-implemented as a common model and is used by *PolicyDevelopment*, *PolicyDeployment,* and *PolicyExecution.*
+implemented as a common model and is used by *PolicyAPI*, *PolicyAdministration,* and *PolicyExecution.*
 
 .. image:: images/ClassStructure.svg
 
@@ -250,7 +260,7 @@ Policy Type Design is the task of creating policy types that capture the generic
 policy for a particular domain use case.
 
 All policy types are specified in TOSCA service templates. Once policy types are defined and created in the system,
-*PolicyDevelopment* manages them and uses them to allow policies to be created from these policy types in a uniform
+*PolicyAPI* manages them and uses them to allow policies to be created from these policy types in a uniform
 way regardless of the domain that the policy type is addressing or the PDP technology that will execute the policy.
 
 A *PolicyTypeImpl* is developed for a policy type for a certain type of PDP (for example XACML oriented for decision
@@ -263,7 +273,15 @@ or it can be more general, providing the implementation of a class of policy typ
 and tool chain for implementing implementations of policy types is specific to the technology of the PDP on which
 the implementation will run.
 
-*PolicyDevelopment* provides the RESTful :ref:`Policy Design API <design-label>`, which allows other components to query
+In the *xacml-pdp* and *drools-pdp*, an *application* is written for a given category of policy types. Such an
+application may have logic written in Java or another programming language, and may have additional artifacts such
+as scripts and SQL queries. The *application* unmarshals and marshals events going into and out of policies as well
+as handling the sequencing of events for interactions of the policies with other components in ONAP. For example,
+*drools-applications* handles the interactions for operational policies running in the drools PDP. In the
+*apex-pdp*, all unmarshaling, marshaling, and component interactions are captured in the state machine, logic, and
+configuraiton of the policy, a Java application is not used.
+
+*PolicyAPI* provides the RESTful :ref:`Policy Design API <design-label>`, which allows other components to query
 policy types, Those components can then create policies that specify values for the properties, triggers, and targets
 specified in a policy type. This API is used by components such as *CLAMP* and *PolicyDistribution* to create policies
 from policy types.
@@ -304,15 +322,15 @@ programmers in their work
 2.2.2 Policy Design
 ^^^^^^^^^^^^^^^^^^^
 
-The *PolicyCreation* function of *PolicyDevelopment* creates policies from a policy type.  The information expressed
+The *PolicyCreation* function of *PolicyAPI* creates policies from a policy type.  The information expressed
 during policy type design is used to parameterize a policy type to create an executable policy. A service designer
 and/or operations team can use tooling that reads the TOSCA Policy Type specifications to express and capture a policy
 at its highest abstraction level. Alternatively, the parameter for the policy can be expressed in a raw JSON or YAML
 file and posted over the policy design API described on the :ref:`Policy Design and Development <design-label>` page.
 
-A number of mechanisms for policy creation are supported in ONAP. The process in *PolicyDevelopment* for creating a
+A number of mechanisms for policy creation are supported in ONAP. The process in *PolicyAPI* for creating a
 policy is the same for all mechanisms. The most general mechanism for creating a policy is using the RESTful
-*Policy Design API*, which provides a full interface to the policy creation support of *PolicyDevelopment*. This API may
+*Policy Design API*, which provides a full interface to the policy creation support of *PolicyAPI*. This API may
 be exercised directly using utilities such as *curl*.
 
 In future releases, the Policy Framework may provide a command line tool that will be a loose wrapper around the API. It
@@ -335,22 +353,22 @@ Framework.
 2.2.2.1 Policy Design in the ONAP Policy Framework
 """"""""""""""""""""""""""""""""""""""""""""""""""
 
-Policy creation in *PolicyDevelopment* follows the general sequence shown in the sequence diagram below. An *API_USER*
-is any component that wants to create a policy from a policy type. *PolicyDevelopment* supplies a REST interface that
+Policy creation in *PolicyAPI* follows the general sequence shown in the sequence diagram below. An *API_USER*
+is any component that wants to create a policy from a policy type. *PolicyAPI* supplies a REST interface that
 exposes the API and also provides a command line tool and general purpose client that wraps the API.
 
 .. image:: images/PolicyDesign.svg
 
 An *API_User* first gets a reference to and the metadata for the Policy type for the policy they want to work on from
-*PolicyDevelopment*. *PolicyDevelopment* reads the metadata and artifact for the policy type from the database. The
-*API_User* then asks for a reference and the metadata for the policy. *PolicyDevelopment* looks up the policy in the
-database. If the policy already exists, *PolicyDevelopment* reads the artifact and returns the reference of the existing
-policy to the *API_User* with the metadata for the existing policy. If the policy does not exist, *PolicyDevelopment*
+*PolicyAPI*. *PolicyAPI* reads the metadata and artifact for the policy type from the database. The
+*API_User* then asks for a reference and the metadata for the policy. *PolicyAPI* looks up the policy in the
+database. If the policy already exists, *PolicyAPI* reads the artifact and returns the reference of the existing
+policy to the *API_User* with the metadata for the existing policy. If the policy does not exist, *PolicyAPI*
 informs the *API_User*.
 
 The *API_User* may now proceed with a policy specification session, where the parameters are set for the policy using
 the policy type specification. Once the *API_User* is happy that the policy is completely and correctly specified, it
-requests *PolicyDevelopment* to create the policy. *PolicyDevelopment* creates the policy, stores the created policy
+requests *PolicyAPI* to create the policy. *PolicyAPI* creates the policy, stores the created policy
 artifact and its metadata in the database.
 
 2.2.2.2 Model Driven VF (Virtual Function) Policy Design via VNF SDK Packaging
@@ -375,7 +393,7 @@ this information to automatically generate a policy.
 
 Note that SDC provides a wrapper for the SDC API as a Java Client and also provides a TOSCA parser. See the
 documentation for the `Policy Distribution Component
-<https://docs.onap.org/en/latest/submodules/policy/distribution.git/docs/index.html>`__.
+<https://docs.onap.org/projects/onap-policy-parent/en/latest/distribution/distribution.html>`__.
 
 In Step 4 above, the \ *PolicyDesign* must download the CSAR file. If the policy is to be composed from the TOSCA
 definition, it must also parse the TOSCA definition.
@@ -417,7 +435,7 @@ underlying ONAP management infrastructure and are designed to comply with the ON
 The PAPs keep track of PDPs, support the deployment of PDP groups and the deployment of a *policy set* across those PDP
 groups. A PAP is stateless in a RESTful sense. Therefore, if there is more than one PAP deployed, it does not matter
 which PAP a user contacts to handle a request. The PAP uses the database (persistent storage) to keep track of ongoing
-sessions with clients. Policy management on PDPs is the responsibility of PAPs; management of policy sets or policies by
+sessions with PDPs. Policy management on PDPs is the responsibility of PAPs; management of policy sets or policies by
 any other manner is not permitted.
 
 In the ONAP Policy Framework, the interfaces to the PDP are designed to be as streamlined as possible. Because the PDP
@@ -437,7 +455,7 @@ Deployment and Registration with PAP are explained.
 The ONAP Policy Framework follows the architectural approach for microservices recommended by the `ONAP Architecture
 Subcommittee <https://wiki.onap.org/display/DW/Architecture+Subcommittee>`__.
 
-The ONAP Policy Framework defines `Kubernetes Services
+The ONAP Policy Framework uses an infrastructure such as Kubernetes `Services
 <https://kubernetes.io/docs/concepts/services-networking/service/>`__ to manage the life cycle of Policy Framework
 executable components at runtime. A Kubernetes service allows, among other parameters,  the number of instances (*pods*
 in Kubernetes terminology) that should be deployed for a particular service to be specified and a common endpoint for
@@ -458,20 +476,20 @@ The following services will be required for the ONAP Policy Framework:
 ================ ============================== =======================================================================
 **Service**      **Endpoint**                   **Description**
 ================ ============================== =======================================================================
-PAP              https://policy-pap             The PAP service, used for policy administration and deployment. See
+PAP              policy-pap                     The PAP service, used for policy administration and deployment. See
                                                 :ref:`Policy Design and Development <design-label>` for details of the
                                                 API for this service
-PDP-X-\ *domain* https://policy-pdpx-\ *domain* A PDP service is defined for each PDP group. A PDP group is identified
+PDP-X-\ *domain* policy-pdpx-\ *domain*         A PDP service is defined for each PDP group. A PDP group is identified
                                                 by the domain on which it operates.
 
                                                 For example, there could be two PDP-X domains, one for admission
                                                 policies for ONAP proper and another for admission policies for VNFs of
                                                 operator *Supacom*. Two PDP-X services are defined:
 
-                                                | https://policy-pdpx-onap
-                                                | https://policy-pdpx-\ *supacom*
-PDP-D-\ *domain* https://policy-pdpd-\ *domain*
-PDP-A-\ *domain* https://policy-pdpa-\ *domain*
+                                                | policy-pdpx-onap
+                                                | policy-pdpx-\ *supacom*
+PDP-D-\ *domain* policy-pdpd-\ *domain*
+PDP-A-\ *domain* policy-pdpa-\ *domain*
 ================ ============================== =======================================================================
 
 There is one and only one PAP service, which handles policy deployment, administration, and monitoring for all policies
@@ -555,16 +573,18 @@ PDP types:
 ================== =====================================================================================================
 PASSIVE MODE       Policy execution is always rejected irrespective of PDP type.
 ACTIVE MODE        Policy execution is executed in the live environment by the PDP.
-SAFE MODE          Policy execution proceeds, but changes to domain state or context are not carried out. The PDP
+SAFE MODE*         Policy execution proceeds, but changes to domain state or context are not carried out. The PDP
                    returns an indication that it is running in SAFE mode together with the action it would have
                    performed if it was operating in ACTIVE mode. The PDP type and the policy types it is running must
                    support SAFE mode operation.
-TEST MODE          Policy execution proceeds and changes to domain and state are carried out in a test or sandbox
+TEST MODE*         Policy execution proceeds and changes to domain and state are carried out in a test or sandbox
                    environment. The PDP returns an indication it is running in TEST mode together with the action it has
                    performed on the test environment. The PDP type and the policy types it is running must support TEST
                    mode operation.
 ================== =====================================================================================================
 
+\* SAFE Mode and TEST Mode will be implemented in future versions of the Policy Framework.
+
 2.3.5 Policy Lifecycle Management
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -592,7 +612,9 @@ mode of the PDP to PASSIVE. The Policy Set is transparently passed to the PDP by
 in the policy set including any models, rules, tasks, or flows in the policy set in the policy implementations.
 
 Once the Policy Set is loaded, the PAP orders the PDP to enter the life cycle mode that has been specified for it
-(ACTIVE/SAFE/TEST). The PDP begins to execute policies in the specified mode (see section 2.3.4).
+(ACTIVE/SAFE*/TEST*). The PDP begins to execute policies in the specified mode (see section 2.3.4).
+
+\* SAFE Mode and TEST Mode will be implemented in future versions of the Policy Framework.
 
 .. _policy-rollout:
 
@@ -617,10 +639,14 @@ Finally, when the user is satisfied with policy set execution and when quality c
 is set into ACTIVE state and the policy set executes on the target environment. The results of target operation are
 reported. The PDP group can be reverted to SAFE, TEST, or even PASSIVE mode at any time if problems arise.
 
+\* SAFE Mode and TEST Mode will be implemented in future versions of the Policy Framework. In current versions, policies
+transition directly from PASSIVE mode to ACTIVE mode.
+
 2.3.5.3 Policy Upgrade and Rollback
 """""""""""""""""""""""""""""""""""
 
-There are a number of approaches for managing policy upgrade and rollback.
+There are a number of approaches for managing policy upgrade and rollback. Upgrade and rollback will be implemented in
+future versions of the Policy Framework.
 
 The most straightforward approach is to use the approach described in section :ref:`policy-rollout` for upgrading and
 rolling back policy sets. In order to upgrade a policy set, one follows the process in :ref:`policy-rollout` with the
@@ -649,7 +675,7 @@ extended to provide information for specific PDP types. PDPs provide at least th
 ===================== ===============================================================================
 **Field**             **Description**
 ===================== ===============================================================================
-State                 Lifecycle State (PASSIVE/TEST/SAFE/ACTIVE)
+State                 Lifecycle State (PASSIVE/TEST*/SAFE*/ACTIVE)
 Timestamp             Time the report record was generated
 InvocationCount       The number of execution invocations the PDP has processed since the last report
 LastInvocationTime    The time taken to process the last execution invocation
@@ -659,6 +685,11 @@ UpTime                The length of time the PDP has been executing
 RealTimeInfo          Real time information on running policies.
 ===================== ===============================================================================
 
+\* SAFE Mode and TEST Mode will be implemented in future versions of the Policy Framework.
+
+Currently, policy monitoring is supported by PAP and by pdp-apex. Policy monitoring for all PDPs will be supported in
+future versions of the Policy Framework.
+
 2.3.7 PEP Registration and Enforcement Guidelines
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -670,6 +701,79 @@ APIs. Some example PEPs are: DCAE, OOF, and SDNC.
 See Section 3.4 of the :ref:`Policy Design and Development <design-label>`
 for more information on the Decision APIs.
 
+2.3.8 Multi-Cluster Support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Multi-cluster support was added to the Policy Framework during the Istanbul release,
+enabling redundancy, load-sharing, and inter-site failover.
+
+**Note:** *multi-cluster support has only been minimally tested, and is thus still
+experimental.*
+
+2.3.8.1 Shared DB
+"""""""""""""""""
+
+Multi-cluster support requires a shared DB.  Rather than spinning up a
+separate DB for each cluster, all of the clusters are pointed to a common DB.
+Policy-API adds policy types and policies, while Policy-PAP manages PDP Groups and
+Subgroups, as well as policy deployments.  The information in these tables is not
+segregated, but is, instead, shared across the API and PAP components across all of
+the clusters.
+
+.. image:: images/MCSharedDB.svg
+
+2.3.8.2 DMaaP Arrangement
+"""""""""""""""""""""""""
+
+As in prior releases, communication between the PAPs and PDPs still takes place via
+DMaaP.  Two arrangements, described below, are supported.
+
+2.3.8.2.1 Local DMaaP
+~~~~~~~~~~~~~~~~~~~~~
+
+In this arrangement, each cluster is associated with its own, local
+DMaaP, and communication only happens between PAPs and PDPs within the same cluster.
+
+.. image:: images/MCLocalDmaap.svg
+
+The one
+limitation with this approach is that, when a PAP in cluster A deploys a policy, PAP
+is only able to inform the PDPs in the local cluster; the PDPs in the other clusters
+are not made aware of the new deployment until they generate a heartbeat, at which
+point, their local PAP will inform them of the new deployment.  The same is true of
+changes made to the state of a PDP Group; changes only propagate to PDPs in other
+clusters in response to heartbeats generated by the PDPs.
+
+.. image:: images/MCLocalHB.svg
+
+2.3.8.2.2 Shared DMaaP
+~~~~~~~~~~~~~~~~~~~~~~
+
+In this arrangement, the PAPs and PDPs in all of the clusters are
+pointed to a common DMaaP.  Because the PAP and PDPs all communicate via the same
+DMaaP, when a PAP deploys a policy, all PDPs are made aware, rather than having to
+wait for a heartbeat.
+
+.. image:: images/MCSharedDmaap.svg
+
+2.3.8.3 Missed Heartbeat
+""""""""""""""""""""""""
+
+To manage the removal of terminated PDPs from the DB, a record, containing a
+"last-updated" timestamp, is maintained within the DB for each PDP.  Whether using a
+local or shared DMaaP, any PAP receiving a message from a PDP will update the timestamp
+in the associated record, thus keeping the records “current”.
+
+.. image:: images/MCSharedHB.svg
+
+Periodically, each PAP will sweep the DB of PDP records whose timestamp has not been
+updated recently.  The frequency with which it is checked is based on the value of
+the "heartbeatMs" configuration parameter, with a record considered expired if no
+heartbeat has been received for three cycles.
+
+.. image:: images/MCMissedHB.svg
+
+
 3. APIs Provided by the Policy Framework
 ========================================