Update docs for audit & statistics api's

[policy/parent.git] / docs / pap / pap.rst

.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0

.. _pap-label:

Policy Administration Point (PAP) Architecture
##############################################

.. contents::
    :depth: 3

.. toctree::
   InternalPapPdp.rst

The Policy Administration Point (PAP) keeps track of PDPs, supporting the deployment of PDP groups and the deployment
of policies across those PDP groups. Policies are created using the Policy API, but are deployed via the PAP.

The PAP is stateless in a RESTful sense, using the database (persistent storage) to track PDPs and the deployment of
policies to those PDPs. In short, policy management on PDPs is the responsibility of PAP; management of policies by
any other manner is not permitted.

Because the PDP is the main unit of scalability in the Policy Framework, the framework is designed to allow PDPs in a
PDP group to arbitrarily appear and disappear and for policy consistency across all PDPs in a PDP group to be easily
maintained. The PAP is responsible for controlling the state across the PDPs in a PDP group. The PAP interacts with the
policy database and transfers policies to PDPs.

The unit of execution and scaling in the Policy Framework is a *PolicyImpl* entity. A *PolicyImpl* entity runs on a PDP.
As is explained above, a *PolicyImpl* entity is a *PolicyTypeImpl* implementation parameterized with a TOSCA *Policy*.

.. image:: images/PolicyImplPDPSubGroup.svg

In order to achieve horizontal scalability, we group the PDPs running instances of a given *PolicyImpl* entity logically
together into a *PDPSubGroup*. The number of PDPs in a *PDPSubGroup* can then be scaled up and down using Kubernetes. In
other words, all PDPs in a subgroup run the same *PolicyImpl*, that is the same policy template implementation (in
XACML, Drools, or APEX) with the same parameters.

The figure above shows the layout of *PDPGroup* and *PDPSubGroup* entities. The figure shows examples of PDP groups for
Control Loop and Monitoring policies on the right.

The health of PDPs is monitored by the PAP in order to alert operations teams managing policies. The PAP manages the life
cycle of policies running on PDPs.

The table below shows the deployment methods in which *PolicyImpl* entities can be deployed to PDP Subgroups.

========== =========================================== ============================== ==================================
**Method** **Description**                             **Advantages**                 **Disadvantages**
========== =========================================== ============================== ==================================
Cold       The *PolicyImpl* (*PolicyTypeImpl* and      No run time configuration      Very restrictive, no run time
           TOSCA *Policy*) are predeployed on the PDP. required and run time          configuration of PDPs is possible.
           PDP is fully configured and ready to        administration is simple.
           execute when started.

           PDPs register with the PAP when they
           start, providing the *pdpGroup* they
           have been preconfigured with.

Warm       The *PolicyTypeImpl* entity is predeployed  The configuration, parameters, Administration and management is
           on the PDP. A TOSCA *Policy* may be loaded  and PDP group of PDPs may be   required. The configuration and
           at startup. The PDP may be configured or    changed at run time by loading life cycle of the TOSCA policies
           reconfigured with a new or updated TOSCA    or updating a TOSCA *Policy*   can change at run time and must be
           *Policy* at run time.                       into the PDP.                  administered and managed.

           PDPs register with the PAP when they start, Support TOSCA *Policy* entity
           providing the *pdpGroup* they have been     life cycle managgement is
           predeployed with if any. The PAP may update supported, allowing features
           the TOSCA *Policy* on a PDP at any time     such as *PolicyImpl* Safe Mode
           after registration.                         and *PolicyImpl* retirement.

Hot        The *PolicyImpl* (*PolicyTypeImpl* and      The policy logic, rules,       Administration and management is
           TOSCA *Policy*) are deployed at run time.   configuration, parameters, and more complex. The *PolicyImpl*
           The *PolicyImpl* (*PolicyTypeImpl* and      PDP group of PDPs may be       itself and its configuration and
           TOSCA *Policy*) may be loaded at startup.   changed at run time by loading life cycle as well as the life
           The PDP may be configured or reconfigured   or updating a TOSCA *Policy*   cycle of the TOSCA policies can
           with a new or updated *PolicyTypeImpl*      and *PolicyTypeImpl* into the  change at run time and must be
           and/or TOSCA *Policy* at run time.          PDP.                           administered and managed.

           PDPs register with the PAP when they        Lifecycle management of TOSCA
           start, providing the *pdpGroup* they have   *Policy* entities and
           been preconfigured with if any. The PAP may *PolicyTypeImpl* entites is
           update the TOSCA *Policy* and               supported, allowing features
           *PolicyTypeImpl* on a PDP at any time after such as *PolicyImpl* Safe Mode
           registration                                and *PolicyImpl* retirement.
========== =========================================== ============================== ==================================


1 APIs
======
The APIs in the subchapters below are supported by the PAP.

1.1 REST API
------------

The purpose of this API is to support CRUD of PDP groups and subgroups and to support the deployment and life cycles of
policies on PDP sub groups and PDPs. This API is provided by the *PolicyAdministration* component (PAP) of the Policy
Framework, see the :ref:`ONAP Policy Framework Architecture <architecture-label>` page.

PDP groups and subgroups may be prefedined in the system. Predefined groups and subgroups may be modified or deleted
over this API. The policies running on predefined groups or subgroups as well as the instance counts and properties may
also be modified.

A PDP may be preconfigured with its PDP group, PDP subgroup, and policies. The PDP sends this information to the PAP
when it starts. If the PDP group, subgroup, or any policy is unknown to the PAP, the PAP locks the PDP in state PASSIVE.

PAP supports the operations listed in the following table, via its REST API:

.. csv-table::
   :header: "Operation", "Description"
   :widths: 25,70

   "Health check", "Queries the health of the PAP"
   "Consolidated healthcheck", "Queries the health of all policy components"
   "Statistics", "Queries various statistics"
   "PDP state change", "Changes the state of all PDPs in a PDP Group"
   "PDP Group create/update", "Creates/updates PDP Groups"
   "PDP Group delete", "Deletes a PDP Group"
   "PDP Group query", "Queries all PDP Groups"
   "Deployment update", "Deploy/undeploy one or more policies in specified PdpGroups"
   "Deploy policy", "Deploys one or more policies to the PDPs"
   "Undeploy policy", "Undeploys a policy from the PDPs"
   "Policy Status", "Queries the status of all policies"
   "Policy deployment status", "Queries the status of all deployed policies"
   "PDP statistics", "Queries the statistics of PDPs"
   "Policy Audit", "Queries the audit records of policies"

1.2 DMaaP API
-------------

PAP interacts with the PDPs via the DMaaP Message Router.  The messages listed
in the following table are transmitted via DMaaP:

.. csv-table::
   :header: "Message", "Direction", "Description"
   :widths: 25,10,70

   "PDP status", "Incoming", "Registers a PDP with PAP; also sent as a periodic heart beat; also sent in response to requests from the PAP"
   "PDP update", "Outgoing", "Assigns a PDP to a PDP Group and Subgroup; also deploys or undeploys policies from the PDP"
   "PDP state change", "Outgoing", "Changes the state of a PDP or all PDPs within a PDP Group or Subgroup"

In addition, PAP generates notifications via the DMaaP Message Router when policies are successfully or unsuccessfully
deployed (or undeployed) from all relevant PDPs.

Here is a sample notification:

.. literalinclude:: notification/dmaap-pap-notif.json
    :language: json


2 PAP REST API Swagger
======================

It is worth noting that we use basic authorization for access with user name and password set to *healthcheck* and
*zb!XztG34*, respectively.

For every call, the client is encouraged to insert a uuid-type *requestID* as parameter. It is helpful for tracking each
http transaction and facilitates debugging. More importantly, it complies with Logging requirements v1.2. If the client
does not provide the requestID in a call, one will be randomly generated and attached to the response header,
*x-onap-requestid*.

In accordance with `ONAP API Common Versioning Strategy Guidelines
<https://wiki.onap.org/display/DW/ONAP+API+Common+Versioning+Strategy+%28CVS%29+Guidelines>`_, several custom headers
are added in the response to each call:

.. csv-table::
   :header: "Header", "Example value", "Description"
   :widths: 25,10,70

   "x-latestversion", "1.0.0", "latest version of the API"
   "x-minorversion", "0", "MINOR version of the API"
   "x-patchversion", "0", "PATCH version of the API"
   "x-onap-requestid", "e1763e61-9eef-4911-b952-1be1edd9812b", "described above; used for logging purposes"

:download:`Download Health Check PAP API Swagger <swagger/health-check-pap.json>`

.. swaggerv2doc:: swagger/health-check-pap.json

This operation performs a health check on the PAP.

Here is a sample response:

.. literalinclude:: response/health-check-pap-resp.json
    :language: json

:download:`Download Consolidated Health Check PAP API Swagger <swagger/consolidated-healthcheck-pap.json>`

.. swaggerv2doc:: swagger/consolidated-healthcheck-pap.json

This operation performs a health check of all policy components. The response
contains the health check result of each component. The consolidated health check
is reported as healthy only if all the components are healthy, otherwise the
"healthy" flag is marked as false.

Here is a sample response:

.. literalinclude:: response/consolidated-healthcheck-pap-resp.json
    :language: json

:download:`Download Statistics PAP API Swagger <swagger/statistics-pap.json>`

.. swaggerv2doc:: swagger/statistics-pap.json

This operation allows statistics for PDP groups, PDP subgroups, and individual PDPs to be retrieved.

.. note::
  While this API is supported, most of the statistics are not currently updated; that work has been deferred to a later
  release.

Here is a sample response:

.. literalinclude:: response/statistics-pap-resp.json
    :language: json

:download:`Download State Change PAP Swagger <swagger/state-change-pap.json>`

.. swaggerv2doc:: swagger/state-change-pap.json

The state of PDP groups is managed by this operation. PDP groups can be in states PASSIVE, TEST, SAFE, or ACTIVE. For a full
description of PDP group states, see the :ref:`ONAP Policy Framework Architecture <architecture-label>` page.

:download:`Download Group Batch PAP API Swagger <swagger/groups-batch-pap.json>`

.. swaggerv2doc:: swagger/groups-batch-pap.json

This operation allows the PDP groups and subgroups to be created and updated. Many PDP groups can be created or updated
in a single POST operation by specifying more than one PDP group in the POST operation body.
This can be used to create the PDP group by providing all the details including the supported policy types for each subgroup.
However, it cannot be used to update policies; that is done using one of
the deployment requests.  Consequently, the "policies" property of this
request will be ignored.
This can also be used to update a PDP Group, but supported policy types cannot be updated during the update operation.
So, "policies" and "supportedPolicyTypes" properties in the request will be ignored if provided during the PDP Group update operation.

The "desiredInstanceCount" specifies the minimum number of PDPs of the given
type that should be registered with PAP.  Currently, this is just used for
health check purposes; if the number of PDPs registered with PAP drops below
the given value, then PAP will return an "unhealthy" indicator if a
"Consolidated Health Check" is performed.

.. note::
  If a subgroup is to be deleted from a PDP Group, then the policies must be removed from
  the subgroup first.

.. note::
  Policies cannot be added/updated during PDP Group create/update operations. So, if provided, they are ignored.
  Supported policy types are defined during PDP Group creation. They cannot be updated once they are created.
  So, supportedPolicyTypes are expected during PDP Group create, but ignored if provided during PDP Group update.

Here is a sample request:

.. literalinclude:: request/groups-batch-pap-req.json
    :language: json

:download:`Download Group Delete PAP API Swagger  <swagger/group-delete-pap.json>`

.. swaggerv2doc:: swagger/group-delete-pap.json

The API also allows PDP groups to be deleted. DELETE operations are only permitted on PDP groups in PASSIVE state.

:download:`Download Group Query PAP API Swagger  <swagger/group-query-pap.json>`

.. swaggerv2doc:: swagger/group-query-pap.json

This operation allows the PDP groups and subgroups to be listed as well as the policies that are deployed on each PDP
group and subgroup.

Here is a sample response:

.. literalinclude:: response/group-query-pap-resp.json
    :language: json

:download:`Download Deployments Batch PAP API Swagger  <swagger/deployments-batch-pap.json>`

.. swaggerv2doc:: swagger/deployments-batch-pap.json

This operation allows policies to be deployed on specific PDP groups.
Each subgroup includes an "action" property, which is used to indicate
that the policies are being added (POST) to the subgroup, deleted (DELETE)
from the subgroup, or that the subgroup's entire set of policies is being
replaced (PATCH) by a new set of policies.  As such, a subgroup may appear
more than once in a single request, one time to delete some policies and
another time to add new policies to the same subgroup.

Here is a sample request:

.. literalinclude:: request/deployment-batch-pap-req.json
    :language: json

Here is a sample response:

.. literalinclude:: response/deployment-pap-resp.json
    :language: json

:download:`Download Deploy PAP API Swagger  <swagger/policy-deploy-pap.json>`

.. swaggerv2doc:: swagger/policy-deploy-pap.json

This operation allows policies to be deployed across all relevant PDP groups.
PAP will deploy the specified policies to all relevant subgroups.  Only the
policies supported by a given subgroup will be deployed to that subgroup.

.. note::
  The policy version is optional.  If left unspecified, then the latest version of the policy is deployed. On the other
  hand, if it is specified, it may be an integer, or it may be a fully qualified version (e.g., "3.0.2").
  In addition, a subgroup to which a policy is being deployed must have at
  least one PDP instance, otherwise the request will be rejected.

Here is a sample request:

.. literalinclude:: request/policy-deploy-pap-req.json
    :language: json

Here is a sample response:

.. literalinclude:: response/deployment-pap-resp.json
    :language: json

:download:`Download Undeploy PAP API Swagger  <swagger/policy-undeploy-pap.json>`

.. swaggerv2doc:: swagger/policy-undeploy-pap.json

This operation allows policies to be undeployed from PDP groups.

.. note::
  If the policy version is specified, then it may be an integer, or it may be a fully qualified version (e.g., "3.0.2").
  On the other hand, if left unspecified, then the latest deployed version will be undeployed.

.. note::
  Due to current limitations, a fully qualified policy version must always be specified.

Here is a sample response:

.. literalinclude:: response/deployment-pap-resp.json
    :language: json

:download:`Download Policy Status PAP API Swagger  <swagger/policy-status-pap.json>`

.. swaggerv2doc:: swagger/policy-status-pap.json

This operation allows the status of all policies that are deployed or undeployed to be listed together.
The result can be filtered based on pdp group name, policy name & version.

.. note::
  When a policy is successfully undeployed, it will no longer appear in the policy status response.

Here is a sample response:

.. literalinclude:: response/policy-status-pap-resp.json
    :language: json

:download:`Download Deployed Policy PAP API Swagger  <swagger/deployed-policy-pap.json>`

.. swaggerv2doc:: swagger/deployed-policy-pap.json

This operation allows the deployed policies to be listed together with their respective deployment status.
The result can be filtered based on policy name & version.

Here is a sample response:

.. literalinclude:: response/deployed-policy-pap-resp.json
    :language: json

:download:`Download PDP Statistics PAP API Swagger  <swagger/pdp-statistics-pap.json>`

.. swaggerv2doc:: swagger/pdp-statistics-pap.json

This operation allows the PDP statistics to be retrieved for all registered PDPs.
The result can be filtered based on PDP group, PDP subgroup & PDP instance.
Along with record count, start time & end time as query parameters.

Here is a sample response:

.. literalinclude:: response/pdp-statistics-pap-resp.json
    :language: json

:download:`Download Policy Audit PAP API Swagger  <swagger/policy-audit-pap.json>`

.. swaggerv2doc:: swagger/policy-audit-pap.json

This operation allows the audit records of policies to be listed together.
The result can be filtered based on pdp group name, policy name & version.
Along with record count, start time & end time as query parameters.

Here is a sample response:

.. literalinclude:: response/policy-audit-pap-resp.json
    :language: json

3 Configuration
=================

3.1 Disable collection of PDP Statistics
========================================

This configuration is to inform PAP to not save the PDP statistics in the database.

In `config.json
<https://github.com/onap/policy-pap/blob/master/packages/policy-pap-tarball/src/main/resources/etc/defaultConfig.json>`_,
add or change the property savePdpStatisticsInDb to false.

.. note::
  By default, if the property is not present, it will be considered as false and
  PDP statistics will not be saved in the database.


4 Future Features
=================

4.1 Disable policies in PDP
===========================

This operation will allow disabling individual policies running in PDP engine. It is mainly beneficial
in scenarios where network operators/administrators want to disable a particular policy in PDP engine
for a period of time due to a failure in the system or for scheduled maintenance.

End of Document