Docs for PDP-PAP interaction

Change-Id: I10bd0a7c3df39d7f2fa6d13eaa947f172c98f578
Issue-ID: POLICY-3264
Signed-off-by: a.sreekumar <ajith.sreekumar@bell.ca>

2 files changed, 342 insertions, 0 deletions

diff --git a/docs/development/pdp/images/PDP_PAP.svg b/docs/development/pdp/images/PDP_PAP.svg
new file mode 100644
index 00000000..3594c762
--- /dev/null
+++ b/docs/development/pdp/images/PDP_PAP.svg
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentScriptType="application/ecmascript" contentStyleType="text/css" height="550px" preserveAspectRatio="none" style="width:1152px;height:550px;background:#FFFFFF;" version="1.1" viewBox="0 0 1152 550" width="1152px" zoomAndPan="magnify"><defs><filter height="300%" id="fd44imp969z1w" width="300%" x="-1" y="-1"><feGaussianBlur result="blurOut" stdDeviation="2.0"/><feColorMatrix in="blurOut" result="blurOut2" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .4 0"/><feOffset dx="4.0" dy="4.0" in="blurOut2" result="blurOut3"/><feBlend in="SourceGraphic" in2="blurOut3" mode="normal"/></filter></defs><g><text fill="#000000" font-family="sans-serif" font-size="18" lengthAdjust="spacing" textLength="230" x="462" y="28.708">PDP interaction with PAP</text><rect fill="#FFFFFF" filter="url(#fd44imp969z1w)" height="46.2656" style="stroke:#000000;stroke-width:2.0;" width="884.5" x="92" y="315.0469"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="27" x2="27" y1="123.25" y2="465.7109"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="125" x2="125" y1="123.25" y2="465.7109"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="192" x2="192" y1="123.25" y2="465.7109"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="943.5" x2="943.5" y1="123.25" y2="465.7109"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="1130" x2="1130" y1="123.25" y2="465.7109"/><rect fill="#FEFECE" filter="url(#fd44imp969z1w)" height="30.2969" style="stroke:#A80036;stroke-width:1.5;" width="41" x="5" y="87.9531"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="27" x="12" y="107.9482">K8S</text><rect fill="#FEFECE" filter="url(#fd44imp969z1w)" height="30.2969" style="stroke:#A80036;stroke-width:1.5;" width="41" x="5" y="464.7109"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="27" x="12" y="484.7061">K8S</text><rect fill="#FEFECE" filter="url(#fd44imp969z1w)" height="30.2969" style="stroke:#A80036;stroke-width:1.5;" width="43" x="102" y="87.9531"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="29" x="109" y="107.9482">PDP</text><rect fill="#FEFECE" filter="url(#fd44imp969z1w)" height="30.2969" style="stroke:#A80036;stroke-width:1.5;" width="43" x="102" y="464.7109"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="29" x="109" y="484.7061">PDP</text><rect fill="#FEFECE" filter="url(#fd44imp969z1w)" height="30.2969" style="stroke:#A80036;stroke-width:1.5;" width="62" x="159" y="87.9531"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="48" x="166" y="107.9482">DMaaP</text><rect fill="#FEFECE" filter="url(#fd44imp969z1w)" height="30.2969" style="stroke:#A80036;stroke-width:1.5;" width="62" x="159" y="464.7109"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="48" x="166" y="484.7061">DMaaP</text><rect fill="#FEFECE" filter="url(#fd44imp969z1w)" height="30.2969" style="stroke:#A80036;stroke-width:1.5;" width="42" x="920.5" y="87.9531"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="28" x="927.5" y="107.9482">PAP</text><rect fill="#FEFECE" filter="url(#fd44imp969z1w)" height="30.2969" style="stroke:#A80036;stroke-width:1.5;" width="42" x="920.5" y="464.7109"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="28" x="927.5" y="484.7061">PAP</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="31" x="1112" y="119.9482">User</text><ellipse cx="1130.5" cy="49.9531" fill="#FEFECE" filter="url(#fd44imp969z1w)" rx="8" ry="8" style="stroke:#A80036;stroke-width:2.0;"/><path d="M1130.5,57.9531 L1130.5,84.9531 M1117.5,65.9531 L1143.5,65.9531 M1130.5,84.9531 L1117.5,99.9531 M1130.5,84.9531 L1143.5,99.9531 " fill="none" filter="url(#fd44imp969z1w)" style="stroke:#A80036;stroke-width:2.0;"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="31" x="1112" y="477.7061">User</text><ellipse cx="1130.5" cy="491.0078" fill="#FEFECE" filter="url(#fd44imp969z1w)" rx="8" ry="8" style="stroke:#A80036;stroke-width:2.0;"/><path d="M1130.5,499.0078 L1130.5,526.0078 M1117.5,507.0078 L1143.5,507.0078 M1130.5,526.0078 L1117.5,541.0078 M1130.5,526.0078 L1143.5,541.0078 " fill="none" filter="url(#fd44imp969z1w)" style="stroke:#A80036;stroke-width:2.0;"/><polygon fill="#A80036" points="113.5,150.3828,123.5,154.3828,113.5,158.3828,117.5,154.3828" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="27.5" x2="119.5" y1="154.3828" y2="154.3828"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="9" x="34.5" y="149.3169">1</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="61" x="47.5" y="149.3169">Start PDP</text><polygon fill="#A80036" points="931.5,179.5156,941.5,183.5156,931.5,187.5156,935.5,183.5156" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="125.5" x2="937.5" y1="183.5156" y2="183.5156"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="9" x="132.5" y="178.4497">2</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="697" x="145.5" y="178.4497">Send PDP_STATUS (registration message) with state as PASSIVE and other info like PDP's Group/Type/Name.</text><polygon fill="#A80036" points="136.5,208.6484,126.5,212.6484,136.5,216.6484,132.5,212.6484" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="130.5" x2="942.5" y1="212.6484" y2="212.6484"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="8" x="142.5" y="207.5825">3</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="643" x="154.5" y="207.5825">Send PDP_UPDATE message with info like subgroup, heartbeat interval, policiesToBeDeployed if any</text><polygon fill="#A80036" points="931.5,237.7813,941.5,241.7813,931.5,245.7813,935.5,241.7813" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="125.5" x2="937.5" y1="241.7813" y2="241.7813"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="9" x="132.5" y="236.7153">4</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="731" x="145.5" y="236.7153">Send PDP_STATUS (response to PDP_UPDATE) with added information such as responseStatus/responseMessage.</text><polygon fill="#A80036" points="136.5,266.9141,126.5,270.9141,136.5,274.9141,132.5,270.9141" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="130.5" x2="942.5" y1="270.9141" y2="270.9141"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="9" x="142.5" y="265.8481">5</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="530" x="155.5" y="265.8481">Send PDP_STATE_CHANGE message asking the PDP to go from PASSIVE to ACTIVE</text><polygon fill="#A80036" points="931.5,296.0469,941.5,300.0469,931.5,304.0469,935.5,300.0469" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="125.5" x2="937.5" y1="300.0469" y2="300.0469"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="9" x="132.5" y="294.981">6</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="781" x="145.5" y="294.981">Send PDP_STATUS (response to PDP_STATE_CHANGE) with added information such as responseStatus/responseMessage.</text><path d="M92,315.0469 L170,315.0469 L170,322.0469 L160,332.0469 L92,332.0469 L92,315.0469 " fill="#EEEEEE" style="stroke:#000000;stroke-width:1.0;"/><rect fill="none" height="46.2656" style="stroke:#000000;stroke-width:2.0;" width="884.5" x="92" y="315.0469"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="33" x="107" y="328.1138">loop</text><text fill="#000000" font-family="sans-serif" font-size="11" font-weight="bold" lengthAdjust="spacing" textLength="61" x="185" y="327.2573">[forever]</text><polygon fill="#A80036" points="931.5,349.3125,941.5,353.3125,931.5,357.3125,935.5,353.3125" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="125.5" x2="937.5" y1="353.3125" y2="353.3125"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="9" x="132.5" y="348.2466">7</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="394" x="145.5" y="348.2466">Send PDP_STATUS which is the heartbeat message from PDP</text><polygon fill="#A80036" points="954.5,385.4453,944.5,389.4453,954.5,393.4453,950.5,389.4453" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="948.5" x2="1129.5" y1="389.4453" y2="389.4453"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="9" x="960.5" y="384.3794">8</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="150" x="973.5" y="384.3794">Deploy/Undeploy Policy</text><polygon fill="#A80036" points="136.5,414.5781,126.5,418.5781,136.5,422.5781,132.5,418.5781" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="130.5" x2="942.5" y1="418.5781" y2="418.5781"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="9" x="142.5" y="413.5122">9</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="464" x="155.5" y="413.5122">Send PDP_UPDATE message with the policiesToBeDeployed/Undeployed</text><polygon fill="#A80036" points="931.5,443.7109,941.5,447.7109,931.5,451.7109,935.5,447.7109" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:2.0,2.0;" x1="125.5" x2="937.5" y1="447.7109" y2="447.7109"/><text fill="#000000" font-family="sans-serif" font-size="13" font-weight="bold" lengthAdjust="spacing" textLength="19" x="132.5" y="442.645">10</text><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="731" x="155.5" y="442.645">Send PDP_STATUS (response to PDP_UPDATE) with added information such as responseStatus/responseMessage.</text><!--MD5=[e6c667340a3c9400f3b529b4b1acf584]
+@startuml
+title PDP interaction with PAP
+
+participant K8S
+participant PDP
+participant DMaaP
+participant PAP
+actor User
+
+autonumber
+
+K8S - -> PDP : Start PDP
+
+PDP - -> PAP: Send PDP_STATUS (registration message) with state as PASSIVE and other info like PDP's Group/Type/Name.
+
+PAP - -> PDP: Send PDP_UPDATE message with info like subgroup, heartbeat interval, policiesToBeDeployed if any
+
+PDP - -> PAP: Send PDP_STATUS (response to PDP_UPDATE) with added information such as responseStatus/responseMessage.
+
+PAP - -> PDP: Send PDP_STATE_CHANGE message asking the PDP to go from PASSIVE to ACTIVE
+
+PDP - -> PAP: Send PDP_STATUS (response to PDP_STATE_CHANGE) with added information such as responseStatus/responseMessage.
+
+loop forever
+  PDP - -> PAP: Send PDP_STATUS which is the heartbeat message from PDP
+end
+
+User - -> PAP: Deploy/Undeploy Policy
+
+PAP - -> PDP: Send PDP_UPDATE message with the policiesToBeDeployed/Undeployed
+
+PDP - -> PAP: Send PDP_STATUS (response to PDP_UPDATE) with added information such as responseStatus/responseMessage.
+@enduml
+
+PlantUML version 1.2021.11beta6(Unknown compile time)
+(GPL source distribution)
+Java Runtime: Java(TM) SE Runtime Environment
+JVM: Java HotSpot(TM) 64-Bit Server VM
+Default Encoding: UTF-8
+Language: en
+Country: US
+--></g></svg>
\ No newline at end of file
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>`.