From 6eec8757733a8b6ff366b1980daff23323302a05 Mon Sep 17 00:00:00 2001 From: Pamela Dragosh Date: Thu, 21 May 2020 11:06:03 -0400 Subject: Fix last documentation warnings Had to add toctree to remove warnings. Do not seem to like the fact that an .rst is referenced via a label. Removed amsterdam controller and added frankfurt controller. Issue-ID: POLICY-2511 Change-Id: I5fb887b3a1d26a543c844d6baa34b3fa0e506f0a Signed-off-by: Pamela Dragosh --- docs/apex/APEX-Policy-Examples.rst | 7 + docs/api/api.rst | 3 - docs/architecture/architecture.rst | 7 + docs/design/InternalPapPdp.rst | 428 --------------------------------- docs/development/development.rst | 2 +- docs/development/devtools/apex-s3p.rst | 2 +- docs/development/devtools/devtools.rst | 2 + docs/drools/droolsFeaturesIndex.rst | 2 +- docs/drools/droolsTutorialsIndex.rst | 2 + docs/drools/feature_clamsterdam.rst | 32 --- docs/drools/feature_clfrankfurt.rst | 37 +++ docs/drools/feature_clusecases.rst | 12 +- docs/pap/InternalPapPdp.rst | 428 +++++++++++++++++++++++++++++++++ docs/pap/pap.rst | 3 + 14 files changed, 496 insertions(+), 471 deletions(-) delete mode 100644 docs/design/InternalPapPdp.rst delete mode 100644 docs/drools/feature_clamsterdam.rst create mode 100644 docs/drools/feature_clfrankfurt.rst create mode 100644 docs/pap/InternalPapPdp.rst diff --git a/docs/apex/APEX-Policy-Examples.rst b/docs/apex/APEX-Policy-Examples.rst index cb8fa8d3..982f3e0f 100644 --- a/docs/apex/APEX-Policy-Examples.rst +++ b/docs/apex/APEX-Policy-Examples.rst @@ -4,6 +4,13 @@ Policy Examples *************** +.. toctree:: + :maxdepth: 1 + + APEX-MyFirstPolicyExample.rst + APEX-PCVS-Example.rst + APEX-DecisionMakerExample.rst + .. contents:: :depth: 3 diff --git a/docs/api/api.rst b/docs/api/api.rst index 58f7e9e0..c65e35e8 100644 --- a/docs/api/api.rst +++ b/docs/api/api.rst @@ -2,9 +2,6 @@ .. Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 -.. DO NOT REMOVE THIS LABEL - EVEN IF IT GENERATES A WARNING -.. _offeredapis: - .. THIS IS USED INTERNALLY IN POLICY ONLY .. _api-label: diff --git a/docs/architecture/architecture.rst b/docs/architecture/architecture.rst index d061b1b7..4c8b3f7b 100644 --- a/docs/architecture/architecture.rst +++ b/docs/architecture/architecture.rst @@ -20,6 +20,13 @@ mapping out the components, software structure, and execution ecosystem of the f .. contents:: :depth: 6 +.. toctree:: + :caption: References + :maxdepth: 1 + + tosca-policy-primer + + 1. Overview =========== 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 `__ 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 diff --git a/docs/development/development.rst b/docs/development/development.rst index 66c095d3..87f49bc4 100644 --- a/docs/development/development.rst +++ b/docs/development/development.rst @@ -6,7 +6,7 @@ Policy Platform Development --------------------------- .. toctree:: - :maxdepth: 2 + :maxdepth: 3 devtools/devtools.rst actors/actors.rst diff --git a/docs/development/devtools/apex-s3p.rst b/docs/development/devtools/apex-s3p.rst index 1220621a..d3a8d410 100644 --- a/docs/development/devtools/apex-s3p.rst +++ b/docs/development/devtools/apex-s3p.rst @@ -313,7 +313,7 @@ The results are similar to those below: :download:`Example APEX performance metrics ` Performance Test Result Frankfurt ------------------------ +--------------------------------- **Summary** diff --git a/docs/development/devtools/devtools.rst b/docs/development/devtools/devtools.rst index a3016d48..1e2fd49f 100644 --- a/docs/development/devtools/devtools.rst +++ b/docs/development/devtools/devtools.rst @@ -281,3 +281,5 @@ familiar with the Policy Framework components and test any local changes. apex-s3p.rst drools-s3p.rst xacml-s3p.rst + distribution-s3p.rst + diff --git a/docs/drools/droolsFeaturesIndex.rst b/docs/drools/droolsFeaturesIndex.rst index e1e05fd8..869bc7af 100644 --- a/docs/drools/droolsFeaturesIndex.rst +++ b/docs/drools/droolsFeaturesIndex.rst @@ -11,7 +11,7 @@ PDP-D Features feature_activestdbymgmt.rst feature_controllerlogging.rst feature_clmgt.rst - feature_clamsterdam.rst + feature_clfrankfurt.rst feature_clusecases.rst feature_eelf.rst feature_healthcheck.rst diff --git a/docs/drools/droolsTutorialsIndex.rst b/docs/drools/droolsTutorialsIndex.rst index a1ccf844..ae6a2610 100644 --- a/docs/drools/droolsTutorialsIndex.rst +++ b/docs/drools/droolsTutorialsIndex.rst @@ -9,9 +9,11 @@ PDP-D Tutorials :maxdepth: 1 runningPDPD.rst + runningEclipse.rst clsimulation.rst guardpdp.rst modAAIdata.rst + modTemplate.rst tutorial_cl.rst tutorial_vCPE.rst tutorial_vDNS.rst diff --git a/docs/drools/feature_clamsterdam.rst b/docs/drools/feature_clamsterdam.rst deleted file mode 100644 index 74e2668a..00000000 --- a/docs/drools/feature_clamsterdam.rst +++ /dev/null @@ -1,32 +0,0 @@ - -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -******************************* -Feature: Control Loop Amsterdam -******************************* - -.. contents:: - :depth: 3 - -Summary -^^^^^^^ - -The "controlloop-amsterdam" feature enables the legacy "amsterdam" controller in a PDP-D. - -Usage -^^^^^ - -The feature is enabled by default. -The lifecycle "enabled" property can be toggled with the "features" command line tool. - - .. code-block:: bash - :caption: PDPD Features Command - - policy stop - - features disable controlloop-amsterdam # enable/disable toggles the activation of the feature. - - policy start - -End of Document diff --git a/docs/drools/feature_clfrankfurt.rst b/docs/drools/feature_clfrankfurt.rst new file mode 100644 index 00000000..629b3afd --- /dev/null +++ b/docs/drools/feature_clfrankfurt.rst @@ -0,0 +1,37 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +******************************* +Feature: Control Loop Frankfurt +******************************* + +.. contents:: + :depth: 3 + +Summary +^^^^^^^ + +The "controlloop-frankfurt" feature enables the "frankfurt" controller in a PDP-D. +The "frankfurt" controller supports the official ONAP use cases for Frankfurt. + +.. note:: + This feature is enabled by default vs the usecases controller which will be deprecated. In the Guilin release we will + be renaming this feature back to usecases. + +Usage +^^^^^ + +The feature is enabled by default. The lifecycle "enabled" property can be toggled with +the "features" command line tool. + + .. code-block:: bash + :caption: PDPD Features Command + + policy stop + + features disable controlloop-frankfurt # enable/disable toggles the activation of the feature. + + policy start + +End of Document diff --git a/docs/drools/feature_clusecases.rst b/docs/drools/feature_clusecases.rst index eab383f6..ae6fae5c 100644 --- a/docs/drools/feature_clusecases.rst +++ b/docs/drools/feature_clusecases.rst @@ -13,15 +13,17 @@ Summary ^^^^^^^ The "controlloop-usecases" feature enables the "usecases" controller in a PDP-D. -The "usecases" controller supports the official ONAP use cases in a more efficient manner than -the legacy "amsterdam" controller. -The main difference is that control loop provisioning does not need a new version upgrade -each time a control loop is added or removed. +The "usecases" controller is carried forward from the El Alto release and will be deprecated in favor of the +"frankfurt" controller. + +.. note:: + This feature is disabled by default. Please use the 'frankfurt' feature in lieu of this. We will be renaming the 'frankfurt' + controller feature back to use cases in the Guilin release. Usage ^^^^^ -The feature is enabled by default. The lifecycle "enabled" property can be toggled with +The feature is disabled by default. The lifecycle "enabled" property can be toggled with the "features" command line tool. .. code-block:: bash diff --git a/docs/pap/InternalPapPdp.rst b/docs/pap/InternalPapPdp.rst new file mode 100644 index 00000000..998514af --- /dev/null +++ b/docs/pap/InternalPapPdp.rst @@ -0,0 +1,428 @@ +.. 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 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 diff --git a/docs/pap/pap.rst b/docs/pap/pap.rst index ff6aac51..21b5b42b 100644 --- a/docs/pap/pap.rst +++ b/docs/pap/pap.rst @@ -9,6 +9,9 @@ Policy Administration Point (PAP) Architecture .. contents:: :depth: 3 +.. toctree:: + InternalPapPdp.rst + The Policy Administration Point (PAP) keeps track of PDPs, supporting the deployment of PDP groups and the deployment of policies across those PDP groups. Policies are created using the Policy API, but are deployed via the PAP. -- cgit 1.2.3-korg