.. 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