summaryrefslogtreecommitdiffstats
path: root/docs/development/pdp/pdp-pap-interaction.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/development/pdp/pdp-pap-interaction.rst')
-rw-r--r--docs/development/pdp/pdp-pap-interaction.rst299
1 files changed, 299 insertions, 0 deletions
diff --git a/docs/development/pdp/pdp-pap-interaction.rst b/docs/development/pdp/pdp-pap-interaction.rst
new file mode 100644
index 00000000..45988192
--- /dev/null
+++ b/docs/development/pdp/pdp-pap-interaction.rst
@@ -0,0 +1,299 @@
+.. This work is licensed under a
+.. Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+.. _pdp-pap-interaction-label:
+
+Guidelines for PDP-PAP interaction
+###################################
+
+.. contents::
+ :depth: 3
+
+A PDP (Policy Decision Point) is where the policy execution happens. The administrative actions such as
+managing the PDPs, deploying or undeploying policies to these PDPs etc. are handled by PAP
+(Policy Administration Point). Any PDP should follow certain behavior to be registered and functional in
+the Policy Framework. All the communications between PAP and PDP happen over DMaaP on topic *POLICY-PDP-PAP*.
+The below diagram shows how a PDP interacts with PAP.
+
+.. image:: images/PDP_PAP.svg
+
+**1. Start PDP**
+
+A PDP should be configured to start with the below information in its startup configuration file.
+
+- *pdpGroup* to which the PDP should belong to.
+- *DMaaP topic* 'POLICY-PDP-PAP' which should be the source and sink for communicating with PAP.
+
+**2. PDP sends PDP_STATUS (registration message)**
+
+As soon as a PDP is up, it sends a registration message to POLICY-PDP-PAP topic.
+Some of the information included in the message are:
+
+- *pdpType* the type of the PDP (apex/drools/xacml etc.).
+- *pdpGroup* to which the PDP should belong to.
+- *state* the initial state of the PDP which is PASSIVE.
+- *healthy* whether the PDP is "HEALTHY" or not.
+- *name* a name that is unique to the PDP instance.
+
+
+.. code-block:: json
+ :caption: Sample PDP_STATUS Registration message (from APEX-PDP)
+ :linenos:
+
+ {
+ "pdpType": "apex",
+ "state": "PASSIVE",
+ "healthy": "HEALTHY",
+ "description": "Pdp Heartbeat",
+ "statistics": {
+ ..... Omitted for brevity
+ },
+ "messageName": "PDP_STATUS",
+ "requestId": "54926ad0-440f-4b40-9237-40ca754ad00d",
+ "timestampMs": 1632325024286,
+ "name": "apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02",
+ "pdpGroup": "defaultGroup"
+ }
+
+**3. PAP sends PDP_UPDATE message**
+
+On receiving the registration message from a PDP, PAP checks and assigns it to a subgroup under the group.
+If there are policies that were already deployed (for e.g. previously deployed, and the PDP is restarted)
+under the subgroup, then the *policiesToBeDeployed* are also sent along with the *subgroup* it is assigned to.
+PAP also sends the *pdpHeartbeatIntervalMs* which is the time interval in which PDPs should send heartbeats to PAP.
+
+.. code-block:: json
+ :caption: Sample PDP_UPDATE message (for APEX-PDP)
+ :linenos:
+
+ {
+ "source": "pap-56c8531d-5376-4e53-a820-6973c62bfb9a",
+ "pdpHeartbeatIntervalMs": 120000,
+ "policiesToBeDeployed": [],
+ "messageName": "PDP_UPDATE",
+ "requestId": "3534e54f-4432-4c68-81c8-a6af07e59fb2",
+ "timestampMs": 1632325037040,
+ "name": "apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02",
+ "pdpGroup": "defaultGroup",
+ "pdpSubgroup": "apex"
+ }
+
+**4. PDP sends PDP_STATUS response to PDP_UPDATE**
+
+PDP on receiving the PDP_UPDATE message from the DMaaP topic, it first checks if the message is intended for the PDP.
+If so, it updates itself with the information in PDP_UPDATE message from PAP such as *pdpSubgroup*,
+*pdpHeartbeatIntervalMs* and *policiesToBeDeployed* (if any). After handling the PDP_UPDATE message, the PDP sends
+a response message back to PAP with the current status of the PDP along with the result of the PDP_UPDATE operation.
+
+.. code-block:: json
+ :caption: Sample PDP_STATUS response message (from APEX-PDP)
+ :linenos:
+
+ {
+ "pdpType": "apex",
+ "state": "PASSIVE",
+ "healthy": "HEALTHY",
+ "description": "Pdp status response message for PdpUpdate",
+ "policies": [],
+ "statistics": {
+ ..... Omitted for brevity
+ },
+ "response": {
+ "responseTo": "3534e54f-4432-4c68-81c8-a6af07e59fb2",
+ "responseStatus": "SUCCESS",
+ "responseMessage": "Pdp update successful."
+ },
+ "messageName": "PDP_STATUS",
+ "requestId": "e3c72783-4e91-4cb5-8140-e4ac0630706d",
+ "timestampMs": 1632325038075,
+ "name": "apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02",
+ "pdpGroup": "defaultGroup",
+ "pdpSubgroup": "apex"
+ }
+
+
+**5. PAP sends PDP_STATE_CHANGE message**
+
+PAP sends PDP_STATE_CHANGE message to PDPs to change the state from PASSIVE to active
+or ACTIVE to PASSIVE. When a PDP is in PASSIVE state, the policy execution will not happen.
+All PDPs start up in PASSIVE state, and they can be changed to ACTIVE/PASSIVE using PAP.
+After registration is complete, PAP makes a PDP ACTIVE by default.
+
+.. code-block:: json
+ :caption: Sample PDP_STATE_CHANGE message
+ :linenos:
+
+ {
+ "source": "pap-56c8531d-5376-4e53-a820-6973c62bfb9a",
+ "state": "ACTIVE",
+ "messageName": "PDP_STATE_CHANGE",
+ "requestId": "90eada6d-bb98-4750-a4e1-b439cb5e041d",
+ "timestampMs": 1632325037040,
+ "name": "apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02",
+ "pdpGroup": "defaultGroup",
+ "pdpSubgroup": "apex"
+ }
+
+**6. PDP sends PDP_STATUS response to PDP_STATE_CHANGE**
+
+PDP updates its state as per the PDP_STATE_CHANGE received from PAP. When a PDP is changed
+to ACTIVE, any policies that are already pushed to the PDP start execution
+and start processing events as per the policies deployed. If no policies are running in a PDP,
+then it waits in ACTIVE state, ready to execute any policies as and when they are pushed
+to them from PAP. After handling the PDP_STATE_CHANGE message, the PDP sends a response message
+back to PAP with the current status of the PDP along with the result of the PDP_STATE_CHANGE operation.
+
+.. code-block:: json
+ :caption: Sample PDP_STATUS response message (from APEX-PDP)
+ :linenos:
+
+ {
+ "pdpType": "apex",
+ "state": "ACTIVE",
+ "healthy": "HEALTHY",
+ "description": "Pdp status response message for PdpStateChange",
+ "policies": [],
+ "statistics": {
+ ..... Omitted for brevity
+ },
+ "response": {
+ "responseTo": "90eada6d-bb98-4750-a4e1-b439cb5e041d",
+ "responseStatus": "SUCCESS",
+ "responseMessage": "State changed to active. No policies are running."
+ },
+ "messageName": "PDP_STATUS",
+ "requestId": "8a88806c-4d3e-4c80-8048-dc85d4bb75dd",
+ "timestampMs": 1632325043068,
+ "name": "apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02",
+ "pdpGroup": "defaultGroup",
+ "pdpSubgroup": "apex"
+ }
+
+**7. PDP sends PDP_STATUS Heartbeat messages**
+
+A PDP has to send Heartbeat messages to PAP periodically with the current status information
+of the PDP. PAP receives this information and makes sure they are updated. In case of any mismatch
+with the data in the database, PAP sends out a PDP_UPDATE message to update the PDP.
+PAP considers a PDP as expired if three consecutive heartbeats are missing from the PDP,
+and removes the PDP instance details from the database.
+
+.. code-block:: json
+ :caption: Sample PDP_STATUS response message (from APEX-PDP)
+ :linenos:
+
+ {
+ "pdpType": "apex",
+ "state": "ACTIVE",
+ "healthy": "HEALTHY",
+ "description": "Pdp Heartbeat",
+ "policies": [],
+ "statistics": {
+ ..... Omitted for brevity
+ },
+ "messageName": "PDP_STATUS",
+ "requestId": "e3c72783-4e91-4cb5-8140-e4ac0630706d",
+ "timestampMs": 1632325038075,
+ "name": "apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02",
+ "pdpGroup": "defaultGroup",
+ "pdpSubgroup": "apex"
+ }
+
+**8. Deploy/Undeploy Policy using PAP**
+
+Policies can be deployed or undeployed using PAP APIs. PAP fetches the policies to be deployed
+from the database, and send the whole policies' list under *policiesToBeDeployed* field.
+In case of undeployment, PAP sends the list of policies with their name and version under
+*policiesToBeUndeployed* in the PDP_UPDATE message.
+
+**9. PAP sends PDP_UPDATE message with policiesToBeDeployed/Undeployed**
+
+PAP sends a PDP_UPDATE message with information about policies to be deployed and
+undeployed. If there are some policies that are already deployed, then only the new ones
+are sent under the *policiesToBeDeployed* field.
+
+.. code-block:: json
+ :caption: Sample PDP_STATUS response message (from APEX-PDP)
+ :linenos:
+
+ {
+ "source": "pap-56c8531d-5376-4e53-a820-6973c62bfb9a",
+ "pdpHeartbeatIntervalMs": 120000,
+ "policiesToBeDeployed": [
+ {
+ "type": "onap.policies.native.Apex",
+ "type_version": "1.0.0",
+ "properties": {
+ ..... Omitted for brevity
+ },
+ "name": "onap.policies.apex.Simplecontrolloop",
+ "version": "1.0.0",
+ "metadata": {
+ "policy-id": "onap.policies.apex.Simplecontrolloop",
+ "policy-version": "1.0.0"
+ }
+ }
+ ],
+ "policiesToBeUndeployed":[],
+ "messageName": "PDP_UPDATE",
+ "requestId": "3534e54f-4432-4c68-81c8-a6af07e59fb2",
+ "timestampMs": 1632325037040,
+ "name": "apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02",
+ "pdpGroup": "defaultGroup",
+ "pdpSubgroup": "apex"
+ }
+
+**10. PDP sends PDP_STATUS response to PDP_UPDATE**
+
+All policies to be deployed/undeployed are updated in the PDP engine.
+Policies that are part of policiesToBeDeployed are updated to the engine, and
+all policies under policiesToBeUndeployed are removed from the PDP engine.
+Once the processing of PDP_UPDATE message is complete, PDP sends back a PDP_STATUS
+message with the updated status, the current list of policies that are in the
+engine, and the result of the PDP_UPDATE operation.
+
+.. code-block:: json
+ :caption: Sample PDP_STATUS response message (from APEX-PDP)
+ :linenos:
+
+ {
+ "pdpType": "apex",
+ "state": "ACTIVE",
+ "healthy": "HEALTHY",
+ "description": "Pdp status response message for PdpUpdate",
+ "policies": [
+ {
+ "name": "onap.policies.apex.Simplecontrolloop",
+ "version": "1.0.0"
+ }
+ ],
+ "statistics": {
+ "pdpInstanceId": "apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02",
+ "timeStamp": "2021-09-22T15:37:18.075436Z",
+ "pdpGroupName": "defaultGroup",
+ "pdpSubGroupName": "apex",
+ "policyExecutedCount": 0,
+ "policyExecutedSuccessCount": 0,
+ "policyExecutedFailCount": 0,
+ "policyDeployCount": 1,
+ "policyDeploySuccessCount": 1,
+ "policyDeployFailCount": 0,
+ "policyUndeployCount": 0,
+ "policyUndeploySuccessCount": 0,
+ "policyUndeployFailCount": 0
+ },
+ "response": {
+ "responseTo": "4534e54f-4432-4c68-81c8-a6af07e59fb2",
+ "responseStatus": "SUCCESS",
+ "responseMessage": "Apex engine started. Deployed policies are: onap.policies.apex.Simplecontrolloop:1.0.0"
+ },
+ "messageName": "PDP_STATUS",
+ "requestId": "e3c72783-4e91-4cb5-8140-e4ac0630706d",
+ "timestampMs": 1632325038075,
+ "name": "apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02",
+ "pdpGroup": "defaultGroup",
+ "pdpSubgroup": "apex"
+ }
+
+More details about the messages used for PDP-PAP internal communication and their structure can be found here
+:ref:`The Internal Policy Framework PAP-PDP API <pap-pdp-label>`.