docs/pap/InternalPapPdp.rst

   1 .. This work is licensed under a
   2 .. Creative Commons Attribution 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4
   5 .. _pap-pdp-label:
   6
   7 The Internal Policy Framework PAP-PDP API
   8 #########################################
   9
  10 .. contents::
  11     :depth: 3
  12
  13 This page describes the API between the PAP and PDPs. The APIs in this section are implemented using `DMaaP
  14 API <https://wiki.onap.org/display/DW/DMaaP+API>`__ messaging. The APIs in this section are used for internal
  15 communication in the Policy Framework. The APIs are NOT supported for use by components outside the Policy Framework and
  16 are subject to revision and change at any time.
  17
  18 There are four messages on the API:
  19
  20 1. PDP_STATUS: PDP→PAP, used by PDPs to report to the PAP
  21
  22 2. PDP_UPDATE: PAP→PDP, used by the PAP to update the policies running on PDPs, triggers a PDP_STATUS message with
  23    the result of the PDP_UPDATE operation
  24
  25 3. PDP_STATE_CHANGE: PAP→PDP, used by the PAP to change the state of PDPs, triggers a PDP_STATUS message with the result
  26    of the PDP_STATE_CHANGE operation
  27
  28 4. PDP_HEALTH_CHECK: PAP→PDP, used by the PAP to order a health check on PDPs, triggers a PDP_STATUS message with the
  29    result of the PDP_HEALTH_CHECK operation
  30
  31 The fields in the table below are valid on API calls:
  32
  33 =============================== ======== ======== ======== ======= =====================================================
  34 **Field**                       **PDP    **PDP    **PDP    **PDP   **Comment**
  35                                 STATUS** UPDATE** STATE    HEALTH
  36                                                   CHANGE** CHECK**
  37 =============================== ======== ======== ======== ======= =====================================================
  38 (message_name)                  M        M        M        M       pdp_status, pdp_update, pdp_state_change, or
  39                                                                    pdp_health_check
  40 name                            M        M        C        C       The name of the PDP, for state changes and health
  41                                                                    checks, the PDP group and subgroup can be used to
  42                                                                    specify the scope of the operation
  43 version                         M        N/A      N/A      N/A     The version of the PDP
  44 pdp_type                        M        M        N/A      N/A     The type of the PDP, currently xacml, drools, or apex
  45 state                           M        N/A      M        N/A     The administrative state of the PDP group: PASSIVE,
  46                                                                    SAFE, TEST, ACTIVE, or TERMINATED
  47 healthy                         M        N/A      N/A      N/A     The result of the latest health check on the PDP:
  48                                                                    HEALTHY/NOT_HEALTHY/TEST_IN_PROGRESS
  49 description                     O        O        N/A      N/A     The description of the PDP
  50 pdp_group                       O        M        C        C       The PDP group to which the PDP belongs, the PDP group
  51                                                                    and subgroup can be used to specify the scope of the
  52                                                                    operation
  53 pdp_subgroup                    O        M        C        C       The PDP subgroup to which the PDP belongs, the PDP
  54                                                                    group and subgroup can be used to specify the scope
  55                                                                    of the operation
  56 supported_policy_types          M        N/A      N/A      N/A     A list of the policy types supported by the PDP
  57 policies                        O        M        N/A      N/A     The list of policies running on the PDP
  58 ->(name)                        O        M        N/A      N/A     The name of a TOSCA policy running on the PDP
  59 ->policy_type                   O        M        N/A      N/A     The TOSCA policy type of the policyWhen a PDP starts,
  60                                                                    it commences periodic sending of *PDP_STATUS*
  61                                                                    messages on DMaaP. The PAP receives these messages
  62                                                                    and acts in whatever manner is appropriate.
  63 ->policy_type_version           O        M        N/A      N/A     The version of the TOSCA policy type of the policy
  64 ->properties                    O        M        N/A      N/A     The properties of the policy for the XACML, Drools,
  65                                                                    or APEX PDP for details
  66 instance                        M        N/A      N/A      N/A     The instance ID of the PDP running in a Kuberenetes
  67                                                                    Pod
  68 deployment_instance_info        M        N/A      N/A      N/A     Information on the node running the PDP
  69 properties                      O        O        N/A      N/A     Other properties specific to the PDP
  70 statistics                      M        N/A      N/A      N/A     Statistics on policy execution in the PDP
  71 ->policy_download_count         M        N/A      N/A      N/A     The number of policies downloaded into the PDP
  72 ->policy_download_success_count M        N/A      N/A      N/A     The number of policies successfully downloaded into
  73                                                                    the PDP
  74 ->policy_download_fail_count    M        N/A      N/A      N/A     The number of policies downloaded into the PDP where
  75                                                                    the download failed
  76 ->policy_executed_count         M        N/A      N/A      N/A     The number of policy executions on the PDP
  77 ->policy_executed_success_count M        N/A      N/A      N/A     The number of policy executions on the PDP that
  78                                                                    completed successfully
  79 ->policy_executed_fail_count    M        N/A      N/A      N/A     The number of policy executions on the PDP that
  80                                                                    failed
  81 response                        O        N/A      N/A      N/A     The response to the last operation that the PAP
  82                                                                    executed on the PDP
  83 ->response_to                   M        N/A      N/A      N/A     The PAP to PDP message to which this is a response
  84 ->response_status               M        N/A      N/A      N/A     SUCCESS or FAIL
  85 ->response_message              O        N/A      N/A      N/A     Message giving further information on the successful
  86                                                                    or failed operation
  87 =============================== ======== ======== ======== ======= =====================================================
  88
  89 YAML is used for illustrative purposes in the examples in this section. JSON (application/json) is used as the content
  90 type in the implementation of this API.
  91
  92 1 PAP API for PDPs
  93 ==================
  94 The purpose of this API is for PDPs to provide heartbeat, status, health, and statistical information to Policy
  95 Administration. There is a single *PDP_STATUS* message on this API. PDPs send this message to the PAP using the
  96 *POLICY_PDP_PAP* DMaaP topic. The PAP listens on this topic for messages.
  97
  98 When a PDP starts, it commences periodic sending of *PDP_STATUS* messages on DMaaP. The PAP receives these messages and
  99 acts in whatever manner is appropriate. *PDP_UPDATE*, *PDP_STATE_CHANGE*, and *PDP_HEALTH_CHECK* operations trigger a
 100 *PDP_STATUS* message as a response.
 101
 102 The *PDP_STATUS* message is used for PDP heartbeat monitoring. A PDP sends a *PDP_STATUS* message with a state of
 103 *TERMINATED* when it terminates normally. If a *PDP_STATUS* message is not received from a PDP periodically or in
 104 response to a pdp_update, pdp-state_change, or pdp_health_check message in a certain configurable time, then the PAP
 105 assumes the PDP has failed.
 106
 107 A PDP may be preconfigured with its PDP group, PDP subgroup, and policies. If the PDP group, subgroup, or any policy
 108 sent to the PAP in a *PDP_STATUS* message is unknown to the PAP, the PAP locks the PDP in state PASSIVE.
 109
 110 .. code-block:: yaml
 111   :caption: PDP_STATUS message from an XACML PDP running control loop policies
 112   :linenos:
 113
 114   pdp_status:
 115     name: xacml_1
 116     version: 1.2.3
 117     pdp_type: xacml
 118     state: active
 119     healthy: true
 120     description: XACML PDP running control loop policies
 121     pdp_group: onap.pdpgroup.controlloop.operational
 122     pdp_subgroup: xacml
 123     supported_policy_types:
 124       - onap.policies.controlloop.guard.FrequencyLimiter
 125       - onap.policies.controlloop.guard.BlackList
 126       - onap.policies.controlloop.guard.MinMax
 127     policies:
 128       - onap.policies.controlloop.guard.frequencylimiter.EastRegion:
 129           policy_type: onap.policies.controlloop.guard.FrequencyLimiter
 130           policy_type_version: 1.0.0
 131           properties:
 132             # Omitted for brevity
 133      - onap.policies.controlloop.guard.blacklist.eastRegion:
 134           policy_type: onap.policies.controlloop.guard.BlackList
 135           policy_type_version: 1.0.0
 136           properties:
 137             # Omitted for brevity
 138       - onap.policies.controlloop.guard.minmax.eastRegion:
 139           policy_type: onap.policies.controlloop.guard.MinMax
 140           policy_type_version: 1.0.0
 141           properties:
 142             # Omitted for brevity
 143     instance: xacml_1
 144     deployment_instance_info:
 145       node_address: xacml_1_pod
 146       # Other deployment instance info
 147     statistics:
 148       policy_download_count: 0
 149       policy_download_success_count: 0
 150       policy_download_fail_count: 0
 151       policy_executed_count: 123
 152       policy_executed_success_count: 122
 153       policy_executed_fail_count: 1
 154
 155 .. code-block:: yaml
 156   :caption: PDP_STATUS message from a Drools PDP running control loop policies
 157   :linenos:
 158
 159   pdp_status:
 160     name: drools_2
 161     version: 2.3.4
 162     pdp_type: drools
 163     state: safe
 164     healthy: true
 165     description: Drools PDP running control loop policies
 166     pdp_group: onap.pdpgroup.controlloop.operational
 167     pdp_subgroup: drools
 168     supported_policy_types:
 169       - onap.controllloop.operational.drools.vCPE
 170       - onap.controllloop.operational.drools.vFW
 171     policies:
 172       - onap.controllloop.operational.drools.vcpe.EastRegion:
 173           policy_type: onap.controllloop.operational.drools.vCPE
 174           policy_type_version: 1.0.0
 175           properties:
 176             # Omitted for brevity
 177       - onap.controllloop.operational.drools.vfw.EastRegion:
 178           policy_type: onap.controllloop.operational.drools.vFW
 179           policy_type_version: 1.0.0
 180           properties:
 181             # Omitted for brevity
 182     instance: drools_2
 183     deployment_instance_info:
 184       node_address: drools_2_pod
 185       # Other deployment instance info
 186     statistics:
 187       policy_download_count: 3
 188       policy_download_success_count: 3
 189       policy_download_fail_count: 0
 190       policy_executed_count: 123
 191       policy_executed_success_count: 122
 192       policy_executed_fail_count: 1
 193     response:
 194       response_to: PDP_HEALTH_CHECK
 195       response_status: SUCCESS
 196
 197 .. code-block:: yaml
 198   :caption: PDP_STATUS message from an APEX PDP running control loop policies
 199   :linenos:
 200
 201   pdp_status:
 202     name: drools_2
 203     version: 2.3.4
 204     pdp_type: drools
 205     state: safe
 206     healthy: true
 207     description: Drools PDP running control loop policies
 208     pdp_group: onap.pdpgroup.controlloop.operational
 209     pdp_subgroup: drools
 210     supported_policy_types:
 211       - onap.controllloop.operational.drools.vCPE
 212       - onap.controllloop.operational.drools.vFW
 213     policies:
 214       - onap.controllloop.operational.drools.vcpe.EastRegion:
 215           policy_type: onap.controllloop.operational.drools.vCPE
 216           policy_type_version: 1.0.0
 217           properties:
 218             # Omitted for brevity
 219       - onap.controllloop.operational.drools.vfw.EastRegion:
 220           policy_type: onap.controllloop.operational.drools.vFW
 221           policy_type_version: 1.0.0
 222           properties:
 223             # Omitted for brevity
 224     instance: drools_2
 225     deployment_instance_info:
 226       node_address: drools_2_pod
 227       # Other deployment instance info
 228     statistics:
 229       policy_download_count: 3
 230       policy_download_success_count: 3
 231       policy_download_fail_count: 0
 232       policy_executed_count: 123
 233       policy_executed_success_count: 122
 234       policy_executed_fail_count: 1
 235     response:
 236       response_to: PDP_HEALTH_CHECK
 237       response_status: SUCCESS
 238
 239 .. code-block:: yaml
 240   :caption: PDP_STATUS message from an XACML PDP running monitoring policies
 241   :linenos:
 242
 243   pdp_status:
 244     name: xacml_1
 245     version: 1.2.3
 246     pdp_type: xacml
 247     state: active
 248     healthy: true
 249     description: XACML PDP running monitoring policies
 250     pdp_group: onap.pdpgroup.Monitoring
 251     pdp_subgroup: xacml
 252     supported_policy_types:
 253       - onap.monitoring.tcagen2
 254      policies:
 255       - onap.scaleout.tca:message
 256           policy_type: onap.policies.monitoring.tcagen2
 257           policy_type_version: 1.0.0
 258           properties:
 259             # Omitted for brevity
 260     instance: xacml_1
 261     deployment_instance_info:
 262       node_address: xacml_1_pod
 263       # Other deployment instance info
 264     statistics:
 265       policy_download_count: 0
 266       policy_download_success_count: 0
 267       policy_download_fail_count: 0
 268       policy_executed_count: 123
 269       policy_executed_success_count: 122
 270       policy_executed_fail_count: 1
 271
 272 2 PDP API for PAPs
 273 ==================
 274
 275 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
 276 allows the PAP to order health checks to run on PDPs. The PAP sends *PDP_UPDATE*, *PDP_STATE_CHANGE*, and
 277 *PDP_HEALTH_CHECK* messages to PDPs using the *POLICY_PAP_PDP* DMaaP topic. PDPs listen on this topic for messages.
 278
 279 The PAP can set the scope of *PDP_STATE_CHANGE* and *PDP_HEALTH_CHECK* messages:
 280
 281 -  PDP Group: If a PDP group is specified in a message, then the PDPs in that PDP group respond to the message and all
 282    other PDPs ignore it.
 283
 284 -  PDP Group and subgroup: If a PDP group and subgroup are specified in a message, then only the PDPs of that subgroup
 285    in the PDP group respond to the message and all other PDPs ignore it.
 286
 287 -  Single PDP: If the name of a PDP is specified in a message, then only that PDP responds to the message and all other
 288    PDPs ignore it.
 289
 290 Note: *PDP_UPDATE* messages must be issued individually to PDPs because the *PDP_UPDATE* operation can change the PDP
 291 group to which a PDP belongs.
 292
 293 2.1 PDP Update
 294 --------------
 295
 296 The *PDP_UPDATE* operation allows the PAP to modify the PDP group to which a PDP belongs and the policies in a PDP.
 297
 298 The following examples illustrate how the operation is used.
 299
 300 .. code-block:: yaml
 301   :caption: PDP_UPDATE message to upgrade XACML PDP control loop policies to version 1.0.1
 302   :linenos:
 303
 304   pdp_update:
 305     name: xacml_1
 306     pdp_type: xacml
 307     description: XACML PDP running control loop policies, Upgraded
 308     pdp_group: onap.pdpgroup.controlloop.operational
 309     pdp_subgroup: xacml
 310     policies:
 311       - onap.policies.controlloop.guard.frequencylimiter.EastRegion:
 312           policy_type: onap.policies.controlloop.guard.FrequencyLimiter
 313           policy_type_version: 1.0.1
 314           properties:
 315             # Omitted for brevity
 316      - onap.policies.controlloop.guard.blackList.EastRegion:
 317           policy_type: onap.policies.controlloop.guard.BlackList
 318           policy_type_version: 1.0.1
 319           properties:
 320             # Omitted for brevity
 321       - onap.policies.controlloop.guard.minmax.EastRegion:
 322           policy_type: onap.policies.controlloop.guard.MinMax
 323           policy_type_version: 1.0.1
 324           properties:
 325             # Omitted for brevity
 326
 327 .. code-block:: yaml
 328   :caption: PDP_UPDATE message to a Drools PDP to add an extra control loop policy
 329   :linenos:
 330
 331   pdp_update:
 332     name: drools_2
 333     pdp_type: drools
 334     description: Drools PDP running control loop policies, extra policy added
 335     pdp_group: onap.pdpgroup.controlloop.operational
 336     pdp_subgroup: drools
 337     policies:
 338       - onap.controllloop.operational.drools.vcpe.EastRegion:
 339           policy_type: onap.controllloop.operational.drools.vCPE
 340           policy_type_version: 1.0.0
 341           properties:
 342             # Omitted for brevity
 343       - onap.controllloop.operational.drools.vfw.EastRegion:
 344           policy_type: onap.controllloop.operational.drools.vFW
 345           policy_type_version: 1.0.0
 346           properties:
 347             # Omitted for brevity
 348       - onap.controllloop.operational.drools.vfw.WestRegion:
 349           policy_type: onap.controllloop.operational.drools.vFW
 350           policy_type_version: 1.0.0
 351           properties:
 352             # Omitted for brevity
 353
 354 .. code-block:: yaml
 355   :caption: PDP_UPDATE message to an APEX PDP to remove a control loop policy
 356   :linenos:
 357
 358     pdp_update:
 359     name: apex_3
 360     pdp_type: apex
 361     description: APEX PDP updated to remove a control loop policy
 362     pdp_group: onap.pdpgroup.controlloop.operational
 363     pdp_subgroup: apex
 364     policies:
 365       - onap.controllloop.operational.apex.bbs.EastRegion:
 366           policy_type: onap.controllloop.operational.apex.BBS
 367           policy_type_version: 1.0.0
 368           properties:
 369             # Omitted for brevity
 370
 371 2.2 PDP State Change
 372 --------------------
 373
 374 The *PDP_STATE_CHANGE* operation allows the PAP to order state changes on PDPs in PDP groups and subgroups. The
 375 following examples illustrate how the operation is used.
 376
 377 .. code-block:: yaml
 378   :caption: Change the state of all control loop Drools PDPs to ACTIVE
 379   :linenos:
 380
 381   pdp_state_change:
 382     state: active
 383     pdp_group: onap.pdpgroup.controlloop.Operational
 384     pdp_subgroup: drools
 385
 386 .. code-block:: yaml
 387   :caption: Change the state of all monitoring PDPs to SAFE
 388   :linenos:
 389
 390   pdp_state_change:
 391     state: safe
 392     pdp_group: onap.pdpgroup.Monitoring
 393
 394 .. code-block:: yaml
 395   :caption: Change the state of a single APEX PDP to TEST
 396   :linenos:
 397
 398   pdp_state_change:
 399     state: test
 400     name: apex_3
 401
 402 2.3 PDP Health Check
 403 --------------------
 404
 405 The *PDP_HEALTH_CHECK* operation allows the PAP to order health checks on PDPs in PDP groups and subgroups. The
 406 following examples illustrate how the operation is used.
 407
 408 .. code-block:: yaml
 409   :caption: Perform a health check on all control loop Drools PDPs
 410   :linenos:
 411
 412   pdp_health_check:
 413     pdp_group: onap.pdpgroup.controlloop.Operational
 414     pdp_subgroup: drools
 415
 416 .. code-block:: yaml
 417   :caption: perform a health check on all monitoring PDPs
 418   :linenos:
 419
 420   pdp_health_check:
 421     pdp_group: onap.pdpgroup.Monitoring
 422
 423 .. code-block:: yaml
 424   :caption: Perform a health check on a single APEX PDP
 425   :linenos:
 426
 427   pdp_health_check:
 428     name: apex_3