.. 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 `__ 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 three 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 The fields in the table below are valid on API calls: =============================== ======== ======== ======== ===================================================== **Field** **PDP **PDP **PDP **Comment** STATUS** UPDATE** STATE CHANGE** =============================== ======== ======== ======== ===================================================== (message_name) M M M pdp_status, pdp_update, pdp_state_change, or pdp_health_check name M M M 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 pdpType M N/A N/A The type of the PDP, currently xacml, drools, or apex state M N/A M The administrative state of the PDP group: PASSIVE, SAFE, TEST, ACTIVE, or TERMINATED healthy M 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 The description of the PDP pdpGroup M M C The PDP group to which the PDP belongs, the PDP group and subgroup can be used to specify the scope of the operation pdpSubgroup O M C The PDP subgroup to which the PDP belongs, the PDP group and subgroup can be used to specify the scope of the operation source N/A M M The source of the message policies M N/A N/A The list of policies running on the PDP policiesToBeDeployed N/A M N/A The list of policies to be deployed on the PDP policiesToBeUndeployed N/A M N/A The list of policies to be undeployed from the PDP ->(name) O M N/A The name of a TOSCA policy running on the PDP ->policy_type O M 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 The version of the TOSCA policy type of the policy ->properties O M N/A The properties of the policy for the XACML, Drools, or APEX PDP for details Pod properties O N/A N/A Other properties specific to the PDP statistics O N/A N/A Statistics on policy execution in the PDP ->policyDeployCount M N/A N/A The number of policies deployed into the PDP ->policyDeploySuccessCount M N/A N/A The number of policies successfully deployed into the PDP ->policyDeployFailCount M N/A N/A The number of policies deployed into the PDP where the deployment failed ->policyUndeployCount M N/A N/A The number of policies undeployed from the PDP ->policyUndeploySuccessCount M N/A N/A The number of policies successfully undeployed from the PDP ->policyUndeployFailCount M N/A N/A The number of policies undeployed from the PDP where the undeployment failed ->policyExecutedCount M N/A N/A The number of policy executions on the PDP ->policyExecutedSuccessCount M N/A N/A The number of policy executions on the PDP that completed successfully ->policyExecutedFailCount M N/A N/A The number of policy executions on the PDP that failed response O N/A N/A The response to the last operation that the PAP executed on the PDP ->responseTo M N/A N/A The PAP to PDP message to which this is a response ->responseStatus M N/A N/A SUCCESS or FAIL ->responseMessage O 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* and *PDP_STATE_CHANGE* 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 or pdp-state_change 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: pdpType: xacml state: ACTIVE healthy: HEALTHY description: XACML PDP running control loop policies policies: - name: SDNC_Policy.ONAP_NF_NAMING_TIMESTAMP version: 1.0.0 - name: onap.policies.controlloop.guard.frequencylimiter.EastRegion version: 1.0.0 - name: onap.policies.controlloop.guard.blacklist.eastRegion version: 1.0.0 - name: .policies.controlloop.guard.minmax.eastRegion version: 1.0.0 messageName: PDP_STATUS requestId: 5551bd1b-4020-4fc5-95b7-b89c80a337b1 timestampMs: 1633534472002 name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c pdpGroup: defaultGroup pdpSubgroup: xacml statistics: policyDeployCount: 0 policyDeploySuccessCount: 0 policyDeployFailCount: 0 policyExecutedCount: 123 policyExecutedSuccessCount: 122 policyExecutedFailCount: 1 .. code-block:: yaml :caption: PDP_STATUS message from a Drools PDP running control loop policies :linenos: pdp_status: pdpType: drools state: ACTIVE healthy: HEALTHY description: Drools PDP running control loop policies policies: - name: onap.controllloop.operational.drools.vcpe.EastRegion version: 1.0.0 - name: onap.controllloop.operational.drools.vfw.EastRegion version: 1.0.0 instance: drools_2 deployment_instance_info: node_address: drools_2_pod # Other deployment instance info statistics: policyDeployCount: 3 policyDeploySuccessCount: 3 policyDeployFailCount: 0 policyExecutedCount: 123 policyExecutedSuccessCount: 122 policyExecutedFailCount: 1 policyUndeployCount: 0 policyUndeploySuccessCount: 0 policyUndeployFailCount: 0 response: responseTo: 52117e25-f416-45c7-a955-83ed929d557f responseStatus: SUCCESSSS messageName: PDP_STATUS requestId: 52117e25-f416-45c7-a955-83ed929d557f timestampMs: 1633355052181 name: drools-8819a672-57fd-4e74-ad89-aed1a64e1837 pdpGroup: defaultGroup pdpSubgroup: drools .. code-block:: yaml :caption: PDP_STATUS message from an APEX PDP running control loop policies :linenos: pdpType: apex state: ACTIVE healthy: HEALTHY description: Pdp status response message for PdpUpdate policies: - name: onap.controllloop.operational.apex.bbs.EastRegion version: 1.0.0 statistics: policyExecutedCount: 0 policyExecutedSuccessCount: 0 policyExecutedFailCount: 0 policyDeployCount: 1 policyDeploySuccessCount: 1 policyDeployFailCount: 0 policyUndeployCount: 0 policyUndeploySuccessCount: 0 policyUndeployFailCount: 0 response: responseTo: 679fad9b-abbf-4b9b-971c-96a8372ec8af responseStatus: SUCCESS responseMessage: >- Apex engine started. Deployed policies are: onap.policies.apex.sample.Salecheck:1.0.0 messageName: PDP_STATUS requestId: 932c17b0-7ef9-44ec-be58-f17e104e7d5d timestampMs: 1633435952217 name: apex-d0610cdc-381e-4aae-8e99-3f520c2a50db pdpGroup: defaultGroup pdpSubgroup: apex .. code-block:: yaml :caption: PDP_STATUS message from an XACML PDP running monitoring policies :linenos: pdp_status: pdpType: xacml state: ACTIVE healthy: HEALTHY description: XACML PDP running control loop policies policies: - name: SDNC_Policy.ONAP_NF_NAMING_TIMESTAMP version: 1.0.0 - name: onap.scaleout.tca:message version: 1.0.0 messageName: PDP_STATUS requestId: 5551bd1b-4020-4fc5-95b7-b89c80a337b1 timestampMs: 1633534472002 name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c pdpGroup: onap.pdpgroup.Monitoring pdpSubgroup: xacml statistics: policyDeployCount: 0 policyDeploySuccessCount: 0 policyDeployFailCount: 0 policyExecutedCount: 123 policyExecutedSuccessCount: 122 policyExecutedFailCount: 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. The PAP sends *PDP_UPDATE* and *PDP_STATE_CHANGE* 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* message: - 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. 2.1 PDP Update -------------- The *PDP_UPDATE* operation allows the PAP to modify the PDP with information such as policiesToBeDeployed/Undeployed, the interval to send heartbeats, subgroup etc. 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: source: pap-6e46095a-3e12-4838-912b-a8608fc93b51 pdpHeartbeatIntervalMs: 120000 policiesToBeDeployed: - type: onap.policies.Naming type_version: 1.0.0 properties: # Omitted for brevity name: onap.policies.controlloop.guard.frequencylimiter.EastRegion version: 1.0.1 metadata: policy-id: onap.policies.controlloop.guard.frequencylimiter.EastRegion policy-version: 1.0.1 messageName: PDP_UPDATE requestId: cbfb9781-da6c-462f-9601-8cf8ca959d2b timestampMs: 1633466294898 name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c description: XACML PDP running control loop policies, Upgraded pdpGroup: defaultGroup pdpSubgroup: xacml .. code-block:: yaml :caption: PDP_UPDATE message to a Drools PDP to add an extra control loop policy :linenos: pdp_update: source: pap-0674bd0c-0862-4b72-abc7-74246fd11a79 pdpHeartbeatIntervalMs: 120000 policiesToBeDeployed: - type: onap.controllloop.operational.drools.vFW type_version: 1.0.0 properties: # Omitted for brevity name: onap.controllloop.operational.drools.vfw.WestRegion version: 1.0.0 metadata: policy-id: onap.controllloop.operational.drools.vfw.WestRegion policy-version: 1.0.0 messageName: PDP_UPDATE requestId: e91c4515-86db-4663-b68e-e5179d0b000e timestampMs: 1633355039004 name: drools-8819a672-57fd-4e74-ad89-aed1a64e1837 description: Drools PDP running control loop policies, extra policy added pdpGroup: defaultGroup pdpSubgroup: drools .. code-block:: yaml :caption: PDP_UPDATE message to an APEX PDP to remove a control loop policy :linenos: pdp_update: 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.controllloop.operational.apex.bbs.WestRegion version: 1.0.0 metadata: policy-id: onap.controllloop.operational.apex.bbs.WestRegion policy-version: 1.0.0 messageName: PDP_UPDATE requestId: 3534e54f-4432-4c68-81c8-a6af07e59fb2 timestampMs: 1632325037040 name: apex-45c6b266-a5fa-4534-b22c-33c2f9a45d02 pdpGroup: defaultGroup pdpSubgroup: apex 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 Drools PDP to ACTIVE :linenos: pdp_state_change: source: pap-6e46095a-3e12-4838-912b-a8608fc93b51 state: ACTIVE messageName: PDP_STATE_CHANGE requestId: 7d422be6-5baa-4316-9649-09e18301b5a8 timestampMs: 1633466294899 name: drools-23d33c2a-8715-43a8-ade5-5923fc0f185c pdpGroup: defaultGroup pdpSubgroup: drools .. code-block:: yaml :caption: Change the state of all XACML PDPs to ACTIVE :linenos: pdp_state_change: source: pap-6e46095a-3e12-4838-912b-a8608fc93b51 state: ACTIVE messageName: PDP_STATE_CHANGE requestId: 7d422be6-5baa-4316-9649-09e18301b5a8 timestampMs: 1633466294899 name: xacml-23d33c2a-8715-43a8-ade5-5923fc0f185c pdpGroup: defaultGroup pdpSubgroup: xacml .. code-block:: yaml :caption: Change the state of APEX PDP to passive :linenos: pdp_state_change: source: pap-e6272159-e1a3-4777-860a-19c47a14cc00 state: PASSIVE messageName: PDP_STATE_CHANGE requestId: 60d9a724-ebf3-4434-9da4-caac9c515a2c timestampMs: 1633528747518 name: apex-a3c58a9e-af72-436c-b46f-0c6f31032ca5 pdpGroup: defaultGroup pdpSubgroup: apex