.. This work is licensed under a .. Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 .. _pap-pdp-label: The Internal Policy Framework PAP-PDP API ######################################### .. contents:: :depth: 3 This page describes the API between the PAP and PDPs. The APIs in this section are implemented using `DMaaP API <https://wiki.onap.org/display/DW/DMaaP+API>`__ messaging. The APIs in this section are used for internal communication in the Policy Framework. The APIs are NOT supported for use by components outside the Policy Framework and are subject to revision and change at any time. There are four messages on the API: 1. PDP_STATUS: PDP→PAP, used by PDPs to report to the PAP 2. PDP_UPDATE: PAP→PDP, used by the PAP to update the policies running on PDPs, triggers a PDP_STATUS message with the result of the PDP_UPDATE operation 3. PDP_STATE_CHANGE: PAP→PDP, used by the PAP to change the state of PDPs, triggers a PDP_STATUS message with the result of the PDP_STATE_CHANGE operation 4. PDP_HEALTH_CHECK: PAP→PDP, used by the PAP to order a health check on PDPs, triggers a PDP_STATUS message with the result of the PDP_HEALTH_CHECK operation The fields in the table below are valid on API calls: =============================== ======== ======== ======== ======= ===================================================== **Field** **PDP **PDP **PDP **PDP **Comment** STATUS** UPDATE** STATE HEALTH CHANGE** CHECK** =============================== ======== ======== ======== ======= ===================================================== (message_name) M M M M pdp_status, pdp_update, pdp_state_change, or pdp_health_check name M M C C The name of the PDP, for state changes and health checks, the PDP group and subgroup can be used to specify the scope of the operation version M N/A N/A N/A The version of the PDP pdp_type M M N/A N/A The type of the PDP, currently xacml, drools, or apex state M N/A M N/A The administrative state of the PDP group: PASSIVE, SAFE, TEST, ACTIVE, or TERMINATED healthy M N/A N/A N/A The result of the latest health check on the PDP: HEALTHY/NOT_HEALTHY/TEST_IN_PROGRESS description O O N/A N/A The description of the PDP pdp_group O M C C The PDP group to which the PDP belongs, the PDP group and subgroup can be used to specify the scope of the operation pdp_subgroup O M C C The PDP subgroup to which the PDP belongs, the PDP group and subgroup can be used to specify the scope of the operation supported_policy_types M N/A N/A N/A A list of the policy types supported by the PDP policies O M N/A N/A The list of policies running on the PDP ->(name) O M N/A N/A The name of a TOSCA policy running on the PDP ->policy_type O M N/A N/A The TOSCA policy type of the policyWhen a PDP starts, it commences periodic sending of *PDP_STATUS* messages on DMaaP. The PAP receives these messages and acts in whatever manner is appropriate. ->policy_type_version O M N/A N/A The version of the TOSCA policy type of the policy ->properties O M N/A N/A The properties of the policy for the XACML, Drools, or APEX PDP for details instance M N/A N/A N/A The instance ID of the PDP running in a Kuberenetes Pod deployment_instance_info M N/A N/A N/A Information on the node running the PDP properties O O N/A N/A Other properties specific to the PDP statistics M N/A N/A N/A Statistics on policy execution in the PDP ->policy_download_count M N/A N/A N/A The number of policies downloaded into the PDP ->policy_download_success_count M N/A N/A N/A The number of policies successfully downloaded into the PDP ->policy_download_fail_count M N/A N/A N/A The number of policies downloaded into the PDP where the download failed ->policy_executed_count M N/A N/A N/A The number of policy executions on the PDP ->policy_executed_success_count M N/A N/A N/A The number of policy executions on the PDP that completed successfully ->policy_executed_fail_count M N/A N/A N/A The number of policy executions on the PDP that failed response O N/A N/A N/A The response to the last operation that the PAP executed on the PDP ->response_to M N/A N/A N/A The PAP to PDP message to which this is a response ->response_status M N/A N/A N/A SUCCESS or FAIL ->response_message O N/A N/A N/A Message giving further information on the successful or failed operation =============================== ======== ======== ======== ======= ===================================================== YAML is used for illustrative purposes in the examples in this section. JSON (application/json) is used as the content type in the implementation of this API. 1 PAP API for PDPs ================== The purpose of this API is for PDPs to provide heartbeat, status, health, and statistical information to Policy Administration. There is a single *PDP_STATUS* message on this API. PDPs send this message to the PAP using the *POLICY_PDP_PAP* DMaaP topic. The PAP listens on this topic for messages. When a PDP starts, it commences periodic sending of *PDP_STATUS* messages on DMaaP. The PAP receives these messages and acts in whatever manner is appropriate. *PDP_UPDATE*, *PDP_STATE_CHANGE*, and *PDP_HEALTH_CHECK* operations trigger a *PDP_STATUS* message as a response. The *PDP_STATUS* message is used for PDP heartbeat monitoring. A PDP sends a *PDP_STATUS* message with a state of *TERMINATED* when it terminates normally. If a *PDP_STATUS* message is not received from a PDP periodically or in response to a pdp_update, pdp-state_change, or pdp_health_check message in a certain configurable time, then the PAP assumes the PDP has failed. A PDP may be preconfigured with its PDP group, PDP subgroup, and policies. If the PDP group, subgroup, or any policy sent to the PAP in a *PDP_STATUS* message is unknown to the PAP, the PAP locks the PDP in state PASSIVE. .. code-block:: yaml :caption: PDP_STATUS message from an XACML PDP running control loop policies :linenos: pdp_status: name: xacml_1 version: 1.2.3 pdp_type: xacml state: active healthy: true description: XACML PDP running control loop policies pdp_group: onap.pdpgroup.controlloop.operational pdp_subgroup: xacml supported_policy_types: - onap.policies.controlloop.guard.FrequencyLimiter - onap.policies.controlloop.guard.BlackList - onap.policies.controlloop.guard.MinMax policies: - onap.policies.controlloop.guard.frequencylimiter.EastRegion: policy_type: onap.policies.controlloop.guard.FrequencyLimiter policy_type_version: 1.0.0 properties: # Omitted for brevity - onap.policies.controlloop.guard.blacklist.eastRegion: policy_type: onap.policies.controlloop.guard.BlackList policy_type_version: 1.0.0 properties: # Omitted for brevity - onap.policies.controlloop.guard.minmax.eastRegion: policy_type: onap.policies.controlloop.guard.MinMax policy_type_version: 1.0.0 properties: # Omitted for brevity instance: xacml_1 deployment_instance_info: node_address: xacml_1_pod # Other deployment instance info statistics: policy_download_count: 0 policy_download_success_count: 0 policy_download_fail_count: 0 policy_executed_count: 123 policy_executed_success_count: 122 policy_executed_fail_count: 1 .. code-block:: yaml :caption: PDP_STATUS message from a Drools PDP running control loop policies :linenos: pdp_status: name: drools_2 version: 2.3.4 pdp_type: drools state: safe healthy: true description: Drools PDP running control loop policies pdp_group: onap.pdpgroup.controlloop.operational pdp_subgroup: drools supported_policy_types: - onap.controllloop.operational.drools.vCPE - onap.controllloop.operational.drools.vFW policies: - onap.controllloop.operational.drools.vcpe.EastRegion: policy_type: onap.controllloop.operational.drools.vCPE policy_type_version: 1.0.0 properties: # Omitted for brevity - onap.controllloop.operational.drools.vfw.EastRegion: policy_type: onap.controllloop.operational.drools.vFW policy_type_version: 1.0.0 properties: # Omitted for brevity instance: drools_2 deployment_instance_info: node_address: drools_2_pod # Other deployment instance info statistics: policy_download_count: 3 policy_download_success_count: 3 policy_download_fail_count: 0 policy_executed_count: 123 policy_executed_success_count: 122 policy_executed_fail_count: 1 response: response_to: PDP_HEALTH_CHECK response_status: SUCCESS .. code-block:: yaml :caption: PDP_STATUS message from an APEX PDP running control loop policies :linenos: pdp_status: name: drools_2 version: 2.3.4 pdp_type: drools state: safe healthy: true description: Drools PDP running control loop policies pdp_group: onap.pdpgroup.controlloop.operational pdp_subgroup: drools supported_policy_types: - onap.controllloop.operational.drools.vCPE - onap.controllloop.operational.drools.vFW policies: - onap.controllloop.operational.drools.vcpe.EastRegion: policy_type: onap.controllloop.operational.drools.vCPE policy_type_version: 1.0.0 properties: # Omitted for brevity - onap.controllloop.operational.drools.vfw.EastRegion: policy_type: onap.controllloop.operational.drools.vFW policy_type_version: 1.0.0 properties: # Omitted for brevity instance: drools_2 deployment_instance_info: node_address: drools_2_pod # Other deployment instance info statistics: policy_download_count: 3 policy_download_success_count: 3 policy_download_fail_count: 0 policy_executed_count: 123 policy_executed_success_count: 122 policy_executed_fail_count: 1 response: response_to: PDP_HEALTH_CHECK response_status: SUCCESS .. code-block:: yaml :caption: PDP_STATUS message from an XACML PDP running monitoring policies :linenos: pdp_status: name: xacml_1 version: 1.2.3 pdp_type: xacml state: active healthy: true description: XACML PDP running monitoring policies pdp_group: onap.pdpgroup.Monitoring pdp_subgroup: xacml supported_policy_types: - onap.monitoring.cdap.tca.hi.lo.app policies: - onap.scaleout.tca:message policy_type: onap.policies.monitoring.cdap.tca.hi.lo.app policy_type_version: 1.0.0 properties: # Omitted for brevity instance: xacml_1 deployment_instance_info: node_address: xacml_1_pod # Other deployment instance info statistics: policy_download_count: 0 policy_download_success_count: 0 policy_download_fail_count: 0 policy_executed_count: 123 policy_executed_success_count: 122 policy_executed_fail_count: 1 2 PDP API for PAPs ================== The purpose of this API is for the PAP to load and update policies on PDPs and to change the state of PDPs. It also allows the PAP to order health checks to run on PDPs. The PAP sends *PDP_UPDATE*, *PDP_STATE_CHANGE*, and *PDP_HEALTH_CHECK* messages to PDPs using the *POLICY_PAP_PDP* DMaaP topic. PDPs listen on this topic for messages. The PAP can set the scope of *PDP_STATE_CHANGE* and *PDP_HEALTH_CHECK* messages: - PDP Group: If a PDP group is specified in a message, then the PDPs in that PDP group respond to the message and all other PDPs ignore it. - PDP Group and subgroup: If a PDP group and subgroup are specified in a message, then only the PDPs of that subgroup in the PDP group respond to the message and all other PDPs ignore it. - Single PDP: If the name of a PDP is specified in a message, then only that PDP responds to the message and all other PDPs ignore it. Note: *PDP_UPDATE* messages must be issued individually to PDPs because the *PDP_UPDATE* operation can change the PDP group to which a PDP belongs. 2.1 PDP Update -------------- The *PDP_UPDATE* operation allows the PAP to modify the PDP group to which a PDP belongs and the policies in a PDP. The following examples illustrate how the operation is used. .. code-block:: yaml :caption: PDP_UPDATE message to upgrade XACML PDP control loop policies to version 1.0.1 :linenos: pdp_update: name: xacml_1 pdp_type: xacml description: XACML PDP running control loop policies, Upgraded pdp_group: onap.pdpgroup.controlloop.operational pdp_subgroup: xacml policies: - onap.policies.controlloop.guard.frequencylimiter.EastRegion: policy_type: onap.policies.controlloop.guard.FrequencyLimiter policy_type_version: 1.0.1 properties: # Omitted for brevity - onap.policies.controlloop.guard.blackList.EastRegion: policy_type: onap.policies.controlloop.guard.BlackList policy_type_version: 1.0.1 properties: # Omitted for brevity - onap.policies.controlloop.guard.minmax.EastRegion: policy_type: onap.policies.controlloop.guard.MinMax policy_type_version: 1.0.1 properties: # Omitted for brevity .. code-block:: yaml :caption: PDP_UPDATE message to a Drools PDP to add an extra control loop policy :linenos: pdp_update: name: drools_2 pdp_type: drools description: Drools PDP running control loop policies, extra policy added pdp_group: onap.pdpgroup.controlloop.operational pdp_subgroup: drools policies: - onap.controllloop.operational.drools.vcpe.EastRegion: policy_type: onap.controllloop.operational.drools.vCPE policy_type_version: 1.0.0 properties: # Omitted for brevity - onap.controllloop.operational.drools.vfw.EastRegion: policy_type: onap.controllloop.operational.drools.vFW policy_type_version: 1.0.0 properties: # Omitted for brevity - onap.controllloop.operational.drools.vfw.WestRegion: policy_type: onap.controllloop.operational.drools.vFW policy_type_version: 1.0.0 properties: # Omitted for brevity .. code-block:: yaml :caption: PDP_UPDATE message to an APEX PDP to remove a control loop policy :linenos: pdp_update: name: apex_3 pdp_type: apex description: APEX PDP updated to remove a control loop policy pdp_group: onap.pdpgroup.controlloop.operational pdp_subgroup: apex policies: - onap.controllloop.operational.apex.bbs.EastRegion: policy_type: onap.controllloop.operational.apex.BBS policy_type_version: 1.0.0 properties: # Omitted for brevity 2.2 PDP State Change -------------------- The *PDP_STATE_CHANGE* operation allows the PAP to order state changes on PDPs in PDP groups and subgroups. The following examples illustrate how the operation is used. .. code-block:: yaml :caption: Change the state of all control loop Drools PDPs to ACTIVE :linenos: pdp_state_change: state: active pdp_group: onap.pdpgroup.controlloop.Operational pdp_subgroup: drools .. code-block:: yaml :caption: Change the state of all monitoring PDPs to SAFE :linenos: pdp_state_change: state: safe pdp_group: onap.pdpgroup.Monitoring .. code-block:: yaml :caption: Change the state of a single APEX PDP to TEST :linenos: pdp_state_change: state: test name: apex_3 2.3 PDP Health Check -------------------- The *PDP_HEALTH_CHECK* operation allows the PAP to order health checks on PDPs in PDP groups and subgroups. The following examples illustrate how the operation is used. .. code-block:: yaml :caption: Perform a health check on all control loop Drools PDPs :linenos: pdp_health_check: pdp_group: onap.pdpgroup.controlloop.Operational pdp_subgroup: drools .. code-block:: yaml :caption: perform a health check on all monitoring PDPs :linenos: pdp_health_check: pdp_group: onap.pdpgroup.Monitoring .. code-block:: yaml :caption: Perform a health check on a single APEX PDP :linenos: pdp_health_check: name: apex_3