.. _pap-label:
-Policy Administration Point (PAP) Architecture
-##############################################
+Policy Administration Point API
+###############################
.. contents::
:depth: 3
+.. toctree::
+ InternalPapPdp.rst
+
+Policy Administration Point (PAP) Architecture
+==============================================
+
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.
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
======
"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
-------------
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
+It is worth noting that we use basic authorization for access with user name and password set to *policyadmin* 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
"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"
-
-.. swaggerv2doc:: swagger/health-check-pap.json
+.. csv-table::
+ :header: "/healthcheck"
+ :widths: 10
+
+ `Health Check PAP Swagger <./local-swagger.html#tag/HealthCheckRestControllerV1>`_
This operation performs a health check on the PAP.
.. literalinclude:: response/health-check-pap-resp.json
:language: json
-.. swaggerv2doc:: swagger/consolidated-healthcheck-pap.json
+.. csv-table::
+ :header: "/pdps/healthcheck"
+ :widths: 10
+
+ `Consolidated Health Check PAP Swagger <./local-swagger.html#tag/PolicyComponentsHealthCheckControllerV1>`_
This operation performs a health check of all policy components. The response
contains the health check result of each component. The consolidated health check
.. literalinclude:: response/consolidated-healthcheck-pap-resp.json
:language: json
-.. swaggerv2doc:: swagger/statistics-pap.json
+.. csv-table::
+ :header: "/statistics"
+ :widths: 10
+
+ `Statistics PAP Swagger <./local-swagger.html#tag/StatisticsRestControllerV1>`_
This operation allows statistics for PDP groups, PDP subgroups, and individual PDPs to be retrieved.
.. literalinclude:: response/statistics-pap-resp.json
:language: json
-.. swaggerv2doc:: swagger/state-change-pap.json
+.. csv-table::
+ :header: "/pdps/groups/{name}"
+ :widths: 10
+
+ `PDP State Change PAP Swagger <./local-swagger.html#tag/PdpGroupStateChangeControllerV1>`_
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.
-.. swaggerv2doc:: swagger/groups-batch-pap.json
+.. csv-table::
+ :header: "/pdps/groups/batch"
+ :widths: 10
+
+ `Group Batch PAP Swagger <./local-swagger.html#tag/PdpGroupCreateOrUpdateControllerV1>`_
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 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.
.. literalinclude:: request/groups-batch-pap-req.json
:language: json
-.. swaggerv2doc:: swagger/group-delete-pap.json
+.. csv-table::
+ :header: "/pdps/groups/{name}"
+ :widths: 10
+
+ `PdpGroup Delete PAP Swagger <./local-swagger.html#tag/PdpGroupDeleteControllerV1>`_
The API also allows PDP groups to be deleted. DELETE operations are only permitted on PDP groups in PASSIVE state.
-.. swaggerv2doc:: swagger/group-query-pap.json
+.. csv-table::
+ :header: "/pdps"
+ :widths: 10
+
+ `PdpGroup Query PAP Swagger <./local-swagger.html#tag/PdpGroupQueryControllerV1>`_
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.
.. literalinclude:: response/group-query-pap-resp.json
:language: json
-.. swaggerv2doc:: swagger/deployments-batch-pap.json
+.. csv-table::
+ :header: "/pdps/deployments/batch"
+ :widths: 10
+
+ `Deployments Update PAP Swagger <./local-swagger.html#tag/PdpGroupDeployControllerV1>`_
This operation allows policies to be deployed on specific PDP groups.
Each subgroup includes an "action" property, which is used to indicate
.. literalinclude:: request/deployment-batch-pap-req.json
:language: json
-.. swaggerv2doc:: swagger/policy-deploy-pap.json
+Here is a sample response:
+
+.. literalinclude:: response/deployment-pap-resp.json
+ :language: json
+
+.. csv-table::
+ :header: "/pdps/policies"
+ :widths: 10
+
+ `Deploy PAP Swagger <./local-swagger.html#operation/deployPolicies>`_
This operation allows policies to be deployed across all relevant PDP groups.
PAP will deploy the specified policies to all relevant subgroups. Only the
.. literalinclude:: request/policy-deploy-pap-req.json
:language: json
-.. swaggerv2doc:: swagger/policy-undeploy-pap.json
+Here is a sample response:
+
+.. literalinclude:: response/deployment-pap-resp.json
+ :language: json
+
+.. csv-table::
+ :header: "/pdps/policies/{name}"
+ :widths: 10
+
+ `Undeploy PAP Swagger <./local-swagger.html#operation/deletePolicy>`_
This operation allows policies to be undeployed from PDP groups.
.. note::
Due to current limitations, a fully qualified policy version must always be specified.
-.. swaggerv2doc:: swagger/deployed-policy-pap.json
+Here is a sample response:
+
+.. literalinclude:: response/deployment-pap-resp.json
+ :language: json
+
+.. csv-table::
+ :header: "/policies/status"
+ :widths: 10
+
+ `All Policy Status PAP Swagger <./local-swagger.html#operation/getStatusOfAllPolicies>`_
+
+
+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
+
+.. csv-table::
+ :header: "/policies/deployed"
+ :widths: 10
+
+ `Deployed Policy Status PAP Swagger <./local-swagger.html#operation/queryAllDeployedPolicies>`_
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.
.. literalinclude:: response/deployed-policy-pap-resp.json
:language: json
-.. swaggerv2doc:: swagger/pdp-statistics-pap.json
+.. csv-table::
+ :header: "/pdps/statistics"
+ :widths: 10
+
+ `Policy Statistics PAP Swagger <./local-swagger.html#tag/StatisticsRestControllerV1>`_
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
+.. csv-table::
+ :header: "/policies/audit"
+ :widths: 10
+
+ `Policy Status PAP Swagger <./local-swagger.html#tag/PolicyAuditControllerV1>`_
+
+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 Future Features
+3 Configuration
=================
-3.1 Disable policies in PDP
-===========================
+The *PolicyAdministration* component (PAP) is initialized using a configuration file: `papParameters.yaml
+<https://github.com/onap/policy-pap/blob/master/packages/policy-pap-tarball/src/main/resources/etc/papParameters.yaml>`_
+
+The configuration file is a YAML file containing the relevant fields for configuring the REST server, Database and DMaaP connectivity and so on.
-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.
+3.1 Disable collection of PDP Statistics
+========================================
+
+This configuration is to inform PAP to not save the PDP statistics in the database.
+
+In *papParameters.yaml*, 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.
End of Document
Code Review / policy / parent.git / blobdiff