.. http://creativecommons.org/licenses/by/4.0
.. DO NOT REMOVE THIS LABEL - EVEN IF IT GENERATES A WARNING
-.. _architecture:
+.. _pf_architecture:
.. THIS IS USED INTERNALLY IN POLICY ONLY
.. _architecture-label:
.. contents::
:depth: 6
+.. toctree::
+ :caption: References
+ :maxdepth: 1
+
+ tosca-policy-primer
+
+
1. Overview
===========
.. 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
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
.. 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:
---------------------------------
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
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
*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.
-*PolicyDevelopment* provides the RESTful :ref:`Policy Design API <design-label>`, which allows other components to query
+*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.
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
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
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.
================ ============================== =======================================================================
**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
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
========================================
Code Review / policy / parent.git / blobdiff