diff options
Diffstat (limited to 'docs/design')
| -rw-r--r-- | docs/design/InternalPapPdp.rst | 428 |
1 files changed, 0 insertions, 428 deletions
diff --git a/docs/design/InternalPapPdp.rst b/docs/design/InternalPapPdp.rst deleted file mode 100644 index 998514af..00000000 --- a/docs/design/InternalPapPdp.rst +++ /dev/null @@ -1,428 +0,0 @@ -.. 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 |