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