diff options
Diffstat (limited to 'docs/drools')
110 files changed, 2816 insertions, 1 deletions
diff --git a/docs/drools/RunEcl_console_output.png b/docs/drools/RunEcl_console_output.png Binary files differnew file mode 100755 index 00000000..d2c39439 --- /dev/null +++ b/docs/drools/RunEcl_console_output.png diff --git a/docs/drools/RunEcl_drools_pdp_project.png b/docs/drools/RunEcl_drools_pdp_project.png Binary files differnew file mode 100755 index 00000000..bafb94ea --- /dev/null +++ b/docs/drools/RunEcl_drools_pdp_project.png diff --git a/docs/drools/RunEcl_main.png b/docs/drools/RunEcl_main.png Binary files differnew file mode 100755 index 00000000..9dec695f --- /dev/null +++ b/docs/drools/RunEcl_main.png diff --git a/docs/drools/RunEcl_pdpd_200.png b/docs/drools/RunEcl_pdpd_200.png Binary files differnew file mode 100755 index 00000000..32e4e5ed --- /dev/null +++ b/docs/drools/RunEcl_pdpd_200.png diff --git a/docs/drools/RunEcl_run_as.png b/docs/drools/RunEcl_run_as.png Binary files differnew file mode 100755 index 00000000..579dc4db --- /dev/null +++ b/docs/drools/RunEcl_run_as.png diff --git a/docs/drools/RunEcl_telemetry.png b/docs/drools/RunEcl_telemetry.png Binary files differnew file mode 100755 index 00000000..ae4f65cc --- /dev/null +++ b/docs/drools/RunEcl_telemetry.png diff --git a/docs/drools/Tut_cl_confirmAndDirectory.PNG b/docs/drools/Tut_cl_confirmAndDirectory.PNG Binary files differnew file mode 100755 index 00000000..cdb84a89 --- /dev/null +++ b/docs/drools/Tut_cl_confirmAndDirectory.PNG diff --git a/docs/drools/Tut_cl_finalStep.PNG b/docs/drools/Tut_cl_finalStep.PNG Binary files differnew file mode 100755 index 00000000..b56b06e4 --- /dev/null +++ b/docs/drools/Tut_cl_finalStep.PNG diff --git a/docs/drools/Tut_cl_preDeploy.PNG b/docs/drools/Tut_cl_preDeploy.PNG Binary files differnew file mode 100755 index 00000000..69a2cdb1 --- /dev/null +++ b/docs/drools/Tut_cl_preDeploy.PNG diff --git a/docs/drools/Tut_cl_propFile.PNG b/docs/drools/Tut_cl_propFile.PNG Binary files differnew file mode 100755 index 00000000..960e182d --- /dev/null +++ b/docs/drools/Tut_cl_propFile.PNG diff --git a/docs/drools/Tut_cl_valuesHighlight.png b/docs/drools/Tut_cl_valuesHighlight.png Binary files differnew file mode 100755 index 00000000..7a4bb790 --- /dev/null +++ b/docs/drools/Tut_cl_valuesHighlight.png diff --git a/docs/drools/Tut_vCPE_appc_request.JPG b/docs/drools/Tut_vCPE_appc_request.JPG Binary files differnew file mode 100755 index 00000000..75d8848a --- /dev/null +++ b/docs/drools/Tut_vCPE_appc_request.JPG diff --git a/docs/drools/Tut_vCPE_final_memory.JPG b/docs/drools/Tut_vCPE_final_memory.JPG Binary files differnew file mode 100755 index 00000000..f68aac79 --- /dev/null +++ b/docs/drools/Tut_vCPE_final_memory.JPG diff --git a/docs/drools/Tut_vCPE_get_facts.JPG b/docs/drools/Tut_vCPE_get_facts.JPG Binary files differnew file mode 100755 index 00000000..27637257 --- /dev/null +++ b/docs/drools/Tut_vCPE_get_facts.JPG diff --git a/docs/drools/Tut_vCPE_get_facts_2.JPG b/docs/drools/Tut_vCPE_get_facts_2.JPG Binary files differnew file mode 100755 index 00000000..4bf8e9f3 --- /dev/null +++ b/docs/drools/Tut_vCPE_get_facts_2.JPG diff --git a/docs/drools/Tut_vCPE_guard_not_queried.JPG b/docs/drools/Tut_vCPE_guard_not_queried.JPG Binary files differnew file mode 100755 index 00000000..14e52e79 --- /dev/null +++ b/docs/drools/Tut_vCPE_guard_not_queried.JPG diff --git a/docs/drools/Tut_vCPE_guard_result.JPG b/docs/drools/Tut_vCPE_guard_result.JPG Binary files differnew file mode 100755 index 00000000..b1818d39 --- /dev/null +++ b/docs/drools/Tut_vCPE_guard_result.JPG diff --git a/docs/drools/Tut_vCPE_inject_appc_response.JPG b/docs/drools/Tut_vCPE_inject_appc_response.JPG Binary files differnew file mode 100755 index 00000000..6f5f21ba --- /dev/null +++ b/docs/drools/Tut_vCPE_inject_appc_response.JPG diff --git a/docs/drools/Tut_vCPE_insert_abatement.JPG b/docs/drools/Tut_vCPE_insert_abatement.JPG Binary files differnew file mode 100755 index 00000000..d0da4d5d --- /dev/null +++ b/docs/drools/Tut_vCPE_insert_abatement.JPG diff --git a/docs/drools/Tut_vCPE_insert_onset.JPG b/docs/drools/Tut_vCPE_insert_onset.JPG Binary files differnew file mode 100755 index 00000000..0316609a --- /dev/null +++ b/docs/drools/Tut_vCPE_insert_onset.JPG diff --git a/docs/drools/Tut_vCPE_policy_active.JPG b/docs/drools/Tut_vCPE_policy_active.JPG Binary files differnew file mode 100755 index 00000000..02544f41 --- /dev/null +++ b/docs/drools/Tut_vCPE_policy_active.JPG diff --git a/docs/drools/Tut_vCPE_policy_final_success.JPG b/docs/drools/Tut_vCPE_policy_final_success.JPG Binary files differnew file mode 100755 index 00000000..f063d09c --- /dev/null +++ b/docs/drools/Tut_vCPE_policy_final_success.JPG diff --git a/docs/drools/Tut_vCPE_policy_operation.JPG b/docs/drools/Tut_vCPE_policy_operation.JPG Binary files differnew file mode 100755 index 00000000..1666ea62 --- /dev/null +++ b/docs/drools/Tut_vCPE_policy_operation.JPG diff --git a/docs/drools/Tut_vCPE_policy_operation_success.JPG b/docs/drools/Tut_vCPE_policy_operation_success.JPG Binary files differnew file mode 100755 index 00000000..9206847f --- /dev/null +++ b/docs/drools/Tut_vCPE_policy_operation_success.JPG diff --git a/docs/drools/Tut_vCPE_policy_start.JPG b/docs/drools/Tut_vCPE_policy_start.JPG Binary files differnew file mode 100755 index 00000000..91be90e6 --- /dev/null +++ b/docs/drools/Tut_vCPE_policy_start.JPG diff --git a/docs/drools/Tut_vCPE_simulated_abatement.JPG b/docs/drools/Tut_vCPE_simulated_abatement.JPG Binary files differnew file mode 100755 index 00000000..2133ff85 --- /dev/null +++ b/docs/drools/Tut_vCPE_simulated_abatement.JPG diff --git a/docs/drools/Tut_vCPE_simulated_appc_response.JPG b/docs/drools/Tut_vCPE_simulated_appc_response.JPG Binary files differnew file mode 100755 index 00000000..3d90e04d --- /dev/null +++ b/docs/drools/Tut_vCPE_simulated_appc_response.JPG diff --git a/docs/drools/Tut_vCPE_simulated_onset.JPG b/docs/drools/Tut_vCPE_simulated_onset.JPG Binary files differnew file mode 100755 index 00000000..a50b3c29 --- /dev/null +++ b/docs/drools/Tut_vCPE_simulated_onset.JPG diff --git a/docs/drools/Tut_vCPE_simulators_enabled.JPG b/docs/drools/Tut_vCPE_simulators_enabled.JPG Binary files differnew file mode 100755 index 00000000..8cd9902d --- /dev/null +++ b/docs/drools/Tut_vCPE_simulators_enabled.JPG diff --git a/docs/drools/Tut_vFW_aai_get.JPG b/docs/drools/Tut_vFW_aai_get.JPG Binary files differnew file mode 100755 index 00000000..1b00d60b --- /dev/null +++ b/docs/drools/Tut_vFW_aai_get.JPG diff --git a/docs/drools/Tut_vFW_aai_named_query_request.JPG b/docs/drools/Tut_vFW_aai_named_query_request.JPG Binary files differnew file mode 100755 index 00000000..c7f86f93 --- /dev/null +++ b/docs/drools/Tut_vFW_aai_named_query_request.JPG diff --git a/docs/drools/Tut_vFW_aai_named_query_response.JPG b/docs/drools/Tut_vFW_aai_named_query_response.JPG Binary files differnew file mode 100755 index 00000000..b3a9fa94 --- /dev/null +++ b/docs/drools/Tut_vFW_aai_named_query_response.JPG diff --git a/docs/drools/Tut_vFW_appc_request.JPG b/docs/drools/Tut_vFW_appc_request.JPG Binary files differnew file mode 100755 index 00000000..737719f7 --- /dev/null +++ b/docs/drools/Tut_vFW_appc_request.JPG diff --git a/docs/drools/Tut_vFW_final_memory.JPG b/docs/drools/Tut_vFW_final_memory.JPG Binary files differnew file mode 100755 index 00000000..f68aac79 --- /dev/null +++ b/docs/drools/Tut_vFW_final_memory.JPG diff --git a/docs/drools/Tut_vFW_get_facts.JPG b/docs/drools/Tut_vFW_get_facts.JPG Binary files differnew file mode 100755 index 00000000..27637257 --- /dev/null +++ b/docs/drools/Tut_vFW_get_facts.JPG diff --git a/docs/drools/Tut_vFW_get_facts_2.JPG b/docs/drools/Tut_vFW_get_facts_2.JPG Binary files differnew file mode 100755 index 00000000..4bf8e9f3 --- /dev/null +++ b/docs/drools/Tut_vFW_get_facts_2.JPG diff --git a/docs/drools/Tut_vFW_insert_appc_response.JPG b/docs/drools/Tut_vFW_insert_appc_response.JPG Binary files differnew file mode 100755 index 00000000..d631603c --- /dev/null +++ b/docs/drools/Tut_vFW_insert_appc_response.JPG diff --git a/docs/drools/Tut_vFW_onset_injected.JPG b/docs/drools/Tut_vFW_onset_injected.JPG Binary files differnew file mode 100755 index 00000000..ebff2e36 --- /dev/null +++ b/docs/drools/Tut_vFW_onset_injected.JPG diff --git a/docs/drools/Tut_vFW_policy_active.JPG b/docs/drools/Tut_vFW_policy_active.JPG Binary files differnew file mode 100755 index 00000000..d3530a74 --- /dev/null +++ b/docs/drools/Tut_vFW_policy_active.JPG diff --git a/docs/drools/Tut_vFW_policy_final_success.JPG b/docs/drools/Tut_vFW_policy_final_success.JPG Binary files differnew file mode 100755 index 00000000..bdb7858b --- /dev/null +++ b/docs/drools/Tut_vFW_policy_final_success.JPG diff --git a/docs/drools/Tut_vFW_policy_guard_result.JPG b/docs/drools/Tut_vFW_policy_guard_result.JPG Binary files differnew file mode 100755 index 00000000..89a2f4f8 --- /dev/null +++ b/docs/drools/Tut_vFW_policy_guard_result.JPG diff --git a/docs/drools/Tut_vFW_policy_guard_start.JPG b/docs/drools/Tut_vFW_policy_guard_start.JPG Binary files differnew file mode 100755 index 00000000..1aa5490a --- /dev/null +++ b/docs/drools/Tut_vFW_policy_guard_start.JPG diff --git a/docs/drools/Tut_vFW_policy_operation_start.JPG b/docs/drools/Tut_vFW_policy_operation_start.JPG Binary files differnew file mode 100755 index 00000000..0203c93a --- /dev/null +++ b/docs/drools/Tut_vFW_policy_operation_start.JPG diff --git a/docs/drools/Tut_vFW_policy_operation_success.JPG b/docs/drools/Tut_vFW_policy_operation_success.JPG Binary files differnew file mode 100755 index 00000000..8e4b8e18 --- /dev/null +++ b/docs/drools/Tut_vFW_policy_operation_success.JPG diff --git a/docs/drools/Tut_vFW_policy_start.JPG b/docs/drools/Tut_vFW_policy_start.JPG Binary files differnew file mode 100755 index 00000000..91be90e6 --- /dev/null +++ b/docs/drools/Tut_vFW_policy_start.JPG diff --git a/docs/drools/Tut_vFW_simulated_appc_response.JPG b/docs/drools/Tut_vFW_simulated_appc_response.JPG Binary files differnew file mode 100755 index 00000000..8ceb89cf --- /dev/null +++ b/docs/drools/Tut_vFW_simulated_appc_response.JPG diff --git a/docs/drools/Tut_vFW_simulated_onset.JPG b/docs/drools/Tut_vFW_simulated_onset.JPG Binary files differnew file mode 100755 index 00000000..b6d40113 --- /dev/null +++ b/docs/drools/Tut_vFW_simulated_onset.JPG diff --git a/docs/drools/Tut_vFW_simulators_enabled.JPG b/docs/drools/Tut_vFW_simulators_enabled.JPG Binary files differnew file mode 100755 index 00000000..8cd9902d --- /dev/null +++ b/docs/drools/Tut_vFW_simulators_enabled.JPG diff --git a/docs/drools/clsimulation.rst b/docs/drools/clsimulation.rst new file mode 100644 index 00000000..8182ebb5 --- /dev/null +++ b/docs/drools/clsimulation.rst @@ -0,0 +1,696 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +********************************************************** +Control Loop Simulation and Injection of Messages Overview +********************************************************** + +.. contents:: + :depth: 2 + +Telemetry +^^^^^^^^^ +The username and password for the Telemetry commands are in *${POLCIY_HOME}/config/policy-engine.properties*. + +Injecting messages: +------------------- + +To inject messages use the following command. The injected message will look as if it came in from the specified topic and will be processed accordingly. + +Use the command: + + .. code-block:: bash + + http --verify=no --default-scheme=https -a <userName>:<password> PUT :9696/policy/pdp/engine/topics/sources/ueb/<topic>/events @<onsetFile> Content-Type:"text/plain" + +Alternatively, this command could be used: + + .. code-block:: bash + + curl --insecure --silent --user <userName>:<password> -X PUT --header "Content-Type: text/plain" --data @<onsetFile> https://localhost:9696/policy/pdp/engine/topics/sources/ueb/<topic>/events + +The topic being used is *unauthenticated.DCAE_CL_OUTPUT*, which is subject to change. The onset file is a file that contains the data to inject as the onset. The data contained depends on the use case. This is an example for VoLTE: + + .. code-block:: json + :caption: VoLTE_Sample_Onset + + { + "closedLoopControlName": "ControlLoop-VOLTE-2179b738-fd36-4843-a71a-a8c24c70c55b", + "closedLoopAlarmStart": 1484677482204798, + "closedLoopEventClient": "DCAE.HolmesInstance", + "closedLoopEventStatus": "ONSET", + "requestID": "97964e10-686e-4790-8c45-bdfa61df770f", + "target_type": "VM", + "target": "vserver.vserver-name", + "AAI": { + "vserver.is-closed-loop-disabled": "false", + "vserver.vserver-name": "dfw1lb01lb01", + "service-instance.service-instance-id" : "vserver-name-16102016-aai3255-data-11-1", + "generic-vnf.vnf-id" : "vnf-id-16102016-aai3255-data-11-1", + "generic-vnf.vnf-name" : "vnf-name-16102016-aai3255-data-11-1" + }, + "from": "DCAE", + "version": "1.0.2" + } + +Getting Information +------------------- + +To get the name of the active controller(s), use: + + .. code-block:: bash + + curl --insecure --silent --user <username>:<password> -X GET https://localhost:9696/policy/pdp/engine/controllers | python -m json.tool + +To check the facts currently in memory, use the following command. There should be 1 each of org.onap.policy.controlloop.PapParams and org.onap.policy.controlloop.Params per policy pushed. + + .. code-block:: bash + + curl --insecure --silent --user <username>:<password> -X GET https://localhost:9696/policy/pdp/engine/controllers/<controllerName>/drools/facts/<artifactId> | python -m json.tool + +To get additional information about the controller, use: + + .. code-block:: bash + + curl --insecure --silent --user <username>:<password> -X GET https://localhost:9696/policy/pdp/engine/controllers/<controllerName> | python -m json.tool + + +Simulators +^^^^^^^^^^ + +Currently, there are 4 supported simulators: A&AI, SO, vFC, and guard. When they are up, they are accessed via localhost on the following ports: A&AI – 6666, SO – 6667, vFC – 6668, and guard – 6669. They all respond with hard-coded values representing their various success messages except for with certain inputs. For the A&AI simulator, if the value being queried with a “GET” query is “getFail” the simulator returns an exception message, if the value being queried in a “GET” query is “disableClosedLoop” the simulator returns a response with the value of “is-closed-loop-disabled” set to true, and if the value being queried in a named query is “error” the response from the simulator is A&AI’s failure message. The other simulator that can return multiple response is the guard simulator, and that returns a deny response if the closed loop control name passed in is “denyGuard” + +Using the Simulators +-------------------- + +To check the status of the simulators, run the command: "*features status*". If the feature controlloop-utils is enabled, the simulators are being used, otherwise, they are not. + +**Turning on the simulators** + + - First, make sure the controller is off by running the command “*policy stop*”. + - Then turn the feature on with the command “*features enable controlloop-utils*”. + - Finally restart the controller by running “*policy start*”. + - Run “*features status*” again and the *feature controlloop-utils* will be **enabled**. + +**Turning the simulators off** + + - First, make sure the controller is off by running the command “*policy stop*”. + - Then turn the feature off with the command “*features disable controlloop-utils*”. + - Finally restart the controller by running “*policy start*”. + - Run “*features status*” again and the *feature controlloop-utils* will be **disabled**. + +**For Junits** + + For Junits, the package *org.onap.policy.simulators* is neeeded. In the Util class, there are four methods to start the four different simulators: *buildAaiSim()*, *buildSoSim()*, *buildVfcSim()*, and *buildGuardSim()*. Once the method is called, the simulator should be up and waiting to respond to requests. To bring down the simulators, call *HttpServletServer.factory.destroy()*. + +Responses +--------- + +**A&AI** + + .. code-block:: bash + :caption: vnf-GET-response + + { + "vnf-id": vnfId, //vnfId will be the vnfId you query on. If you query on a vnfName, the id will be "error" if the name is "error", "5e49ca06-2972-4532-9ed4-6d071588d792" otherwise + "vnf-name": vnfName, //vnfName will be the vnfName you query on. If you query on a vnfId, the name will be "USUCP0PCOIL0110UJRT01" + "vnf-type": "RT", + "service-id": "d7bb0a21-66f2-4e6d-87d9-9ef3ced63ae4", + "equipment-role": "UCPE", + "orchestration-status": "created", + "management-option": "ATT", + "ipv4-oam-address": "32.40.68.35", + "ipv4-loopback0-address": "32.40.64.57", + "nm-lan-v6-address": "2001:1890:e00e:fffe::1345", + "management-v6-address": "2001:1890:e00e:fffd::36", + "in-maint": false, + "prov-status":"ACTIVE", + "is-closed-loop-disabled": isDisabled, //isDisabled will be true if the vnf name/Id you query on is disableClosedLoop, false otherwise + "resource-version": "1493389458092", + "relationship-list": { + "relationship": [{ + "related-to": "service-instance", + "related-link": "/aai/v11/business/customers/customer/1610_Func_Global_20160817084727/service-subscriptions/service-subscription/uCPE-VMS/service-instances/service-instance/USUCP0PCOIL0110UJZZ01", + "relationship-data": [{ + "relationship-key": "customer.global-customer-id", + "relationship-value": "1610_Func_Global_20160817084727" + }, { + "relationship-key": "service-subscription.service-type", + "relationship-value": "uCPE-VMS" + }, { + "relationship-key": "service-instance.service-instance-id", + "relationship-value": "USUCP0PCOIL0110UJZZ01" + }], + "related-to-property": [{ + "property-key": "service-instance.service-instance-name" + }] + }, { + "related-to": "vserver", + "related-link": "/aai/v11/cloud-infrastructure/cloud-regions/cloud-region/att-aic/AAIAIC25/tenants/tenant/USUCP0PCOIL0110UJZZ01%3A%3AuCPE-VMS/vservers/vserver/3b2558f4-39d8-40e7-bfc7-30660fb52c45", + "relationship-data": [{ + "relationship-key": "cloud-region.cloud-owner", + "relationship-value": "att-aic" + }, { + "relationship-key": "cloud-region.cloud-region-id", + "relationship-value": "AAIAIC25" + }, { + "relationship-key": "tenant.tenant-id", + "relationship-value": "USUCP0PCOIL0110UJZZ01::uCPE-VMS" + }, { + "relationship-key": "vserver.vserver-id", + "relationship-value": "3b2558f4-39d8-40e7-bfc7-30660fb52c45" + }], + "related-to-property": [{ + "property-key": "vserver.vserver-name", + "property-value": "USUCP0PCOIL0110UJZZ01-vsrx" + }] + }] + } + + + .. code-block:: bash + :caption: vnf-GET-fail + + //This is returned if you query on the value "getFail" + { + "requestError": { + "serviceException": { + "messageId": "SVC3001", + "text": "Resource not found for %1 using id %2 (msg=%3) (ec=%4)", + "variables": ["GET", "network/generic-vnfs/generic-vnf/getFail", "Node Not Found:No Node of type generic-vnf found at network/generic-vnfs/generic-vnf/getFail", "ERR.5.4.6114"] + } + } + } + + + .. code-block:: bash + :caption: vserver-GET-response + + { + "vserver": [{ + "vserver-id": "d0668d4f-c25e-4a1b-87c4-83845c01efd8", + "vserver-name": vserverName, // The value you query on + "vserver-name2": "vjunos0", + "vserver-selflink": "https://aai-ext1.test.att.com:8443/aai/v7/cloud-infrastructure/cloud-regions/cloud-region/att-aic/AAIAIC25/tenants/tenant/USMSO1SX7NJ0103UJZZ01%3A%3AuCPE-VMS/vservers/vserver/d0668d4f-c25e-4a1b-87c4-83845c01efd8", + "in-maint": false, + "prov-status":"ACTIVE", + "is-closed-loop-disabled": isDisabled, // True if the vserverName is "disableClosedLoop", false otherwise + "resource-version": "1494001931513", + "relationship-list": { + "relationship": [{ + "related-to": "generic-vnf", + "related-link": "/aai/v11/network/generic-vnfs/generic-vnf/e1a41e99-4ede-409a-8f9d-b5e12984203a", + "relationship-data": [{ + "relationship-key": "generic-vnf.vnf-id", + "relationship-value": "e1a41e99-4ede-409a-8f9d-b5e12984203a" + }], + "related-to-property": [{ + "property-key": "generic-vnf.vnf-name", + "property-value": "USMSO1SX7NJ0103UJSW01" + }] + }, { + "related-to": "pserver", + "related-link": "/aai/v11/cloud-infrastructure/pservers/pserver/USMSO1SX7NJ0103UJZZ01", + "relationship-data": [{ + "relationship-key": "pserver.hostname", + "relationship-value": "USMSO1SX7NJ0103UJZZ01" + }], + "related-to-property": [{ + "property-key": "pserver.pserver-name2" + }] + }] + } + }] + } + + + .. code-block:: bash + :caption: vserver-GET-error + + //This is returned if you query on the value "getFail" + { + "requestError": { + "serviceException": { + "messageId": "SVC3001", + "text": "Resource not found for %1 using id %2 (msg=%3) (ec=%4)", + "variables": ["GET", "nodes/vservers", "Node Not Found:No Node of type generic-vnf found at nodes/vservers", "ERR.5.4.6114"] + } + } + } + + + .. code-block:: bash + :caption: vnf-NamedQuery-response + + { + "inventory-response-item": [ + { + "model-name": "service-instance", + "generic-vnf": { + "vnf-id": "vnfId", //vnfId will be the vnfId you query on + "vnf-name": "ZRDM2MMEX39", + "vnf-type": "vMME Svc Jul 14/vMME VF Jul 14 1", + "service-id": "a9a77d5a-123e-4ca2-9eb9-0b015d2ee0fb", + "prov-status": "ACTIVE", + "in-maint": false, + "is-closed-loop-disabled": false, + "resource-version": "1503082370097", + "model-invariant-id": "82194af1-3c2c-485a-8f44-420e22a9eaa4", + "model-version-id": "46b92144-923a-4d20-b85a-3cbd847668a9" + }, + "extra-properties": { + "extra-property": [] + }, + "inventory-response-items": { + "inventory-response-item": [ + { + "model-name": "service-instance", + "service-instance": { + "service-instance-id": "37b8cdb7-94eb-468f-a0c2-4e3c3546578e", + "service-instance-name": "Changed Service Instance NAME", + "resource-version": "1503082993532", + "model-invariant-id": "82194af1-3c2c-485a-8f44-420e22a9eaa4", + "model-version-id": "46b92144-923a-4d20-b85a-3cbd847668a9" + }, + "extra-properties": { + "extra-property": [] + }, + "inventory-response-items": { + "inventory-response-item": [ + { + "model-name": "pnf", + "generic-vnf": { + "vnf-id": "pnfVnfId", // pnfVnfId is UUID generated from ${pnfVnfName} + "vnf-name": "pnfVnfName", // pnfVnfName is pnf-test-${vnfId} + "vnf-type": "vMME Svc Jul 14/vMME VF Jul 14 1", + "service-id": "a9a77d5a-123e-4ca2-9eb9-0b015d2ee0fb", + "in-maint": false, + "is-closed-loop-disabled": false, + "resource-version": "1504013830207", + "model-invariant-id": "862b25a1-262a-4961-bdaa-cdc55d69785a", + "model-version-id": "e9f1fa7d-c839-418a-9601-03dc0d2ad687" + }, + "extra-properties": { + "extra-property": [] + } + }, + { + "model-name": "service-instance", + "generic-vnf": { + "vnf-id": "serviceInstanceVnfId", // serviceInstanceVnfId is UUID generated from ${serviceInstanceVnfName} + "vnf-name": "serviceInstanceVnfName", // serviceInstanceVnfName is service-instance-test-${vnfId} + "vnf-type": "vMME Svc Jul 14/vMME VF Jul 14 1", + "service-id": "a9a77d5a-123e-4ca2-9eb9-0b015d2ee0fb", + "in-maint": false, + "is-closed-loop-disabled": false, + "resource-version": "1504014833841", + "model-invariant-id": "Eace933104d443b496b8.nodes.heat.vpg", + "model-version-id": "46b92144-923a-4d20-b85a-3cbd847668a9" + }, + "extra-properties": { + "extra-property": [] + } + } + ] + } + } + ] + } + } + ] + } + + + .. code-block:: bash + :caption: vserver-NamedQuery-response + + { + "inventory-response-item": [ + { + "vserver": { + "vserver-id": "6ed3642c-f7a1-4a7c-9290-3d51fe1531eb", + "vserver-name": "zdfw1lb01lb02", + "vserver-name2": "zdfw1lb01lb02", + "prov-status": "ACTIVE", + "vserver-selflink": "http://10.12.25.2:8774/v2.1/41d6d38489bd40b09ea8a6b6b852dcbd/servers/6ed3642c-f7a1-4a7c-9290-3d51fe1531eb", + "in-maint": false, + "is-closed-loop-disabled": false, + "resource-version": "1510606403522" + }, + "extra-properties": { + "extra-property": [] + }, + "inventory-response-items": { + "inventory-response-item": [ + { + "model-name": "vLoadBalancer", + "generic-vnf": { + "vnf-id": "db373a8d-f7be-4d02-8ac8-6ca4c305d144", + "vnf-name": "Vfmodule_vLB1113", + "vnf-type": "vLoadBalancer-1106/vLoadBalancer 0", + "service-id": "66f157fc-4148-4880-95f5-e120677e98d1", + "prov-status": "PREPROV", + "in-maint": false, + "is-closed-loop-disabled": false, + "resource-version": "1510604011851", + "model-invariant-id": "cee050ed-92a5-494f-ab04-234307a846dc", + "model-version-id": "fd65becc-6b2c-4fe8-ace9-cc29db9a3da2" + }, + "extra-properties": { + "extra-property": [ + { + "property-name": "model-ver.model-version-id", + "property-value": "fd65becc-6b2c-4fe8-ace9-cc29db9a3da2" + }, + { + "property-name": "model-ver.model-name", + "property-value": "vLoadBalancer" + }, + { + "property-name": "model.model-type", + "property-value": "resource" + }, + { + "property-name": "model.model-invariant-id", + "property-value": "cee050ed-92a5-494f-ab04-234307a846dc" + }, + { + "property-name": "model-ver.model-version", + "property-value": "1.0" + } + ] + }, + "inventory-response-items": { + "inventory-response-item": [ + { + "model-name": "vLoadBalancer-1106", + "service-instance": { + "service-instance-id": "3b12f31f-8f2d-4f5c-b875-61ff1194b941", + "service-instance-name": "vLoadBalancer-1113", + "resource-version": "1510603936425", + "model-invariant-id": "1321d60d-f7ff-4300-96c2-6bf0b3268b7a", + "model-version-id": "732d4692-4b97-46f9-a996-0b3339e88c50" + }, + "extra-properties": { + "extra-property": [ + { + "property-name": "model-ver.model-version-id", + "property-value": "732d4692-4b97-46f9-a996-0b3339e88c50" + }, + { + "property-name": "model-ver.model-name", + "property-value": "vLoadBalancer-1106" + }, + { + "property-name": "model.model-type", + "property-value": "service" + }, + { + "property-name": "model.model-invariant-id", + "property-value": "1321d60d-f7ff-4300-96c2-6bf0b3268b7a" + }, + { + "property-name": "model-ver.model-version", + "property-value": "1.0" + } + ] + } + }, + { + "model-name": "Vloadbalancer..base_vlb..module-0", + "vf-module": { + "vf-module-id": "e6b3e3eb-34e1-4c00-b8c1-2a4fbe479b12", + "vf-module-name": "Vfmodule_vLB1113-1", + "heat-stack-id": "Vfmodule_vLB1113-1/3dd6d900-772f-4fcc-a0cb-e250ab2bb4db", + "orchestration-status": "active", + "is-base-vf-module": true, + "resource-version": "1510604612557", + "model-invariant-id": "6d760188-9a24-451a-b05b-e08b86cb94f2", + "model-version-id": "93facad9-55f2-4fe0-9574-814c2bc2d071" + }, + "extra-properties": { + "extra-property": [ + { + "property-name": "model-ver.model-version-id", + "property-value": "93facad9-55f2-4fe0-9574-814c2bc2d071" + }, + { + "property-name": "model-ver.model-name", + "property-value": "Vloadbalancer..base_vlb..module-0" + }, + { + "property-name": "model.model-type", + "property-value": "resource" + }, + { + "property-name": "model.model-invariant-id", + "property-value": "6d760188-9a24-451a-b05b-e08b86cb94f2" + }, + { + "property-name": "model-ver.model-version", + "property-value": "1" + } + ] + } + }, + { + "model-name": "Vloadbalancer..dnsscaling..module-1", + "vf-module": { + "vf-module-id": "dummy_db373a8d-f7be-4d02-8ac8-6ca4c305d144", + "vf-module-name": "dummy_db373a8d-f7be-4d02-8ac8-6ca4c305d144", + "is-base-vf-module": false, + "resource-version": "1510610079687", + "model-invariant-id": "356a1cff-71f2-4086-9980-a2927ce11c1c", + "model-version-id": "6b93d804-cfc8-4be3-92cc-9336d135859a" + }, + "extra-properties": { + "extra-property": [ + { + "property-name": "model-ver.model-version-id", + "property-value": "6b93d804-cfc8-4be3-92cc-9336d135859a" + }, + { + "property-name": "model-ver.model-name", + "property-value": "Vloadbalancer..dnsscaling..module-1" + }, + { + "property-name": "model.model-type", + "property-value": "resource" + }, + { + "property-name": "model.model-invariant-id", + "property-value": "356a1cff-71f2-4086-9980-a2927ce11c1c" + }, + { + "property-name": "model-ver.model-version", + "property-value": "1" + } + ] + } + }, + { + "model-name": "Vloadbalancer..dnsscaling..module-1", + "vf-module": { + "vf-module-id": "my_module_db373a8d-f7be-4d02-8ac8-6ca4c305d144", + "vf-module-name": "my_module_1", + "is-base-vf-module": false, + "resource-version": "1510610079687", + "model-invariant-id": "356a1cff-71f2-4086-9980-a2927ce11c1c", + "model-version-id": "6b93d804-cfc8-4be3-92cc-9336d135859a" + }, + "extra-properties": { + "extra-property": [ + { + "property-name": "model-ver.model-version-id", + "property-value": "6b93d804-cfc8-4be3-92cc-9336d135859a" + }, + { + "property-name": "model-ver.model-name", + "property-value": "Vloadbalancer..dnsscaling..module-1" + }, + { + "property-name": "model.model-type", + "property-value": "resource" + }, + { + "property-name": "model.model-invariant-id", + "property-value": "356a1cff-71f2-4086-9980-a2927ce11c1c" + }, + { + "property-name": "model-ver.model-version", + "property-value": "1" + } + ] + } + }, + { + "model-name": "Vloadbalancer..dnsscaling..module-1", + "vf-module": { + "vf-module-id": "my_module_db373a8d-f7be-4d02-8ac8-6ca4c305d144", + "vf-module-name": "my_module_2", + "is-base-vf-module": false, + "resource-version": "1510610079687", + "model-invariant-id": "356a1cff-71f2-4086-9980-a2927ce11c1c", + "model-version-id": "6b93d804-cfc8-4be3-92cc-9336d135859a" + }, + "extra-properties": { + "extra-property": [ + { + "property-name": "model-ver.model-version-id", + "property-value": "6b93d804-cfc8-4be3-92cc-9336d135859a" + }, + { + "property-name": "model-ver.model-name", + "property-value": "Vloadbalancer..dnsscaling..module-1" + }, + { + "property-name": "model.model-type", + "property-value": "resource" + }, + { + "property-name": "model.model-invariant-id", + "property-value": "356a1cff-71f2-4086-9980-a2927ce11c1c" + }, + { + "property-name": "model-ver.model-version", + "property-value": "1" + } + ] + } + } + ] + } + }, + { + "tenant": { + "tenant-id": "41d6d38489bd40b09ea8a6b6b852dcbd", + "tenant-name": "Integration-SB-00", + "resource-version": "1509587770200" + }, + "extra-properties": { + "extra-property": [] + }, + "inventory-response-items": { + "inventory-response-item": [ + { + "cloud-region": { + "cloud-owner": "CloudOwner", + "cloud-region-id": "RegionOne", + "cloud-region-version": "v1", + "resource-version": "1509587770092" + }, + "extra-properties": { + "extra-property": [] + } + } + ] + } + } + ] + } + } + ] + } + + + .. code-block:: bash + :caption: NamedQuery-error + + // This is returned if you query the value "error" + { + "requestError": { + "serviceException": { + "messageId": "SVC3001", + "text": "Resource not found for %1 using id %2 (msg=%3) (ec=%4)", + "variables": ["POST Search", "getNamedQueryResponse", "Node Not Found:No Node of type generic-vnf found for properties", "ERR.5.4.6114"] + } + } + } + + +**SO** + + .. code-block:: bash + :caption: SO-response + + { + "requestReferences": { + "requestId":"3e074e0e-5468-48f2-9226-51039d30fe5d" // randomly generated UUID + }, + "request": { + "requestId":"a8f58372-aab2-45b8-9d36-c7a42e701c29", // randomly generated UUID + "requestStatus": { + "percentProgress":0, + "requestState":"COMPLETE", + "wasRolledBack":false + } + } + } + } + + + +**vFC** + + .. code-block:: bash + :caption: vFC-POST-response + + { + "jobId": "1" + } + + + .. code-block:: bash + :caption: vFC-GET-response + + { + "jobId": jobId, //The jod id that you query + "responseDescriptor": { + "progress": "40", + "status": "finished", + "statusDescription": "OMC VMs are decommissioned in VIM", + "errorCode": null, + "responseId": 101, + "responseHistoryList": [{ + "progress": "40", + "status": "proccessing", + "statusDescription": "OMC VMs are decommissioned in VIM", + "errorCode": null, + "responseId": "1" + }, { + "progress": "41", + "status": "proccessing", + "statusDescription": "OMC VMs are decommissioned in VIM", + "errorCode": null, + "responseId": "2" + }] + } + } + + +**GUARD** + + .. code-block:: bash + :caption: permit-response + + { + "decision": "PERMIT", + "details": "Decision Permit. OK!" + } + + + .. code-block:: bash + :caption: deny-response + + //This is returned if the closed loop name is denyGuard + { + "decision": "DENY", + "details": "Decision Deny. You asked for it" + } + + +End of Document + +.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Control+Loop+Simulation+and+Injection+of+Messages+Overview + diff --git a/docs/drools/ctrlog_config.png b/docs/drools/ctrlog_config.png Binary files differnew file mode 100755 index 00000000..8d5aeb65 --- /dev/null +++ b/docs/drools/ctrlog_config.png diff --git a/docs/drools/ctrlog_enablefeature.png b/docs/drools/ctrlog_enablefeature.png Binary files differnew file mode 100755 index 00000000..dc1abf34 --- /dev/null +++ b/docs/drools/ctrlog_enablefeature.png diff --git a/docs/drools/ctrlog_logback.png b/docs/drools/ctrlog_logback.png Binary files differnew file mode 100755 index 00000000..252f3fe1 --- /dev/null +++ b/docs/drools/ctrlog_logback.png diff --git a/docs/drools/ctrlog_view.png b/docs/drools/ctrlog_view.png Binary files differnew file mode 100755 index 00000000..118bd64d --- /dev/null +++ b/docs/drools/ctrlog_view.png diff --git a/docs/drools/drools.rst b/docs/drools/drools.rst index 90bd05a5..a7705b0f 100644 --- a/docs/drools/drools.rst +++ b/docs/drools/drools.rst @@ -5,8 +5,10 @@ Policy Drools PDP Engine ------------------------ .. toctree:: - :maxdepth: 1 + :maxdepth: 2 + droolsFeaturesIndex.rst + droolsTutorialsIndex.rst End of Document diff --git a/docs/drools/droolsFeaturesIndex.rst b/docs/drools/droolsFeaturesIndex.rst new file mode 100644 index 00000000..6bff285b --- /dev/null +++ b/docs/drools/droolsFeaturesIndex.rst @@ -0,0 +1,23 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _drools-features-label: + +PDP-D Features +-------------- + +.. toctree:: + :maxdepth: 1 + + feature_activestdbymgmt.rst + feature_controllerlogging.rst + feature_eelf.rst + feature_healthcheck.rst + feature_locking.rst + feature_mdcfilters.rst + feature_pooling.rst + feature_sesspersist.rst + feature_statemgmt.rst + feature_testtransaction.rst + + +End of Document diff --git a/docs/drools/droolsTutorialsIndex.rst b/docs/drools/droolsTutorialsIndex.rst new file mode 100644 index 00000000..fbc915ab --- /dev/null +++ b/docs/drools/droolsTutorialsIndex.rst @@ -0,0 +1,23 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _drools-tutorials-label: + +PDP-D Tutorials +---------------- + +.. toctree:: + :maxdepth: 1 + + clsimulation.rst + guardpdp.rst + modAAIdata.rst + modAmsterTemplate.rst + runningEclipse.rst + tutorial_cl.rst + tutorial_vCPE.rst + tutorial_vDNS.rst + tutorial_vFW.rst + tutorial_VOLTE.rst + + +End of Document diff --git a/docs/drools/feature_activestdbymgmt.rst b/docs/drools/feature_activestdbymgmt.rst new file mode 100644 index 00000000..a7c3fb97 --- /dev/null +++ b/docs/drools/feature_activestdbymgmt.rst @@ -0,0 +1,116 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +********************************** +Feature: Active/Standby Management +********************************** + +.. contents:: + :depth: 3 + +Summary +^^^^^^^ +When the Feature Session Persistence is enabled, there can only be one active/providing service Drools PDP due to the behavior of Drools persistence. The Active/Standby Management Feature controls the selection of the Drools PDP that is providing service. It utilizes its own database and the State Management Feature database in the election algorithm. All Drools PDP nodes periodically run the election algorithm and, since they all use the same data, all nodes come to the same conclusion with the "elected" node assuming an active/providingservice state. Thus, the algorithm is distributed and has no single point of failure - assuming the database is configured for high availability. + +When the algorithm selects a Drools PDP to be active/providing service the controllers and topic endpoints are unlocked and allowed to process transactions. When a Drools PDP transitions to a hotstandby or coldstandby state, the controllers and topic endpoints are locked, preventing the Drools PDP from handling transactions. + + +Usage +^^^^^ + +Enabling and Disabling Feature State Management +----------------------------------------------- + +The Active/Standby Management Feature is enabled from the command line when logged in as policy after configuring the feature properties file (see Description Details section). From the command line: + +- > features status - Lists the status of features +- > features enable active-standby-management - Enables the Active-Standby Management Feature +- > features disable active-standby-management - Disables the Active-Standby Management Feature + +The Drools PDP must be stopped prior to enabling/disabling features and then restarted after the features have been enabled/disabled. + + .. code-block:: bash + :caption: Enabling Active/Standby Management Feature + + policy@hyperion-4:/opt/app/policy$ policy stop + [drools-pdp-controllers] + L []: Stopping Policy Management... Policy Management (pid=354) is stopping... Policy Management has stopped. + policy@hyperion-4:/opt/app/policy$ features enable active-standby-management + name version status + ---- ------- ------ + controlloop-utils 1.1.0-SNAPSHOT disabled + healthcheck 1.1.0-SNAPSHOT disabled + test-transaction 1.1.0-SNAPSHOT disabled + eelf 1.1.0-SNAPSHOT disabled + state-management 1.1.0-SNAPSHOT disabled + active-standby-management 1.1.0-SNAPSHOT enabled + session-persistence 1.1.0-SNAPSHOT disabled + + +Description Details +^^^^^^^^^^^^^^^^^^^ + +Election Algorithm +------------------ + +The election algorithm selects the active/providingservice Drools PDP. The algorithm on each node reads the *standbystatus* from the *StateManagementEntity* table for all other nodes to determine if they are providingservice or in a hotstandby state and able to assume an active status. It uses the *DroolsPdpEntity* table to verify that other node election algorithms are currently functioning and when the other nodes were last designated as the active Drools PDP. + +In general terms, the election algorithm periodically gathers the standbystatus and designation status for all the Drools PDPs. If the node which is currently designated as providingservice is "current" in updating its status, no action is required. If the designated node is either not current or has a standbystatus other than providingservice, it is time to choose another designated *DroolsPDP*. The algorithm will build a list of all DroolsPDPs that are current and have a *standbystatus* of *hotstandby*. It will then give preference to DroolsPDPs within the same site, choosing the DroolsPDP with the lowest lexicographic value to the droolsPdpId (resourceName). If the chosen DroolsPDP is itself, it will promote its standbystatus from hotstandby to providingservice. If the chosen DroolsPDP is other than itself, it will do nothing. + +When the DroolsPDP promotes its *standbystatus* from hotstandby to providing service, a state change notification will occur and the Standby State Change Handler will take appropriate action. + + +Standby State Change Handler +---------------------------- + +The Standby State Change Handler (*PMStandbyStateChangeHandler* class) extends the IntegrityMonitor StateChangeNotifier class which implements the Observer class. When the DroolsPDP is constructed, an instance of the handler is constructed and registered with StateManagement. Whenever StateManagement implements a state transition, it calls the *handleStateChange()* method of the handler. If the StandbyStatus transitions to hot or cold standby, the handler makes a call into the lower level management layer to lock the application controllers and topic endpoints, preventing it from handling transactions. If the StandbyStatus transitions to providingservice, the handler makes a call into the lower level management layer to unlock the application controllers and topic endpoints, allowing it to handle transactions. + + +Database +-------- + +The Active/Standby Feature creates a database named activestandbymanagement with a single table, **droolspdpentity**. The election handler uses that table to determine which DroolsPDP was/is designated as the active DroolsPDP and which DroolsPDP election handlers are healthy enough to periodically update their status. + +The **droolspdpentity** table has the following columns: + - **pdpId** - The unique indentifier for the DroolsPDP. It is the same as the resourceName + - **designated** - Has a value of 1 if the DroolsPDP is designated as active/providingservice. It has a value of 0 otherwise + - **priority** - Indicates the priority level of the DroolsPDP for the election handler. In general, this is ignore and all have the same priority. + - **updatedDate** - This is the timestamp for the most recent update of the record. + - **designatedDate** - This is the timestamp that indicates when the designated column was most recently set to a value of 1 + - **site** - This is the name of the site + +Properties +---------- + +The properties are found in the feature-active-standby-management.properties file. In general, the properties are adequately described in the properties file. Parameters which must be replaced prior to usage are indicated thus: ${{parameter to be replaced}} + + .. code-block:: bash + :caption: feature-active-standby-mangement.properties + + # DB properties + javax.persistence.jdbc.driver=org.mariadb.jdbc.Driver + javax.persistence.jdbc.url=jdbc:mariadb://${{SQL_HOST}}:3306/activestandbymanagement + javax.persistence.jdbc.user=${{SQL_USER}} + javax.persistence.jdbc.password=${{SQL_PASSWORD}} + + # Must be unique across the system + resource.name=pdp1 + # Name of the site in which this node is hosted + site_name=site1 + + # Needed by DroolsPdpsElectionHandler + pdp.checkInterval=1500 # The interval in ms between updates of the updatedDate + pdp.updateInterval=1000 # The interval in ms between executions of the election handler + #pdp.timeout=3000 + # Need long timeout, because testTransaction is only run every 10 seconds. + pdp.timeout=15000 + #how long do we wait for the pdp table to populate on initial startup + pdp.initialWait=20000 + + +End of Document + +.. SSNote: Wiki page ref. https://wiki.onap.org/pages/viewpage.action?pageId=16005790 + + diff --git a/docs/drools/feature_controllerlogging.rst b/docs/drools/feature_controllerlogging.rst new file mode 100644 index 00000000..0677030e --- /dev/null +++ b/docs/drools/feature_controllerlogging.rst @@ -0,0 +1,50 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +*************************** +Feature: Controller Logging +*************************** + +.. contents:: + :depth: 3 + +Summary +^^^^^^^ +The controller logging feature provides a way to log network topic messages to a separate controller log file for each controller. This allows a clear separation of network traffic between all of the controllers. + +Enabling Controller Logging +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Type "features enable controller-logging". The feature will now display as "enabled". + + .. image:: ctrlog_enablefeature.png + +When the feature's enable script is executed, it will search the $POLICY_HOME/config directory for any logback files containing the prefix "logback-include-". These logger configuration files are typically provided with a feature that installs a controlloop (ex: controlloop-amsterdam and controlloop-casablanca features). Once these configuration files are found by the enable script, the logback.xml config file will be updated to include the configurations. + + .. image:: ctrlog_logback.png + + +Controller Logger Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The contents of a logback-include-``*``.xml file follows the same configuration syntax as the logback.xml file. It will contain the configurations for the logger associated with the given controller. + + .. note:: A controller logger MUST be configured with the same name as the controller (ex: a controller named "casablanca" will have a logger named "casablanca"). + + .. image:: ctrlog_config.png + + +Viewing the Controller Logs +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Once a logger for the controller is configured, start the drools-pdp and navigate to the $POLICY_LOGS directory. A new controller specific network log will be added that contains all the network topic traffic of the controller. + + .. image:: ctrlog_view.png + +The original network log remains and will append traffic information from all topics regardless of which controller it is for. To abbreviate and customize messages for the network log, refer to the `Feature MDC Filters <feature_mdcfilters.html>`_ documentation. + + +End of Document + + diff --git a/docs/drools/feature_eelf.rst b/docs/drools/feature_eelf.rst new file mode 100644 index 00000000..7daeb76d --- /dev/null +++ b/docs/drools/feature_eelf.rst @@ -0,0 +1,52 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +************************************************* +Feature: EELF (Event and Error Logging Framework) +************************************************* + +.. contents:: + :depth: 3 + +Summary +^^^^^^^ +The EELF feature provides backwards compatibility with R0 logging functionality. It supports the use of EELF/Common Framework style logging at the same time as traditional logging. + +.. seealso:: Additional information for EELF logging can be found at `EELF wiki`_. + +.. _EELF wiki: https://github.com/att/EELF/wiki + + +Usage +^^^^^ + +To utilize the eelf logging capabilities, first stop policy engine and then enable the feature using the "*features*" command. + + .. code-block:: bash + :caption: Enabling EELF Feature + + policy@hyperion-4:/opt/app/policy$ policy stop + [drools-pdp-controllers] + L []: Stopping Policy Management... Policy Management (pid=354) is stopping... Policy Management has stopped. + policy@hyperion-4:/opt/app/policy$ features enable eelf + name version status + ---- ------- ------ + controlloop-utils 1.1.0-SNAPSHOT disabled + healthcheck 1.1.0-SNAPSHOT disabled + test-transaction 1.1.0-SNAPSHOT disabled + eelf 1.1.0-SNAPSHOT enabled + state-management 1.1.0-SNAPSHOT disabled + active-standby-management 1.1.0-SNAPSHOT disabled + session-persistence 1.1.0-SNAPSHOT disabled + +The output of the enable command will indicate whether or not the feature was enabled successfully. + +Policy engine can then be started as usual. + + + +End of Document + +.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Feature+EELF + diff --git a/docs/drools/feature_healthcheck.rst b/docs/drools/feature_healthcheck.rst new file mode 100644 index 00000000..a0793e92 --- /dev/null +++ b/docs/drools/feature_healthcheck.rst @@ -0,0 +1,117 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +************************* +Feature: Healthcheck +************************* + +.. contents:: + :depth: 3 + +Summary +^^^^^^^ +The Healthcheck feature provides reports used to verify the health of *PolicyEngine.manager* in addition to the construction, operation, and deconstruction of HTTP server/client objects. + +Usage +^^^^^ + +When enabled, the feature takes as input a properties file named "*feature-healtcheck.properties*" (example below). This file should contain configuration properties necessary for the construction of HTTP client and server objects. + +Upon initialization, the feature first constructs HTTP server and client objects using the properties from its properties file. A healthCheck operation is then triggered. The logic of the healthCheck verifies that *PolicyEngine.manager* is alive, and iteratively tests each HTTP server object by sending HTTP GET requests using its respective client object. If a server returns a "200 OK" message, it is marked as "healthy" in its individual report. Any other return code results in an "unhealthy" report. + +After the testing of the server objects has completed, the feature returns a single consolidated report. + + + .. code-block:: bash + :caption: feature-healthcheck.properties + :linenos: + + ### + # ============LICENSE_START======================================================= + # feature-healthcheck + # ================================================================================ + # Copyright (C) 2017 AT&T Intellectual Property. All rights reserved. + # ================================================================================ + # Licensed under the Apache License, Version 2.0 (the "License"); + # you may not use this file except in compliance with the License. + # You may obtain a copy of the License at + # + # http://www.apache.org/licenses/LICENSE-2.0 + # + # Unless required by applicable law or agreed to in writing, software + # distributed under the License is distributed on an "AS IS" BASIS, + # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + # See the License for the specific language governing permissions and + # limitations under the License. + # ============LICENSE_END========================================================= + ### + + http.server.services=HEALTHCHECK + http.server.services.HEALTHCHECK.host=0.0.0.0 + http.server.services.HEALTHCHECK.port=6969 + http.server.services.HEALTHCHECK.restClasses=org.onap.policy.drools.healthcheck.RestHealthCheck + http.server.services.HEALTHCHECK.managed=false + http.server.services.HEALTHCHECK.swagger=true + http.server.services.HEALTHCHECK.userName=healthcheck + http.server.services.HEALTHCHECK.password=zb!XztG34 + + http.client.services=PAP,PDP + + http.client.services.PAP.host=pap + http.client.services.PAP.port=9091 + http.client.services.PAP.contextUriPath=pap/test + http.client.services.PAP.https=false + http.client.services.PAP.userName=testpap + http.client.services.PAP.password=alpha123 + http.client.services.PAP.managed=true + + http.client.services.PDP.host=pdp + http.client.services.PDP.port=8081 + http.client.services.PDP.contextUriPath=pdp/test + http.client.services.PDP.https=false + http.client.services.PDP.userName=testpdp + http.client.services.PDP.password=alpha123 + http.client.services.PDP.managed=false + + +To utilize the healthcheck functionality, first stop policy engine and then enable the feature using the "*features*" command. + + .. code-block:: bash + :caption: Enabling Healthcheck feature + + policy@hyperion-4:/opt/app/policy$ policy stop + [drools-pdp-controllers] + L []: Stopping Policy Management... Policy Management (pid=354) is stopping... Policy Management has stopped. + policy@hyperion-4:/opt/app/policy$ features enable healthcheck + name version status + ---- ------- ------ + controlloop-utils 1.1.0-SNAPSHOT disabled + healthcheck 1.1.0-SNAPSHOT enabled + test-transaction 1.1.0-SNAPSHOT disabled + eelf 1.1.0-SNAPSHOT disabled + state-management 1.1.0-SNAPSHOT disabled + active-standby-management 1.1.0-SNAPSHOT disabled + session-persistence 1.1.0-SNAPSHOT disabled + + +The output of the enable command will indicate whether or not the feature was enabled successfully. + +Policy engine can then be started as usual. + +The Healthcheck can also be invoked manually as follows: + + .. code-block:: bash + :caption: Manual Healthcheck invokation + + + # Assuming the healthcheck service credentials have not been changed + # post-installation within the drools container + + source /opt/app/policy/config/feature-healthcheck.conf.environment + curl -k --silent --user "${HEALTHCHECK_USER}:${HEALTHCHECK_PASSWORD}" -X GET https://localhost:6969/healthcheck | python -m json.tool + + +End of Document + +.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Feature+Healthcheck diff --git a/docs/drools/feature_locking.rst b/docs/drools/feature_locking.rst new file mode 100644 index 00000000..1236c93f --- /dev/null +++ b/docs/drools/feature_locking.rst @@ -0,0 +1,47 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +**************************** +Feature: Distributed Locking +**************************** + +Summary +^^^^^^^ + +The Distributed Locking Feature provides locking of resources across a pool of PDP-D hosts. The list of locks is maintained in a database, where each record includes a resource identifier, an owner identifier, and an expiration time. Typically, a drools application will unlock the resource when it's operation completes. However, if it fails to do so, then the resource will be automatically released when the lock expires, thus preventing a resource from becoming permanently locked. + +Usage +^^^^^ + + .. code-block:: bash + :caption: Enable Feature Distributed Locking + + policy stop + + features enable distributed-locking + + The configuration is located at: + + * $POLICY_HOME/config/feature-distributed-locking.properties + + + .. code-block:: bash + :caption: Start the PDP-D using pooling + + policy start + + + .. code-block:: bash + :caption: Disable the Distributed Locking feature + + policy stop + features disable distributed-locking + policy start + + +End of Document + +.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Feature+Distributed+Locking + + diff --git a/docs/drools/feature_mdcfilters.rst b/docs/drools/feature_mdcfilters.rst new file mode 100644 index 00000000..b0f5543d --- /dev/null +++ b/docs/drools/feature_mdcfilters.rst @@ -0,0 +1,121 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +******************** +Feature: MDC Filters +******************** + +.. contents:: + :depth: 3 + +Summary +^^^^^^^ +The MDC Filter Feature provides configurable properties for network topics to extract fields from JSON strings and place them in a mapped diagnostic context (MDC). + +Network Log Structure Before Feature Enabled +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before enabling the feature, the network log contains the entire content of each message received on a topic. Below is a sample message from the network log. Note that the topic used for this tutorial is DCAE-CL. + + .. code-block:: bash + + [2019-03-22T16:36:42.942+00:00|DMAAP-source-DCAE-CL][IN|DMAAP|DCAE-CL] + {"closedLoopControlName":"ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e","closedLoopAlarmStart":1463679805324,"closedLoopEventClient":"DCAE_INSTANCE_ID.dcae-tca","closedLoopEventStatus":"ONSET","requestID":"664be3d2-6c12-4f4b-a3e7-c349acced200","target_type":"VNF","target":"generic-vnf.vnf-id","AAI":{"vserver.is-closed-loop-disabled":"false","vserver.prov-status":"ACTIVE","generic-vnf.vnf-id":"vCPE_Infrastructure_vGMUX_demo_app"},"from":"DCAE","version":"1.0.2"} + +The network log can become voluminous if messages received from various topics carry large messages for various controllers. With the MDC Filter Feature, users can define keywords in JSON messages to extract and structure according to a desired format. This is done through configuring the feature's properties. + +Configuring the MDC Filter Feature +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To configure the feature, the feature must be enabled using the following command: + + .. code-block:: bash + + features enable mdc-filters + + + .. image:: mdc_enablefeature.png + +Once the feature is enabled, there will be a new properties file in *$POLICY_HOME/config* called **feature-mdc-filters.properties**. + + .. image:: mdc_properties.png + +The properties file contains filters to extract key data from messages on the network topics that are saved in an MDC, which can be referenced in logback.xml. The configuration format is as follows: + + .. code-block:: bash + + <protocol>.<type>.topics.<topic-name>.mdcFilters=<filters> + + Where: + <protocol> = ueb, dmaap, noop + <type> = source, sink + <topic-name> = Name of DMaaP or UEB topic + <filters> = Comma separated list of key/json-path(s) + +The filters consist of an MDC key used by **logback.xml** (see below) and the JSON path(s) to the desired data. The path always begins with '$', which signifies the root of the JSON document. The underlying library, JsonPath, uses a query syntax for searching through a JSON file. The query syntax and some examples can be found at https://github.com/json-path/JsonPath. An example filter for the *DCAE-CL* is provided below: + + .. code-block:: bash + + dmaap.source.topics.DCAE-CL.mdcFilters=requestID=$.requestID + +This filter is specifying that the dmaap source topic *DCAE-CL* will search each message received for requestID by following the path starting at the root ($) and searching for the field *requestID*. If the field is found, it is placed in the MDC with the key "requestID" as signified by the left hand side of the filter before the "=". + + +Configuring Multiple Filters and Paths +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Multiple fields can be found for a given JSON document by a comma separated list of <mdcKey,jsonPath> pairs. For the previous example, another filter is added by adding a comma and specifying the filter as follows: + + .. code-block:: bash + + dmaap.source.topics.DCAE-CL.mdcFilters=requestID=$.requestID,closedLoopName=$.closedLoopControlName + +The feature will now search for both requestID and closedLoopControlName in a JSON message using the specified "$." path notations and put them in the MDC using the keys "requestID" and "closedLoopName" respectively. To further refine the filter, if a topic receives different message structures (ex: a response message structure vs an error message structure) the "|" notation allows multiple paths to a key to be defined. The feature will search through each specified path until a match is found. An example can be found below: + + .. code-block:: bash + + dmaap.source.topics.DCAE-CL.mdcFilters=requestID=$.requestID,closedLoopName=$.closedLoopControlName|$.AAI.closedLoopControlName + +Now when the filter is searching for closedLoopControlName it will check the first path "$.closedLoopControlName", if it is not present then it will try the second path "$.AAI.closedLoopControlName". If the user is unsure of the path to a field, JsonPath supports a deep scan by using the ".." notation. This will search the entire JSON document for the field without specifying the path. + + +Accessing the MDC Values in logback.xml +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Once the feature properties have been defined, logback.xml contains a "abstractNetworkPattern" property that will hold the desired message structure defined by the user. The user has the flexibility to define the message structure however they choose but for this tutorial the following pattern is used: + + .. code-block:: bash + + <property name="abstractNetworkPattern" value="[%d{yyyy-MM-dd'T'HH:mm:ss.SSS+00:00, UTC}] [%X{networkEventType:-NULL}|%X{networkProtocol:-NULL}|%X{networkTopic:-NULL}|%X{requestID:-NULL}|%X{closedLoopName:-NULL}]%n" /> + +The "value" portion consists of two headers in bracket notation, the first header defines the timestamp while the second header references the keys from the MDC filters defined in the feature properties. The standard logback syntax is used and more information on the syntax can be found here. Note that some of the fields here were not defined in the feature properties file. The feature automatically puts the network infrastructure information in the keys that are prepended with "network". The current supported network infrastructure information is listed below. + + +-------------------+-------------------------------------------------+ + | Field | Values | + +===================+=================================================+ + | networkEventType | IN, OUT | + +-------------------+-------------------------------------------------+ + | networkProtocol | DMAAP, UEB, NOOP | + +-------------------+-------------------------------------------------+ + | networkTopic | The name of the topic that received the message | + +-------------------+-------------------------------------------------+ + + +To reference the keys from the feature properties the syntax "%X{KEY_DEFINED_IN_PROPERTIES}" provides access to the value. An optional addition is to append ":-", which specifies a default value to display in the log if the field was not found in the message received. For this tutorial, a default of "NULL" is displayed for any of the fields that were not found while filtering. The "|" has no special meaning and is just used as a field separator for readability; the user can decorate the log format to their desired visual appeal. + +Network Log Structure After Feature Enabled +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Once the feature and logback.xml is configured to the user's desired settings, start the PDP-D by running "policy start". Based on the configurations from the previous sections of this tutorial, the following log message is written to network log when a message is received on the DCAE-CL topic: + + .. code-block:: bash + + [2019-03-22T16:38:23.884+00:00] [IN|DMAAP|DCAE-CL|664be3d2-6c12-4f4b-a3e7-c349acced200|ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e] + +The message has now been filtered to display the network infrastructure information and the extracted data from the JSON message based on the feature properties. In order to view the entire message received from a topic, a complementary feature was developed to display the entire message on a per controller basis while preserving the compact network log. Refer to the `Feature Controller Logging <feature_controllerlogging.html>`_ documentation for details. + + + +End of Document + diff --git a/docs/drools/feature_pooling.rst b/docs/drools/feature_pooling.rst new file mode 100644 index 00000000..f7d3579d --- /dev/null +++ b/docs/drools/feature_pooling.rst @@ -0,0 +1,100 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +**************** +Feature: Pooling +**************** + +Summary +^^^^^^^ + +The Pooling feature provides the ability to load-balance work across a “pool” of active-active Drools-PDP hosts. This particular implementation uses a DMaaP topic for communication between the hosts within the pool. + +The pool is adjusted automatically, with no manual intervention when: + * a new host is brought online + * a host goes offline, whether gracefully or due to a failure in the host or in the network + +Assumptions and Limitations +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + * Session persistence is not required + * Data may be lost when processing is moved from one host to another + * The entire pool may shut down if the inter-host DMaaP topic becomes inaccessible + + .. image:: poolingDesign.png + + +Key Points +^^^^^^^^^^ + * Requests are received on a common DMaaP topic + - DMaaP distributes the requests randomly to the hosts + - The request topic should have at least as many partitions as there are hosts + * Uses a single, internal DMaaP topic for all inter-host communication + * Allocates buckets to each host + - Requests are assigned to buckets based on their respective “request IDs” + * No session persistence + * No objects copied between hosts + * Requires feature(s): distributed-locking + * Precludes feature(s): session-persistence, active-standby, state-management + +Example Scenario +^^^^^^^^^^^^^^^^ + 1. Incoming DMaaP message is received on a topic — all hosts are listening, but only one random host receives the message + 2. Decode message to determine “request ID” key (message-specific operation) + 3. Hash request ID to determine the bucket number + 4. Look up host associated with hash bucket (most likely remote) + 5. Publish “forward” message to internal DMaaP topic, including remote host, bucket number, DMaaP topic information, and message body + 6. Remote host verifies ownership of bucket, and routes the DMaaP message to its own rule engine for processing + + The figure below shows several different hosts in a pool. Each host has a copy of the bucket assignments, which specifies which buckets are assigned to which hosts. Incoming requests are mapped to a bucket, and a bucket is mapped to a host, to which the request is routed. The host table includes an entry for each active host in the pool, to which one or more buckets are mapped. + + .. image:: poolingPdps.png + +Bucket Reassignment +^^^^^^^^^^^^^^^^^^^ + * When a host goes up or down, buckets are rebalanced + * Attempts to maintain an even distribution + * Leaves buckets with their current owner, where possible + * Takes a few buckets from each host to assign to new hosts + + For example, in the diagram below, the left side shows how 32 buckets might be assigned among four different hosts. When the first host fails, the buckets from host 1 would be reassigned among the remaining hosts, similar to what is shown on the right side of the diagram. Any requests that were being processed by host 1 will be lost and must be restarted. However, the buckets that had already been assigned to the remaining hosts are unchanged, thus requests associated with those buckets are not impacted by the loss of host 1. + + .. image:: poolingBuckets.png + +Usage +^^^^^ + +For pooling to be enabled, the distributed-locking feature must be also be enabled. + + .. code-block:: bash + :caption: Enable Feature Pooling + + policy stop + + features enable distributed-locking + features enable pooling-dmaap + + The configuration is located at: + + * $POLICY_HOME/config/feature-pooling-dmaap.properties + + + .. code-block:: bash + :caption: Start the PDP-D using pooling + + policy start + + + .. code-block:: bash + :caption: Disable the pooling feature + + policy stop + features disable pooling-dmaap + policy start + + +End of Document + +.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Feature+Pooling + + diff --git a/docs/drools/feature_sesspersist.rst b/docs/drools/feature_sesspersist.rst new file mode 100644 index 00000000..4bb5ef62 --- /dev/null +++ b/docs/drools/feature_sesspersist.rst @@ -0,0 +1,49 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +************************************ +Feature: Session Persistence +************************************ + +The session persistence feature allows drools kie sessions to be persisted in a database surviving pdp-d restarts. + + .. code-block:: bash + :caption: Enable session persistence + :linenos: + + policy stop + features enable session-persistence + +The configuration is located at: + + - *$POLICY_HOME/config/feature-session-persistence.properties* + +Each controller that wants to be started with persistence should contain the following line in its *<controller-name>-controller.properties* + + - *persistence.type=auto* + + .. code-block:: bash + :caption: Start the PDP-D using session-persistence + :linenos: + + db-migrator -o upgrade -s ALL + policy start + +Facts will survive PDP-D restart using the native drools capabilities and introduce a performance overhead. + + .. code-block:: bash + :caption: Disable the session-persistence feature + :linenos: + + policy stop + features disable session-persistence + sed -i "/persistence.type=auto/d" <controller-name>-controller.properties + db-migrator -o erase -s sessionpersistence # delete all its database data (optional) + policy start + +End of Document + +.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Feature+Session+Persistence + + diff --git a/docs/drools/feature_statemgmt.rst b/docs/drools/feature_statemgmt.rst new file mode 100644 index 00000000..960ff396 --- /dev/null +++ b/docs/drools/feature_statemgmt.rst @@ -0,0 +1,313 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +************************* +Feature: State Management +************************* + +.. contents:: + :depth: 2 + +Summary +^^^^^^^ +The State Management Feature provides: + +- Node-level health monitoring +- Monitoring the health of dependency nodes - nodes on which a particular node is dependent +- Ability to lock/unlock a node and suspend or resume all application processing +- Ability to suspend application processing on a node that is disabled or in a standby state +- Interworking/Coordination of state values +- Support for ITU X.731 states and state transitions for: + - Administrative State + - Operational State + - Availability Status + - Standby Status + +Usage +^^^^^ + +Enabling and Disabling Feature State Management +----------------------------------------------- + +The State Management Feature is enabled from the command line when logged in as policy after configuring the feature properties file (see Description Details section). From the command line: + +- > features status - Lists the status of features +- > features enable state-management - Enables the State Management Feature +- > features disable state-management - Disables the State Management Feature + +The Drools PDP must be stopped prior to enabling/disabling features and then restarted after the features have been enabled/disabled. + + .. code-block:: bash + :caption: Enabling State Management Feature + + policy@hyperion-4:/opt/app/policy$ policy stop + [drools-pdp-controllers] + L []: Stopping Policy Management... Policy Management (pid=354) is stopping... Policy Management has stopped. + policy@hyperion-4:/opt/app/policy$ features enable state-management + name version status + ---- ------- ------ + controlloop-utils 1.1.0-SNAPSHOT disabled + healthcheck 1.1.0-SNAPSHOT disabled + test-transaction 1.1.0-SNAPSHOT disabled + eelf 1.1.0-SNAPSHOT disabled + state-management 1.1.0-SNAPSHOT enabled + active-standby-management 1.1.0-SNAPSHOT disabled + session-persistence 1.1.0-SNAPSHOT disabled + +Description Details +^^^^^^^^^^^^^^^^^^^ + +State Model +----------- + +The state model follows the ITU X.731 standard for state management. The supported state values are: + **Administrative State:** + - Locked - All application transaction processing is prohibited + - Unlocked - Application transaction processing is allowed + + **Administrative State Transitions:** + - The transition from Unlocked to Locked state is triggered with a Lock operation + - The transition from the Locked to Unlocked state is triggered with an Unlock operation + + **Operational State:** + - Enabled - The node is healthy and able to process application transactions + - Disabled - The node is not healthy and not able to process application transactions + + **Operational State Transitions:** + - The transition from Enabled to Disabled is triggered with a disableFailed or disableDependency operation + - The transition from Disabled to Enabled is triggered with an enableNotFailed and enableNoDependency operation + + **Availability Status:** + - Null - The Operational State is Enabled + - Failed - The Operational State is Disabled because the node is no longer healthy + - Dependency - The Operational State is Disabled because all members of a dependency group are disabled + - Dependency.Failed - The Operational State is Disabled because the node is no longer healthy and all members of a dependency group are disabled + + **Availability Status Transitions:** + - The transition from Null to Failed is triggered with a disableFailed operation + - The transtion from Null to Dependency is triggered with a disableDependency operation + - The transition from Failed to Dependency.Failed is triggered with a disableDependency operation + - The transition from Dependency to Dependency.Failed is triggered with a disableFailed operation + - The transition from Dependency.Failed to Failed is triggered with an enableNoDependency operation + - The transition from Dependency.Failed to Dependency is triggered with an enableNotFailed operation + - The transition from Failed to Null is triggered with an enableNotFailed operation + - The transition from Dependency to Null is triggered with an enableNoDependency operation + + **Standby Status:** + - Null - The node does not support active-standby behavior + - ProvidingService - The node is actively providing application transaction service + - HotStandby - The node is capable of providing application transaction service, but is currently waiting to be promoted + - ColdStandby - The node is not capable of providing application service because of a failure + + **Standby Status Transitions:** + - The transition from Null to HotStandby is triggered by a demote operation when the Operational State is Enabled + - The transition for Null to ColdStandby is triggered is a demote operation when the Operational State is Disabled + - The transition from ColdStandby to HotStandby is triggered by a transition of the Operational State from Disabled to Enabled + - The transition from HotStandby to ColdStandby is triggered by a transition of the Operational State from Enabled to Disabled + - The transition from ProvidingService to ColdStandby is triggered by a transition of the Operational State from Enabled to Disabled + - The transition from HotStandby to ProvidingService is triggered by a Promote operation + - The transition from ProvidingService to HotStandby is triggered by a Demote operation + +Database +-------- + +The State Management feature creates a StateManagement database having three tables: + + **StateManagementEntity** - This table has the following columns: + - **id** - Automatically created unique identifier + - **resourceName** - The unique identifier for a node + - **adminState** - The Administrative State + - **opState** - The Operational State + - **availStatus** - The Availability Status + - **standbyStatus** - The Standby Status + - **created_Date** - The timestamp the resource entry was created + - **modifiedDate** - The timestamp the resource entry was last modified + + **ForwardProgressEntity** - This table has the following columns: + - **forwardProgressId** - Automatically created unique identifier + - **resourceName** - The unique identifier for a node + - **fpc_count** - A forward progress counter which is periodically incremented if the node is healthy + - **created_date** - The timestamp the resource entry was created + - **last_updated** - The timestamp the resource entry was last updated + + **ResourceRegistrationEntity** - This table has the following columns: + - **ResourceRegistrationId** - Automatically created unique identifier + - **resourceName** - The unique identifier for a node + - **resourceUrl** - The JMX URL used to check the health of a node + - **site** - The name of the site in which the resource resides + - **nodeType** - The type of the node (i.e, pdp_xacml, pdp_drools, pap, pap_admin, logparser, brms_gateway, astra_gateway, elk_server, pypdp) + - **created_date** - The timestamp the resource entry was created + - **last_updated** - The timestamp the resource entry was last updated + +Node Health Monitoring +---------------------- + +**Application Monitoring** + + Application monitoring can be implemented using the *startTransaction()* and *endTransaction()* methods. Whenever a transaction is started, the *startTransaction()* method is called. If the node is locked, disabled or in a hot/cold standby state, the method will throw an exception. Otherwise, it resets the timer which triggers the default *testTransaction()* method. + + When a transaction completes, calling *endTransaction()* increments the forward process counter in the *ForwardProgressEntity* DB table. As long as this counter is updating, the integrity monitor will assume the node is healthy/sane. + + If the *startTransaction()* method is not called within a provisioned period of time, a timer will expire which calls the *testTransaction()* method. The default implementation of this method simply increments the forward progress counter. The *testTransaction()* method may be overwritten to perform a more meaningful test of system sanity, if desired. + + If the forward progress counter stops incrementing, the integrity monitoring routine will assume the node application has lost sanity and it will trigger a *statechange* (disableFailed) to cause the operational state to become disabled and the availability status attribute to become failed. Once the forward progress counter again begins incrementing, the operational state will return to enabled. + +**Application Monitoring with AllSeemsWell** + + The IntegrityMonitor class provides a facility for applications to directly control updates of the forwardprogressentity table. As previously described, *startTransaction()* and *endTransaction()* are provided to monitor the forward progress of transactions. This, however, does not monitor things such as internal threads that may be blocked or die. An example is the feature-state-management *DroolsPdpElectionHandler.run()* method. + + The *run()* method is monitored by a timer task, *checkWaitTimer()*. If the *run()* method is stalled an extended period of time, the *checkWaitTimer()* method will call *StateManagementFeature.allSeemsWell(<className>, <AllSeemsWell State>, <String message>)* with the AllSeemsWell state of Boolean.FALSE. + + The IntegrityMonitor instance owned by StateManagementFeature will then store an entry in the allSeemsWellMap and block updates of the forwardprogressentity table. This in turn, will cause the Drools PDP operational state to be set to “disabled” and availability status to be set to “failed”. + + Once the blocking condition is cleared, the *checkWaiTimer()* will again call the *allSeemsWell()* method and include an AllSeemsWell state of Boolean.True. This will cause the IntegrityMonitor to remove the entry for that className from the allSeemsWellMap and allow updating of the forwardprogressentity table, so long as there are no other entries in the map. + +**Dependency Monitoring** + + When a Drools PDP (or other node using the *IntegrityMonitor* policy/common module) is dependent upon other nodes to perform its function, those other nodes can be defined as dependencies in the properties file. In order for the dependency algorithm to function, the other nodes must also be running the *IntegrityMonitor*. Periodically the Drools PDP will check the state of dependencies. If all of a node type have failed, the Drools PDP will declare that it can no longer function and change the operational state to disabled and the availability status to dependency. + + In addition to other policy node types, there is a *subsystemTest()* method that is periodically called by the *IntegrityMonitor*. In Drools PDP, *subsystemTest* has been overwritten to execute an audit of the Database and of the Maven Repository. If the audit is unable to verify the function of either the DB or the Maven Repository, he Drools PDP will declare that it can no longer function and change the operational state to disabled and the availability status to dependency. + + When a failed dependency returns to normal operation, the *IntegrityMontor* will change the operational state to enabled and availability status to null. + +**External Health Monitoring Interface** + + The Drools PDP has a http test interface which, when called, will return 200 if all seems well and 500 otherwise. The test interface URL is defined in the properties file. + + +Site Manager +------------ + +The Site Manager is not deployed with the Drools PDP, but it is available in the policy/common repository in the site-manager directory. +The Site Manager provides a lock/unlock interface for nodes and a way to display node information and status. + +The following is from the README file included with the Site Manager. + + .. code-block:: bash + :caption: Site Manager README extract + + Before using 'siteManager', the file 'siteManager.properties' needs to be + edited to configure the parameters used to access the database: + + javax.persistence.jdbc.driver - typically 'org.mariadb.jdbc.Driver' + + javax.persistence.jdbc.url - URL referring to the database, + which typically has the form: 'jdbc:mariadb://<host>:<port>/<db>' + ('<db>' is probably 'xacml' in this case) + + javax.persistence.jdbc.user - the user id for accessing the database + + javax.persistence.jdbc.password - password for accessing the database + + Once the properties file has been updated, the 'siteManager' script can be + invoked as follows: + + siteManager show [ -s <site> | -r <resourceName> ] : + display node information (Site, NodeType, ResourceName, AdminState, + OpState, AvailStatus, StandbyStatus) + + siteManager setAdminState { -s <site> | -r <resourceName> } <new-state> : + update admin state on selected nodes + + siteManager lock { -s <site> | -r <resourceName> } : + lock selected nodes + + siteManager unlock { -s <site> | -r <resourceName> } : + unlock selected nodes + +Note that the 'siteManager' script assumes that the script, +'site-manager-${project.version}.jar' file and 'siteManager.properties' file +are all in the same directory. If the files are separated, the 'siteManager' +script will need to be modified so it can locate the jar and properties files. + + +Properties +---------- + +The feature-state-mangement.properties file controls the function of the State Management Feature. In general, the properties have adequate descriptions in the file. Parameters which must be replaced prior to usage are indicated thus: ${{parameter to be replaced}}. + + .. code-block:: bash + :caption: feature-state-mangement.properties + + # DB properties + javax.persistence.jdbc.driver=org.mariadb.jdbc.Driver + javax.persistence.jdbc.url=jdbc:mariadb://${{SQL_HOST}}:3306/statemanagement + javax.persistence.jdbc.user=${{SQL_USER}} + javax.persistence.jdbc.password=${{SQL_PASSWORD}} + + # DroolsPDPIntegrityMonitor Properties + # Test interface host and port defaults may be overwritten here + http.server.services.TEST.host=0.0.0.0 + http.server.services.TEST.port=9981 + #These properties will default to the following if no other values are provided: + # http.server.services.TEST.restClasses=org.onap.policy.drools.statemanagement.IntegrityMonitorRestManager + # http.server.services.TEST.managed=false + # http.server.services.TEST.swagger=true + + #IntegrityMonitor Properties + + # Must be unique across the system + resource.name=pdp1 + # Name of the site in which this node is hosted + site_name=site1 + # Forward Progress Monitor update interval seconds + fp_monitor_interval=30 + # Failed counter threshold before failover + failed_counter_threshold=3 + # Interval between test transactions when no traffic seconds + test_trans_interval=10 + # Interval between writes of the FPC to the DB seconds + write_fpc_interval=5 + # Node type Note: Make sure you don't leave any trailing spaces, or you'll get an 'invalid node type' error! + node_type=pdp_drools + # Dependency groups are groups of resources upon which a node operational state is dependent upon. + # Each group is a comma-separated list of resource names and groups are separated by a semicolon. For example: + # dependency_groups=site_1.astra_1,site_1.astra_2;site_1.brms_1,site_1.brms_2;site_1.logparser_1;site_1.pypdp_1 + dependency_groups= + # When set to true, dependent health checks are performed by using JMX to invoke test() on the dependent. + # The default false is to use state checks for health. + test_via_jmx=true + # This is the max number of seconds beyond which a non incrementing FPC is considered a failure + max_fpc_update_interval=120 + # Run the state audit every 60 seconds (60000 ms). The state audit finds stale DB entries in the + # forwardprogressentity table and marks the node as disabled/failed in the statemanagemententity + # table. NOTE! It will only run on nodes that have a standbystatus = providingservice. + # A value of <= 0 will turn off the state audit. + state_audit_interval_ms=60000 + # The refresh state audit is run every (default) 10 minutes (600000 ms) to clean up any state corruption in the + # DB statemanagemententity table. It only refreshes the DB state entry for the local node. That is, it does not + # refresh the state of any other nodes. A value <= 0 will turn the audit off. Any other value will override + # the default of 600000 ms. + refresh_state_audit_interval_ms=600000 + + + # Repository audit properties + # Assume it's the releaseRepository that needs to be audited, + # because that's the one BRMGW will publish to. + repository.audit.id=${{releaseRepositoryID}} + repository.audit.url=${{releaseRepositoryUrl}} + repository.audit.username=${{repositoryUsername}} + repository.audit.password=${{repositoryPassword}} + repository2.audit.id=${{releaseRepository2ID}} + repository2.audit.url=${{releaseRepository2Url}} + repository2.audit.username=${{repositoryUsername2}} + repository2.audit.password=${{repositoryPassword2}} + + # Repository Audit Properties + # Flag to control the execution of the subsystemTest for the Nexus Maven repository + repository.audit.is.active=false + repository.audit.ignore.errors=true + repository.audit.interval_sec=86400 + repository.audit.failure.threshold=3 + + # DB Audit Properties + # Flag to control the execution of the subsystemTest for the Database + db.audit.is.active=false + + +End of Document + +.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Feature+State+Management + + diff --git a/docs/drools/feature_testtransaction.rst b/docs/drools/feature_testtransaction.rst new file mode 100644 index 00000000..488ee1a5 --- /dev/null +++ b/docs/drools/feature_testtransaction.rst @@ -0,0 +1,106 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +************************* +Feature: Test Transaction +************************* + +.. contents:: + :depth: 3 + +Summary +^^^^^^^ + +The Test Transaction feature provides a mechanism by which the health of drools policy controllers can be tested. + +When enabled, the feature functions by injecting an event object (identified by a UUID) into the drools session of each policy controller that is active in the system. Only an object with this UUID can trigger the Test Transaction-specific drools logic to execute. + +The injection of the event triggers the "TT" rule (see *TestTransactionTemplate.drl* below) to fire. The "TT" rule simply increments a ForwardProgress counter object, thereby confirming that the drools session for this particular controller is active and firing its rules accordingly. This cycle repeats at 20 second intervals. + +If it is ever the case that a drools controller does not have the "TT" rule present in its *.drl*, or that the forward progress counter is not incremented, the Test Transaction thread for that particular drools session (i.e. controller) is terminated and a message is logged to *error.log*. + +Usage +^^^^^ + +Prior to being enabled, the following drools rules need to be appended to the rules templates of any use-case that is to be monitored by the feature. + + .. code-block:: java + :caption: TestTransactionTemplate.drl + :linenos: + + /* + * ============LICENSE_START======================================================= + * feature-test-transaction + * ================================================================================ + * Copyright (C) 2017 AT&T Intellectual Property. All rights reserved. + * ================================================================================ + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * ============LICENSE_END========================================================= + */ + + package org.onap.policy.drools.rules; + + import java.util.EventObject; + + declare ForwardProgress + counter : Long + end + + rule "TT.SETUP" + when + then + ForwardProgress fp = new ForwardProgress(); + fp.setCounter(0L); + insert(fp); + end + + rule "TT" + when + $fp : ForwardProgress() + $tt : EventObject(source == "43868e59-d1f3-43c2-bd6f-86f89a61eea5") + then + $fp.setCounter($fp.getCounter() + 1); + retract($tt); + end + query "TT.FPC" + ForwardProgress(counter >= 0, $ttc : counter) + end + +Once the proper artifacts are built and deployed with the addition of the TestTransactionTemplate rules, the feature can then be enabled by entering the following commands: + + .. code-block:: bash + :caption: PDPD Features Command + + policy@hyperion-4:/opt/app/policy$ policy stop + [drools-pdp-controllers] + L []: Stopping Policy Management... Policy Management (pid=354) is stopping... Policy Management has stopped. + policy@hyperion-4:/opt/app/policy$ features enable test-transaction + name version status + ---- ------- ------ + controlloop-utils 1.1.0-SNAPSHOT disabled + healthcheck 1.1.0-SNAPSHOT disabled + test-transaction 1.1.0-SNAPSHOT enabled + eelf 1.1.0-SNAPSHOT disabled + state-management 1.1.0-SNAPSHOT disabled + active-standby-management 1.1.0-SNAPSHOT disabled + session-persistence 1.1.0-SNAPSHOT disabled + +The output of the enable command will indicate whether or not the feature was enabled successfully. + +Policy engine can then be started as usual. + + +End of Document + +.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Feature+Test+Transaction diff --git a/docs/drools/guardpdp.rst b/docs/drools/guardpdp.rst new file mode 100644 index 00000000..797557fc --- /dev/null +++ b/docs/drools/guardpdp.rst @@ -0,0 +1,153 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +************************ +Using guard in the PDP-D +************************ + +.. contents:: + :depth: 2 + +This guide will help configure and test guard connection from PDP-D to PDP-X. This guide assumes that the PDP-D is installed and running policy properly with other properties being set properly. + +Configuration +^^^^^^^^^^^^^ + +Prerequisites +------------- + +Stop Policy, open, and verify the config: + +- Stop policy with *policy stop* +- Open *$POLICY_HOME/config/controlloop.properties.environment* +- Make sure the *sql.db.host*, *sql.db.username* and *sql.db.password* are set correctly + + +Guard Properties +---------------- + +**guard.url** - URL endpoint of the PDP-X which will receive the request. + - For example, *http://pdp:8081/pdp/api/getDecision* will connect to the localhost PDP-X. + - This request requires some configuration for PDP-X properties below. + - For testing this URL before running policy, see Verification below. + +**guard.jdbc.url** - URL of the database location to which the operations history will be written. + - For example, *jdbc:mariadb://mariadb:3306/onap_sdk*. + - Note that the port is included. + - Note that at the end, the database name is used. + +**guard.disabled** - For enabling / disabling guard functionality. + - For example, to enable set it to false. + - When this is set to true, the previous two properties will be ignored. + - If guard is enabled, then the following PDP-X properties must also be set. + + +PDP-X Properties +---------------- + +For testing these properties before running policy, see Verification below. + +**pdpx.host** - URL of the PDP-X + - For example, pdp can be used when PDP-X is on localhost. + +**pdpx.username** - User to authenticate + +**pdpx.password** - User Password + +**pdpx.environment** - Environment making requests + - For example, TEST + +**pdpx.client.username** - Client to authenticate + +**pdpx.client.password** - Client password + + + +Verification +^^^^^^^^^^^^ + +It is recommended to test using CLI tools before running since changing bash command parameters are faster than restarting policy. + +Logs Verification +----------------- +Checking the logs is straight forward. Check the *$POLICY_HOME/logs/error.log* file for the word "*callRESTfulPDP*" for any exceptions thrown. If they are thrown then there was a problem with the connection. +You can also check the *$POLICY_HOME/logs/network.log* file for the word "*Indeterminate*" which implies the connection failed or got a non 200 response code. + +CLI Verification +---------------- + +It can be helpful to test the PDP-X connection using bash commands to make sure that the PDP-X properties are correct and the guard.url property is correct before running policy. + +**Method 1: httpie - CLI, cURL-like tool for humans** + + Using the http command we can make a request directly to PDP-X from the command line. Use the following form: + + .. code-block:: bash + + http + POST pdp:8081/pdp/api/getDecision + Authorization:<yourAuth> ClientAuth:<yourClientAuth> + Environment:<environment> Content-Type:application/json < guard_request.json + + | where: + | *<yourAuth>* is the string generated from user:pass converted to base64 encoding + | (a conversion tool is available at https://www.base64encode.org/) + | *<yourClientAuth>* is generated the same way but from the client user and pass. + | *<environment>* is the context of the request. For example: TEST + | *pdp* is the host of the PDP-X + + + The guard_request.json should be in the form of the following: + + .. code-block:: json + :caption: guard_request.json + + { + "decisionAttributes": { + "actor": "APPC", + "recipe": "Restart", + "target": "test13", + "clname" : "piptest" + }, + "onapName": "PDPD" + } + + * This request uses Basic Access Authentication. + * This request will need further configuration if you are using a proxy. + + + You know a successful connection is set when a response containing a “PERMIT” or “DENY” in uppercase is returned as follows: + + .. code-block:: json + :caption: Response + + { + "decision": "PERMIT", + "details": "Decision Permit. OK!" + } + +**Method 2: curl** + + This method does the same as the http command but uses the alternate command of curl. The command should have the following form: + + .. code-block:: bash + + curl -u <user>:<pass> -H "Content-Type: application/json" -H "ClientAuth:<yourClientAuth>" + -H "Environment:<environment>" -X POST -d @guard_req.json pdp:8081/pdp/api/getDecision + + * Note that <user> and <pass> are in plain text, while the other headers follow the same form as in Method 1 above. + * This request will need further configuration if you are using a proxy + * The response is the same as in Method 1. + + +**Note on Proxies** + + * JVM system properties should be set if a proxy is being used to make the connection work with policy. + * The connection may succeed but have response code 401 or 403 with improper proxy authentication, which leads to "Indeterminate" + * Additionally, the CLI tools have specific proxy configuration. See their respective manual pages for more info. + + +End of Document + +.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Using+guard+in+the+PDP-D diff --git a/docs/drools/mat_add_local_catalog.JPG b/docs/drools/mat_add_local_catalog.JPG Binary files differnew file mode 100755 index 00000000..e71dcc54 --- /dev/null +++ b/docs/drools/mat_add_local_catalog.JPG diff --git a/docs/drools/mat_amsterdam_controller.JPG b/docs/drools/mat_amsterdam_controller.JPG Binary files differnew file mode 100755 index 00000000..c095082a --- /dev/null +++ b/docs/drools/mat_amsterdam_controller.JPG diff --git a/docs/drools/mat_amsterdam_drl.JPG b/docs/drools/mat_amsterdam_drl.JPG Binary files differnew file mode 100755 index 00000000..01b0126c --- /dev/null +++ b/docs/drools/mat_amsterdam_drl.JPG diff --git a/docs/drools/mat_amsterdam_project.JPG b/docs/drools/mat_amsterdam_project.JPG Binary files differnew file mode 100755 index 00000000..4a494065 --- /dev/null +++ b/docs/drools/mat_amsterdam_project.JPG diff --git a/docs/drools/mat_archetype_checkparams.png b/docs/drools/mat_archetype_checkparams.png Binary files differnew file mode 100755 index 00000000..88b67443 --- /dev/null +++ b/docs/drools/mat_archetype_checkparams.png diff --git a/docs/drools/mat_archetype_params.JPG b/docs/drools/mat_archetype_params.JPG Binary files differnew file mode 100755 index 00000000..bca06360 --- /dev/null +++ b/docs/drools/mat_archetype_params.JPG diff --git a/docs/drools/mat_archetypes.JPG b/docs/drools/mat_archetypes.JPG Binary files differnew file mode 100755 index 00000000..87ee3ce4 --- /dev/null +++ b/docs/drools/mat_archetypes.JPG diff --git a/docs/drools/mat_build_success.JPG b/docs/drools/mat_build_success.JPG Binary files differnew file mode 100755 index 00000000..cd2c2988 --- /dev/null +++ b/docs/drools/mat_build_success.JPG diff --git a/docs/drools/mat_clean_install.JPG b/docs/drools/mat_clean_install.JPG Binary files differnew file mode 100755 index 00000000..0a2a5c81 --- /dev/null +++ b/docs/drools/mat_clean_install.JPG diff --git a/docs/drools/mat_configure.JPG b/docs/drools/mat_configure.JPG Binary files differnew file mode 100755 index 00000000..0965e679 --- /dev/null +++ b/docs/drools/mat_configure.JPG diff --git a/docs/drools/mat_console_output.JPG b/docs/drools/mat_console_output.JPG Binary files differnew file mode 100755 index 00000000..23689fa9 --- /dev/null +++ b/docs/drools/mat_console_output.JPG diff --git a/docs/drools/mat_error.JPG b/docs/drools/mat_error.JPG Binary files differnew file mode 100755 index 00000000..565266f6 --- /dev/null +++ b/docs/drools/mat_error.JPG diff --git a/docs/drools/mat_hello_world.JPG b/docs/drools/mat_hello_world.JPG Binary files differnew file mode 100755 index 00000000..d52e4c75 --- /dev/null +++ b/docs/drools/mat_hello_world.JPG diff --git a/docs/drools/mat_local_archetypes.png b/docs/drools/mat_local_archetypes.png Binary files differnew file mode 100755 index 00000000..2172e636 --- /dev/null +++ b/docs/drools/mat_local_archetypes.png diff --git a/docs/drools/mat_maven_build.JPG b/docs/drools/mat_maven_build.JPG Binary files differnew file mode 100755 index 00000000..2752a633 --- /dev/null +++ b/docs/drools/mat_maven_build.JPG diff --git a/docs/drools/mat_maven_project.JPG b/docs/drools/mat_maven_project.JPG Binary files differnew file mode 100755 index 00000000..3d8efe38 --- /dev/null +++ b/docs/drools/mat_maven_project.JPG diff --git a/docs/drools/mat_new_project.JPG b/docs/drools/mat_new_project.JPG Binary files differnew file mode 100755 index 00000000..2deed0d8 --- /dev/null +++ b/docs/drools/mat_new_project.JPG diff --git a/docs/drools/mat_nexus_catalog.JPG b/docs/drools/mat_nexus_catalog.JPG Binary files differnew file mode 100755 index 00000000..4240eaa3 --- /dev/null +++ b/docs/drools/mat_nexus_catalog.JPG diff --git a/docs/drools/mat_nexus_local_catalog.png b/docs/drools/mat_nexus_local_catalog.png Binary files differnew file mode 100755 index 00000000..b12533e8 --- /dev/null +++ b/docs/drools/mat_nexus_local_catalog.png diff --git a/docs/drools/mat_project_location.JPG b/docs/drools/mat_project_location.JPG Binary files differnew file mode 100755 index 00000000..34c3cb93 --- /dev/null +++ b/docs/drools/mat_project_location.JPG diff --git a/docs/drools/mat_run_as.JPG b/docs/drools/mat_run_as.JPG Binary files differnew file mode 100755 index 00000000..d4401b11 --- /dev/null +++ b/docs/drools/mat_run_as.JPG diff --git a/docs/drools/mat_select_archetypes.png b/docs/drools/mat_select_archetypes.png Binary files differnew file mode 100755 index 00000000..07991c49 --- /dev/null +++ b/docs/drools/mat_select_archetypes.png diff --git a/docs/drools/mdc_enablefeature.png b/docs/drools/mdc_enablefeature.png Binary files differnew file mode 100755 index 00000000..26ae55a4 --- /dev/null +++ b/docs/drools/mdc_enablefeature.png diff --git a/docs/drools/mdc_properties.png b/docs/drools/mdc_properties.png Binary files differnew file mode 100755 index 00000000..63cea92e --- /dev/null +++ b/docs/drools/mdc_properties.png diff --git a/docs/drools/modAAI_getAllVserver.PNG b/docs/drools/modAAI_getAllVserver.PNG Binary files differnew file mode 100755 index 00000000..611992f4 --- /dev/null +++ b/docs/drools/modAAI_getAllVserver.PNG diff --git a/docs/drools/modAAI_getByVserverName.PNG b/docs/drools/modAAI_getByVserverName.PNG Binary files differnew file mode 100755 index 00000000..7670ff89 --- /dev/null +++ b/docs/drools/modAAI_getByVserverName.PNG diff --git a/docs/drools/modAAI_getCloudRegions.png b/docs/drools/modAAI_getCloudRegions.png Binary files differnew file mode 100755 index 00000000..82fb659c --- /dev/null +++ b/docs/drools/modAAI_getCloudRegions.png diff --git a/docs/drools/modAAI_namedQueryVnfId.PNG b/docs/drools/modAAI_namedQueryVnfId.PNG Binary files differnew file mode 100755 index 00000000..14ca3121 --- /dev/null +++ b/docs/drools/modAAI_namedQueryVnfId.PNG diff --git a/docs/drools/modAAIdata.rst b/docs/drools/modAAIdata.rst new file mode 100644 index 00000000..220d38f4 --- /dev/null +++ b/docs/drools/modAAIdata.rst @@ -0,0 +1,124 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +**************************** +Verifying/Modifying AAI Data +**************************** + +.. contents:: + :depth: 2 + +This page highlights key commands used by Policy to look at and modify A&AI data for testing purposes. Please refer to the A&AI REST API Documentation for more details. + +Checking Current Data +^^^^^^^^^^^^^^^^^^^^^ + +To get all the vnfs that are in AAI +----------------------------------- + +Use this command if you want to get all the vnf's that are provisioned in A&AI. This is useful if you want to find a couple vnf's you can later query. + + .. code-block:: bash + + curl --silent -k -u "<userName>:<password>" --header "X-FromAppId: <fromApp>" --header "Content-Type: application/json" --header "Accept: application/json" --header "X-TransactionId: <requestID>" -X GET https://aai.api.simpledemo.openecomp.org:8443/aai/v11/network/generic-vnfs | python -m json.tool + +To get a specific vnf +--------------------- + +If you have a **vnf-id**, this command returns the details related to the specific vnf id you are querying. Policy primarily does this query if the onset has a vnf id but not the isClosedLoopDisabled field. + + .. code-block:: bash + + curl --silent -k -u "<userName>:<password>" --header "X-FromAppId: <fromApp>" --header "Content-Type: application/json" --header "Accept: application/json" --header "X-TransactionId: <requestID>" -X GET https://aai.api.simpledemo.openecomp.org:8443/aai/v11/network/generic-vnfs/generic-vnf/<vnfID> | python -m json.tool + +If you have a **vnf-name**, this command returns the details related to the specific vnf name you are querying. Policy primarily does this query if the onset has a vnf name but no vnf id. + + .. code-block:: bash + + curl --silent -k -u "<userName>:<password>" --header "X-FromAppId: <fromApp>" --header "Content-Type: application/json" --header "Accept: application/json" --header "X-TransactionId: <requestID>" -X GET https://aai.api.simpledemo.openecomp.org:8443/aai/v11/network/generic-vnfs/generic-vnf?vnf-name=<vnfName> | python -m json.tool + +To find all the vservers +------------------------ + +Follow these steps to get all of the vservers. This is useful to get a couple of vservers to query later, either manually or through a closed loop. + +**Step 1:** Execute the following: + + .. code-block:: bash + + curl --silent -k -u "<userName>:<password>" --header "X-FromAppId: <fromApp>" --header "Content-Type: application/json" --header "Accept: application/json" --header "X-TransactionId: <requestID>" -X GET https://aai.api.simpledemo.openecomp.org:8443/aai/v11/cloud-infrastructure/cloud-regions | python -m json.tool + + Take note of all the cloud-owner/cloud-region combinations. In this example, there are 3 combinations: Skynet/CL-MR1, AMIST/AMCR1, and Rackspace/DFW. + + .. image:: modAAI_getCloudRegions.png + +**Step 2:** Invoke the following command for each combination: + + .. code-block:: bash + + curl --silent -k -u "<userName>:<password>" --header "X-FromAppId: <fromApp>" --header "Content-Type: application/json" --header "Accept: application/json" --header "X-TransactionId: <requestID>" -X GET https://aai.api.simpledemo.openecomp.org:8443/aai/v11/cloud-infrastructure/cloud-regions/cloud-region/<cloudOwner>/<cloudRegion>?depth=all | python -m json.tool + + .. image:: modAAI_getAllVserver.PNG + +To get a specific vserver +------------------------- + +Use this command to get the details of a specific vserver based on its vserver name. + + .. code-block:: bash + + curl --silent -k -u "<userName>:<password>" --header "X-FromAppId: <fromApp>" --header "Content-Type: application/json" --header "Accept: application/json" --header "X-TransactionId: <requestID>" -X GET https://aai.api.simpledemo.openecomp.org:8443/aai/v11/nodes/vservers?vserver-name=<vserverName> | python -m json.tool + + .. image:: modAAI_getByVserverName.PNG + +Named-Queries +------------- + +These commands are used to get more information than can be obtained in a single other query. They require more data to be sent in the query, but return information on the related instances of a given vnf or vserver, as well as the information about the vnf/vserver itself. + +**For vFW:** + + .. code-block:: bash + + curl --silent -k -u "<userName>:<password>" --header "X-FromAppId: <fromApp>" --header "Content-Type: application/json" --header "Accept: application/json" --header "X-TransactionId: <requestID>" -d "{\"query-parameters\": { \"named-query\": { \"named-query-uuid\": \"a93ac487-409c-4e8c-9e5f-334ae8f99087\" } }, \"instance-filters\":{\"instance-filter\":[ {\"generic-vnf\": { \"vnf-id\": \"<vnfID>\"}}]}}" -X POST https://aai.api.simpledemo.openecomp.org:8443/aai/search/named-query | python -m json.tool + + .. image:: modAAI_namedQueryVnfId.PNG + +**For vDNS:** + + .. code-block:: bash + + curl --silent -k -u "<userName>:<password>" --header "X-FromAppId: <fromApp>" --header "Content-Type: application/json" --header "Accept: application/json" --header "X-TransactionId: <requestID>" -d "{\"query-parameters\": { \"named-query\": { \"named-query-uuid\": \"4ff56a54-9e3f-46b7-a337-07a1d3c6b469\" } }, \"instance-filters\":{\"instance-filter\":[ {\"vserver\": { \"vserver-name\": \"<vnfID>\"}}]}}" -X POST https://aai.api.simpledemo.openecomp.org:8443/aai/search/named-query | python -m json.tool + +Adding Data to A&AI +^^^^^^^^^^^^^^^^^^^ + +Generic-Vnf +----------- + + .. code-block:: bash + + curl --silent -k -u "<username>:<password>" --header "X-FromAppId: POLICY" --header "Content-Type: application/json" --header "Accept: application/json" --header "X-TransactionId: 8611ece5-5786-4e71-b72f-e87ef44029da" -X PUT -H "Content-Type: application/json" --data @addVnf.txt https://aai.api.simpledemo.openecomp.org:8443/aai/v11/network/generic-vnfs/generic-vnf/<vnfID> | python -m json.tool + +The addVNF.txt file is just the data you would like to add. At minimum, the vnf-id, vnf-name, vnf-type and is-closed-loop-disabled fields need to be filled out, and the vnf-id needs to match the one you choose in the url of the curl command. + +Vserver +------- + + .. code-block:: bash + + curl --silent -k -u "<username>:<password>" --header "X-FromAppId: POLICY" --header "Content-Type: application/json" --header "Accept: application/json" --header "X-TransactionId: 8611ece5-5786-4e71-b72f-e87ef44029da" -X PUT -H "Content-Type: application/json" --data @addVserver.txt https://aai.api.simpledemo.openecomp.org:8443/aai/v11/cloud-infrastructure/cloud-regions/cloud-region/<cloud-owner>/<cloud-region-id>/tenants/tenant/<tenant-id>/vservers/vserver/<vserver-id> + +The addVserver.txt file is the vserver object you would like to add. It needs values for vserver-id, vserver-name, vserver-selflink, in-maint, and is-close-loop-disabled at minimum. The values of <cloud-owner>, <cloud-region-id>, and <tenants> depends on the values already in Rackspace, see the section above under finding all Vservers. + +Named Queries +------------- + +The data for the named queries is based off of the data in the relationship-list field for both vservers and vnfs. + +End of Document + +.. SSNote: Wiki page ref. https://wiki.onap.org/pages/viewpage.action?pageId=16005849#Verifying/ModifyingAAIData + + diff --git a/docs/drools/modAmsterTemplate.rst b/docs/drools/modAmsterTemplate.rst new file mode 100644 index 00000000..4456f292 --- /dev/null +++ b/docs/drools/modAmsterTemplate.rst @@ -0,0 +1,130 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +****************************** +Modifying the Release Template +****************************** + +.. contents:: + :depth: 3 + + +This tutorial is intended for Policy Drools Applications developers who would like to test their code using the PDP-D in Eclipse instead of installing in a lab. The example for this tutorial will walk through making a change to the Amsterdam Control Loop Template, building the archetype project, and instantiating a controller with the PDP-D. + +Installing the Archetype Project in Eclipse +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**STEP 1:** First, open the drools-pdp project in Eclipse and navigate to File → New → Project... + + .. image:: mat_new_project.JPG + +**STEP 2:** Navigate to Maven → Maven Project + + .. image:: mat_maven_project.JPG + +**STEP 3:** For demo purposes, the location of the project will be put in Documents/demo. Hit next to proceed. + + .. image:: mat_project_location.JPG + +**STEP 4:** Click "Configure" near the top right. + + .. image:: mat_configure.JPG + +**STEP 5:** Add a Remote and/or a Local catalog + + **STEP 5.1:** Add a Remote Catalog to find the ONAP staged drools-applications + + **STEP 5.1.1:** Click "Add Remote Catalog..." + + .. image:: mat_add_local_catalog.JPG + + **STEP 5.1.2:** Add the ONAP Staging repository archetype-catalog.xml with a description if desired. Click "OK" then "Apply", then "OK". + + .. image:: mat_nexus_catalog.JPG + + **STEP 5.1.3:** The ONAP staging archetypes are now an option: + + .. image:: mat_archetypes.JPG + + **STEP 5.2:** Add a Local Catalog to find a local drools-applications in your .m2 local repository + + **STEP 5.2.1:** Click "Add Local Catalog..." + + .. image:: mat_add_local_catalog.JPG + + **STEP 5.2.2:** Browse to or type in the path to your .m2 repository, give it a name and click "OK" + + .. image:: mat_nexus_local_catalog.png + + **STEP 5.2.3:** The new local repository appears on the catalog list, click "Apply and Close" + + .. image:: mat_local_archetypes.png + +**STEP 6:** If you wish to use a snapshot version of drools-applications, make sure to check the "Include snapshot archetypes" box. Highlight the option with the Artifact Id "archetype-cl-amsterdam" and click next. + + .. image:: mat_select_archetypes.png + +**STEP 7:** The following screen allows the user to modify some of the configurable parameters of the control loop. For this demo the default parameters that are already populated will be used. Fill out the Groud Id, Artifact Id, Version, and Package and hit "Finish". For the demo the following is used: + + .. image:: mat_archetype_params.JPG + +**NOTE:** If you are using a snapshot version of drools-applications. make sure that the "dependenciesVersion" variable value you specify matches the drools-applications artifact versions + + .. image:: mat_archetype_checkparams.png + + +**STEP 8:** Depending on the IDE in use, an error may be generated about handling the kie-maven-plugin:6.5.0.Final:build plugin. This can be ignored, click "Finish" and then "OK" if a warning pops up about having build errors. + + .. image:: mat_error.JPG + +**STEP 9:** Amsterdam can now be seen in the Project Explorer: + + .. image:: mat_amsterdam_project.JPG + + +Modifying the Amsterdam Template +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**STEP 1:** Expand the amsterdam project and "src/main/resources". The drl generated from the archetype will be present as follows: + + .. image:: mat_amsterdam_drl.JPG + +**STEP 2:** Now a change will be added to the drl from above. For this tutorial, a new logging statement will be added that will show in the console of Eclipse when the changes are tested. We'll add this in the SETUP rule. + + .. image:: mat_hello_world.JPG + +**STEP 3:** Right click on the Amsterdam project, hover over "Run As", then click "Maven build". + + .. image:: mat_maven_build.JPG + +**STEP 4:** For the goals type "clean install", click "Apply" and then click "Run". + + .. image:: mat_clean_install.JPG + + .. image:: mat_build_success.JPG + +Running the PDP-D with the Amsterdam Controller +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**STEP 1:** Copy the controller properties file that was generated from the archetype in amsterdam/src/main/config into policy-management/src/main/config + + .. image:: mat_amsterdam_controller.JPG + +**STEP 2:** Go src/main/java and expand the package "org.onap.policy.drools.system". Right click on "Main.java", then hover over "Run As..." and click "Java Application". + + .. image:: mat_run_as.JPG + +**STEP 3:** Search through the console for the logging statement "\***** HELLO WORLD \*****". This indicates that the template change worked. Modifications can continue to be made and the Telemetry API can be used to interact with the PDP-D that is running in Eclipse and to test control loop flows. + + .. image:: mat_console_output.JPG + + + +End of Document + + +.. SSNote: Beijing release update. https://wiki.onap.org/display/DW/Modifying+the+Release+template +.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Modifying+the+Amsterdam+release+template + + diff --git a/docs/drools/poolingBuckets.png b/docs/drools/poolingBuckets.png Binary files differnew file mode 100644 index 00000000..8b43a7de --- /dev/null +++ b/docs/drools/poolingBuckets.png diff --git a/docs/drools/poolingDesign.png b/docs/drools/poolingDesign.png Binary files differnew file mode 100644 index 00000000..8040e809 --- /dev/null +++ b/docs/drools/poolingDesign.png diff --git a/docs/drools/poolingPdps.png b/docs/drools/poolingPdps.png Binary files differnew file mode 100644 index 00000000..e05bad3d --- /dev/null +++ b/docs/drools/poolingPdps.png diff --git a/docs/drools/runningEclipse.rst b/docs/drools/runningEclipse.rst new file mode 100644 index 00000000..136efe73 --- /dev/null +++ b/docs/drools/runningEclipse.rst @@ -0,0 +1,56 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +************************ +Running PDP-D in Eclipse +************************ + +.. contents:: + :depth: 3 + +This tutorial is intended for developers who would like to run the PDP-D in an Eclipse environment. It is assumed that the drools-pdp git project has been imported in an Eclipse workspace. + +Starting the PDP-D +^^^^^^^^^^^^^^^^^^ +For the Amsterdam release, the project directory will look as follows assuming all drools-pdp projects were selected when importing. + + .. image:: RunEcl_drools_pdp_project.png + +Right click on policy-management hover over "Run As" and select "Java Application" + + .. image:: RunEcl_run_as.png + +Search for "Main" in the pop up and select the Main with the package "org.onap.policy.drools.system" and click "OK". + + .. image:: RunEcl_main.png + +The PDP-D will start running; the console will display output. + + .. image:: RunEcl_console_output.png + +Interacting with the PDP-D +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To interact with the PDP-D, the Telemetry API can be used. A simple GET on the engine will show that the PDP-D is running in Eclipse. + + .. code-block:: bash + + curl -k --silent --user @1b3rt:31nst31n -X GET https://localhost:9696/policy/pdp/engine/ | python -m json.tool + + .. image:: RunEcl_telemetry.png + +An HTTP 200 message for the GET request will also appear in the console in Eclipse. + + .. image:: RunEcl_pdpd_200.png + + +.. seealso:: To create a controller and run a control loop, refer to `Modifying the Release Template <modAmsterTemplate.html>`_. + + +End of Document + + +.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Running+PDP-D+in+Eclipse + + diff --git a/docs/drools/tutorial_VOLTE.rst b/docs/drools/tutorial_VOLTE.rst new file mode 100644 index 00000000..2dc84628 --- /dev/null +++ b/docs/drools/tutorial_VOLTE.rst @@ -0,0 +1,121 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +********************************************************** +Tutorial: Testing the VOLTE Use Case in a standalone PDP-D +********************************************************** + +.. contents:: + :depth: 3 + +In this tutorial we will go over how to access and start up the PDP-D, setup the prerequisites for the VOLTE flow, enable/disable the VFC Simulator that will be used in the VOLTE flow, and inject messages to trigger the VOLTE flow. + +Accessing and starting the PDP-D +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The first step is to access the docker container of name *drools*. + + .. code-block:: bash + + docker exec -it -u 0 drools su - policy + +The PDP-D software is installed under the *policy* account, the policy root directory is under *${POLICY_HOME}* environment variable and it may be changed on a per installation basis. It is typically set up under the */opt/app/policy* directory but can be changed during installation. All PDP-D software runs with non-root privileges as *policy* is a regular user account. + +Once within the drools container, the running status can be observed by using the *policy* command: + + .. code-block:: bash + + policy [--debug] status|start|stop + +The running status of the PDP-D can be observed with *policy status* + + .. code-block:: bash + + policy@drools:~$ policy status [drools-pdp-controllers] L []: Policy Management (pid 1500) is running 1 cron jobs installed. + + +Prerequisites for the VOLTE flow +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In order to trigger the VOLTE flow we will need to inject an ONSET message via curl command. We're going to create a temporary *util* directory to store a file that contains the VOLTE ONSET message. + +Navigate to */tmp* and create directory *util*. *util* is just a temporary folder we've created to use as our 'workspace'. + + .. code-block:: bash + + cd /tmp + mkdir util + + +Next, we're going to create a file named *dcae.volte.onset.json* and edit it to paste the VOLTE ONSET message contents. + + .. code-block:: bash + + touch dcae.volte.onset.json + vi dcae.volte.onset.json + +Here are the contents of the VOLTE ONSET message. Copy/paste this into dcae.volte.onset.json: + + .. code-block:: json + + { + "closedLoopControlName": "ControlLoop-VOLTE-2179b738-fd36-4843-a71a-a8c24c70c55b", + "closedLoopAlarmStart": 1484677482204798, + "closedLoopEventClient": "DCAE.HolmesInstance", + "closedLoopEventStatus": "ONSET", + "requestID": "97964e10-686e-4790-8c45-bdfa61df770f", + "target_type": "VM", + "target": "vserver.vserver-name", + "AAI": { + "vserver.is-closed-loop-disabled": "false", + "vserver.prov-status": "ACTIVE", + "vserver.vserver-name": "dfw1lb01lb01", + "service-instance.service-instance-id" : "vserver-name-16102016-aai3255-data-11-1", + "generic-vnf.vnf-id" : "vnf-id-16102016-aai3255-data-11-1", + "generic-vnf.vnf-name" : "vnf-name-16102016-aai3255-data-11-1" + }, + "from": "DCAE", + "version": "1.0.2" + } + + +Enabling the VFC Simulator +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Enabling the *controlloop-utils* feature will enable the simulators. To do this, simply stop the drools pdp, enable the feature, and restart the drools pdp like so: + + .. code-block:: bash + + policy stop + features enable controlloop-utils + policy start + +Now, in */opt/app/policy/config/* directory, you should see a new properties file named *simulators.properties.environment*. In here you will find the credentials for the VFC simulator. + +Injecting an ONSET to trigger the VOLTE Flow +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We are now ready to inject an ONSET message to trigger the VOLTE flow. Simply navigate back to the directory *dcae.volte.onset.json* file is saved (i.e. cd /tmp/util) and run this curl command: + + .. code-block:: bash + + http --verify=no --default-scheme=https -a @1b3rt:31nst31n PUT :9696/policy/pdp/engine/topics/sources/ueb/unauthenticated.DCAE_CL_OUTPUT/events @dcae.volte.onset.json Content-Type:"text/plain" + +You should see some output similar to this: + +.. image:: tutorial_VOLTE_1.png + +You can view the logs to see the network activity or find any errors that may have occurred. Logs are located in */opt/app/policy/logs*. + +Reading the logs +^^^^^^^^^^^^^^^^ + +Once you've injected the onset message, this should appear in the network.log: + +.. image:: tutorial_VOLTE_2.png + + +End of Document + +.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Tutorial%3A+Testing+the+VOLTE+Use+Case+in+a+standalone+PDP-D diff --git a/docs/drools/tutorial_VOLTE_1.png b/docs/drools/tutorial_VOLTE_1.png Binary files differnew file mode 100755 index 00000000..938604df --- /dev/null +++ b/docs/drools/tutorial_VOLTE_1.png diff --git a/docs/drools/tutorial_VOLTE_2.png b/docs/drools/tutorial_VOLTE_2.png Binary files differnew file mode 100755 index 00000000..53ee7802 --- /dev/null +++ b/docs/drools/tutorial_VOLTE_2.png diff --git a/docs/drools/tutorial_cl.rst b/docs/drools/tutorial_cl.rst new file mode 100644 index 00000000..3395ea71 --- /dev/null +++ b/docs/drools/tutorial_cl.rst @@ -0,0 +1,51 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +*********************************************************************************************** +Tutorial: Generating and Testing your own Control Loop Operational Policy in a standalone PDP-D +*********************************************************************************************** + +.. contents:: + :depth: 3 + +To generate your own control loop operational policy, use the *create-cl-amsterdam* tool. The *create-cl-amsterdam* script is located in *${POLICY_HOME}/bin (/opt/app/policy/bin)*. When the script is run, it will ask for values for a variety of fields. The fields will have pre-filled out defaults, and for the most part, the defaults are fine to leave in. The two main fields that should be changed are the Template Control Loop Name and the Control Loop Yaml. + + .. image:: Tut_cl_valuesHighlight.png + +Make sure the Yaml’s controlLoopName matches the Template Control Loop Name you pass in. Finally, confirm that the parameters are correct, confirm the directory it will add the policy files in (default is /tmp) and tell the script to create the maven artifact. + + *Confirm the parameters and enter the directory to install in as shown below:* + + .. image:: Tut_cl_confirmAndDirectory.PNG + + *Choose whether to immediately deploy (in this case the directory is /tmp/amsterdam)* + + .. image:: Tut_cl_preDeploy.PNG + +When the processing is done, you get the choice of immediately deploying the policy to the local repository, or first examining the rules in the directory it tells you. If you don’t immediately deploy, you need to use the “*mvn install*” command in the newly created directory to continue. When all that is done, go to the directory where the rule was placed (the /tmp/amsterdam directory in this case) and copy the *<name>-controller.properties* file to *${POLICY_HOME}/config*. Turn the engine off and then back on with “*policy stop*” and then “*policy start*”. + + *Location of the properties file* + + .. image:: Tut_cl_propFile.PNG + + *Moving the properties file to ${POLICY_HOME}/config* + + .. image:: Tut_cl_finalStep.PNG + +Proceed with testing your new policy as described in the specific tutorials: + +• vCPE - `Tutorial: Testing the vCPE use case in a standalone PDP-D <tutorial_vCPE.html>`_ +• vDNS - `Tutorial: Testing the vDNS Use Case in a standalone PDP-D <tutorial_vDNS.html>`_ +• vFW - `Tutorial: Testing the vFW flow in a standalone PDP-D <tutorial_vFW.html>`_ +• VoLTE - `Tutorial: Testing the VOLTE Use Case in a standalone PDP-D <tutorial_VOLTE.html>`_ + + +.. seealso:: To deploy a control loop in Eclipse from the control loop archetype template, refer to `Modifying the Release Template <modAmsterTemplate.html>`_. + + +End of Document + + +.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Tutorial%3A+Generating+and+Testing+your+own+Control+Loop+Operational+Policy+in+a+standalone+PDP-D + diff --git a/docs/drools/tutorial_vCPE.rst b/docs/drools/tutorial_vCPE.rst new file mode 100644 index 00000000..9a2ac1a4 --- /dev/null +++ b/docs/drools/tutorial_vCPE.rst @@ -0,0 +1,122 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +********************************************************* +Tutorial: Testing the vCPE use case in a standalone PDP-D +********************************************************* + +.. contents:: + :depth: 3 + + +High Level Architecture +^^^^^^^^^^^^^^^^^^^^^^^ +The vCPE flow begins with an onset message that is sent from DCAE notifying the PDP-D that an action needs to be taken on a VM/VNF. Once the PDP-D has inserted the onset into drools memory, rules begin to fire to start processing the onset for the vCPE policy that exists in drools memory. If the onset is not enriched with A&AI data, Policy will query A&AI for the VM/VNF data otherwise the PDP-D will get the A&AI data needed directly from the onset. A Guard query is then executed to determine if the action to be taken is allowed. If Guard returns a permit, the PDP-D will then send an APPC Restart recipe request to restart the VM/VNF specified in the request. If APPC is successful then the PDP-D will send a operation success notification on the POLICY-CL-MGT topic. The PDP-D waits for an abatement message to come from DCAE before ending the transaction. Once the abatement is received the PDP-D sends a final success notification and gracefully ends processing the event. + +Initial Setup +^^^^^^^^^^^^^ + +For this tutorial, a feature for simulating components involved in the flow outside of Policy will be turned on. Run "*features enable controlloop-utils*". + + .. image:: Tut_vCPE_simulators_enabled.JPG + +Now start the PDP-D using the command "policy start" + + .. image:: Tut_vCPE_policy_start.JPG + +Running the Flow +^^^^^^^^^^^^^^^^ + +The telemetry API is used to see what is in memory. There should only be 1 fact, the Params object which is created at initialization time and contains the vCPE policy that was created. + + .. code-block:: bash + + curl -k --silent --user @1b3rt:31nst31n -X GET https://localhost:9696/policy/pdp/engine/controllers/amsterdam/drools/facts/amsterdam | python -m json.tool + + + .. image:: Tut_vCPE_get_facts.JPG + +Using the telemetry API, a simulated onset can be injected by the user. For demo purposes, this is the simulated onset that will be used: + + .. image:: Tut_vCPE_simulated_onset.JPG + +**NOTE:** The onset that gets injected has to have a closedLoopControlName that matches the pushed policy's closedLoopControlName. + +Inject the onset using the Telemetry API. + + .. code-block:: bash + + curl -k --silent --user @1b3rt:31nst31n --header "Content-Type: text/plain" --data @dcae.vcpe.onset.json -X PUT https://localhost:9696/policy/pdp/engine/topics/sources/ueb/unauthenticated.DCAE_EVENT_OUTPUT/events | python -m json.tool + + .. image:: Tut_vCPE_insert_onset.JPG + +**NOTE:** The simulated onset is enriched with A&AI data. The PDP-D will not make an A&AI query since the data needed can be extracted from the onset. + +Now check the facts in memory, there should be 7 objects present. Two timers exist to put a time limit on the operation and on the overall control loop (in the case of retries or policy chaining). The event and it's associated manager and operation manager are also present in memory. A lock on the target entity is inserted to ensure no other events try to take action on the VM/VNF that is currently processing. + + .. image:: Tut_vCPE_get_facts_2.JPG + +The network log will be used to monitor the activity coming in and out of the PDP-D. This log is located at *$POLICY_HOME/logs/network.log*. This will show the notifications that the PDP-D sends out at different stages of processing. The order of successful processing begins with an ACTIVE notification to show that the onset was acknowledged and the operation is beginning transit. + + .. image:: Tut_vCPE_policy_active.JPG + +Once the event is in the ACTIVE state, the PDP-D consults Guard to determine if this operation should be allowed, a series of operation notifications are sent for starting the Guard query, obtaining a PERMIT or DENY, and beginning the operation. + + .. image:: Tut_vCPE_guard_not_queried.JPG + +| + + .. image:: Tut_vCPE_guard_result.JPG + +| + + .. image:: Tut_vCPE_policy_operation.JPG + +Once the operation starts an APPC request is sent out. + + .. image:: Tut_vCPE_appc_request.JPG + +A simulated APPC response will be injected to the APPC-LCM-WRITE topic, this is the example response used: + + .. image:: Tut_vCPE_simulated_appc_response.JPG + +Inject the response using the Telemetry API. + + .. code-block:: bash + + curl -k --silent --user @1b3rt:31nst31n --header "Content-Type: text/plain" --data @appc.lcm.success.json -X PUT https://localhost:9696/policy/pdp/engine/topics/sources/ueb/APPC-LCM-WRITE/events | python -m json.tool + + .. image:: Tut_vCPE_inject_appc_response.JPG + +The network log will show the PDP-D sent an operation success notification. + + .. image:: Tut_vCPE_policy_operation_success.JPG + +For the vCPE use case, once an operation is successful, the PDP-D waits for DCAE to send an abatement message to end processing. The following abatement message will be used: + + .. image:: Tut_vCPE_simulated_abatement.JPG + +Inject the abatement message using the Telemetry API. + + .. code-block:: bash + + curl -k --silent --user @1b3rt:31nst31n --header "Content-Type: text/plain" --data @dcae.vcpe.abatement.json -X PUT https://localhost:9696/policy/pdp/engine/topics/sources/ueb/unauthenticated.DCAE_EVENT_OUTPUT/events | python -m json.tool + + .. image:: Tut_vCPE_insert_abatement.JPG + +Once the abatement is received, a final success notification is sent from the PDP-D. + + .. image:: Tut_vCPE_policy_final_success.JPG + +After processing there should only be 1 fact left in memory. + + .. image:: Tut_vCPE_final_memory.JPG + + +End of Document + + +.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Tutorial%3A+Testing+the+vCPE+use+case+in+a+standalone+PDP-D + + diff --git a/docs/drools/tutorial_vDNS.rst b/docs/drools/tutorial_vDNS.rst new file mode 100644 index 00000000..330bb64e --- /dev/null +++ b/docs/drools/tutorial_vDNS.rst @@ -0,0 +1,119 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +********************************************************* +Tutorial: Testing the vDNS Use Case in a standalone PDP-D +********************************************************* + +.. contents:: + :depth: 3 + +In this tutorial we will go over how to access and start up the PDP-D, setup the prerequisites for the vDNS flow, enable/disable the AAI and SO Simulators that will be used in the vDNS flow, and inject messages to trigger the vDNS flow. + +Accessing and starting the PDP-D +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The first step is to access the docker container of name *drools*. + + .. code-block:: bash + + docker exec -it -u 0 drools su - policy + +The PDP-D software is installed under the *policy* account, the policy root directory is under *${POLICY_HOME}* environment variable and it may be changed on a per installation basis. It is typically set up under the */opt/app/policy* directory but can be changed during installation. All PDP-D software runs with non-root privileges as *policy* is a regular user account. + +Once within the drools container, the running status can be observed by using the *policy* command: + + .. code-block:: bash + + policy [--debug] status|start|stop + +The running status of the PDP-D can be observed with *policy status* + + .. code-block:: bash + + policy@drools:~$ policy status [drools-pdp-controllers] L []: Policy Management (pid 1500) is running 1 cron jobs installed. + + +Prerequisites for the vDNS flow +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In order to trigger the vDNS flow we will need to inject an ONSET message via curl command. We're going to create a temporary *util* directory to store a file that contains the vDNS ONSET message. + +Navigate to */tmp* and create directory *util*. *util* is just a temporary folder we've created to use as our 'workspace'. + + .. code-block:: bash + + cd /tmp + mkdir util + + +Next, we're going to create a file named *dcae.vdns.onset.json* and edit it to paste the vDNS ONSET message contents. + + .. code-block:: bash + + touch dcae.vdns.onset.json + vi dcae.vdns.onset.json + +Here are the contents of the vDNS ONSET message. Copy/paste this into dcae.vdns.onset.json: + + .. code-block:: json + + { + "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3", + "closedLoopAlarmStart": 1484677482204798, + "closedLoopEventClient": "DCAE_INSTANCE_ID.dcae-tca", + "closedLoopEventStatus": "ONSET", + "requestID": "e4f95e0c-a013-4530-8e59-c5c5f9e539b6", + "target_type": "VNF", + "target": "vserver.vserver-name", + "AAI": { + "vserver.is-closed-loop-disabled": "false", + "vserver.prov-status": "ACTIVE", + "vserver.vserver-name": "dfw1lb01lb01" + }, + "from": "DCAE", + "version": "1.0.2" + } + + + +Enabling the AAI and SO Simulators +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Enabling the *controlloop-utils* feature will enable the simulators. To do this, simply stop the drools pdp, enable the feature, and restart the drools pdp like so: + + .. code-block:: bash + + policy stop + features enable controlloop-utils + policy start + +Now, in */opt/app/policy/config/* directory, you should see a new properties file named *simulators.properties.environment*. In here you will find the credentials for the AAI and SO simulators. + +Injecting an ONSET to trigger the vDNS Flow +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We are now ready to inject an ONSET message to trigger the vDNS flow. Simply navigate back to the directory *dcae.vdns.onset.json* file is saved (i.e. cd /tmp/util) and run this curl command: + + .. code-block:: bash + + http --verify=no --default-scheme=https -a @1b3rt:31nst31n PUT :9696/policy/pdp/engine/topics/sources/ueb/unauthenticated.DCAE_CL_OUTPUT/events @dcae.vdns.onset.json Content-Type:"text/plain" + +You should see some output similar to this: + + .. image:: tutorial_vDNS_1.png + +You can view the logs to see the network activity or find any errors that may have occurred. Logs are located in */opt/app/policy/logs*. + +Reading the logs +^^^^^^^^^^^^^^^^ + +Once you've injected the onset message, this should appear in the network.log: + + .. image:: tutorial_vDNS_2.png + + +End of Document + +.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Tutorial%3A+Testing+the+vDNS+Use+Case+in+a+standalone+PDP-D diff --git a/docs/drools/tutorial_vDNS_1.png b/docs/drools/tutorial_vDNS_1.png Binary files differnew file mode 100644 index 00000000..ed2cb36f --- /dev/null +++ b/docs/drools/tutorial_vDNS_1.png diff --git a/docs/drools/tutorial_vDNS_2.png b/docs/drools/tutorial_vDNS_2.png Binary files differnew file mode 100644 index 00000000..bbfb8206 --- /dev/null +++ b/docs/drools/tutorial_vDNS_2.png diff --git a/docs/drools/tutorial_vFW.rst b/docs/drools/tutorial_vFW.rst new file mode 100644 index 00000000..72288f33 --- /dev/null +++ b/docs/drools/tutorial_vFW.rst @@ -0,0 +1,124 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +**************************************************** +Tutorial: Testing the vFW flow in a standalone PDP-D +**************************************************** + +.. contents:: + :depth: 3 + + +High Level Architecture +^^^^^^^^^^^^^^^^^^^^^^^ +The vFW flow begins with an onset message that is sent from DCAE notifying the PDP-D that an action needs to be taken on a VNF. Once the PDP-D has inserted the onset into drools memory, rules begin to fire to start processing the onset for the vFW policy that exists in drools memory. If the onset is not enriched with A&AI data, Policy will query A&AI for the VNF data otherwise the PDP-D will get the A&AI data needed directly from the onset. Then an A&AI named query is executed on the source VNF entity from the onset to find the target VNF entity that the PDP-D will take action on. Once the target entity is retrieved from A&AI, a Guard query is executed to determine if the action to be taken is allowed. If Guard returns a permit, the PDP-D will then send an APPC ModifyConfig recipe request to modify pg-streams as specified in the request payload. If APPC is successful then the PDP-D will send a final success notification on the POLICY-CL-MGT topic and gracefully end processing the event. + +Initial Setup +^^^^^^^^^^^^^ + +For this tutorial, a feature for simulating components involved in the flow outside of Policy will be turned on. Run "*features enable controlloop-utils*". + + .. image:: Tut_vFW_simulators_enabled.JPG + +Now start the PDP-D using the command "policy start" + + .. image:: Tut_vFW_policy_start.JPG + +Running the Flow +^^^^^^^^^^^^^^^^ + +The telemetry API is used to see what is in memory. There should only be 1 fact, the Params object which is created at initialization time and contains the vFW policy that was created. + + .. code-block:: bash + + curl -k --silent --user @1b3rt:31nst31n -X GET https://localhost:9696/policy/pdp/engine/controllers/amsterdam/drools/facts/amsterdam | python -m json.tool + + .. image:: Tut_vFW_get_facts.JPG + +Using the telemetry API, a simulated onset can be injected by the user. For demo purposes, this is the simulated onset that will be used: + + .. image:: Tut_vFW_simulated_onset.JPG + +**NOTE:** The onset that gets injected has to have a closedLoopControlName that matches the pushed policy's closedLoopControlName. + +Inject the onset using the Telemetry API. + + .. code-block:: bash + + curl -k --silent --user @1b3rt:31nst31n --header "Content-Type: text/plain" --data @dcae.vfw.onset.json -X PUT https://localhost:9696/policy/pdp/engine/topics/sources/ueb/unauthenticated.DCAE_EVENT_OUTPUT/events | python -m json.tool + + .. image:: Tut_vFW_onset_injected.JPG + +Now check the facts in memory, there should be 7 objects present. Two timers exist to put a time limit on the operation and on the overall control loop (in the case of retries or policy chaining). The event and it's associated manager and operation manager are also present in memory. A lock on the target entity is inserted to ensure no other events try to take action on the VNF that is currently processing. + + .. image:: Tut_vFW_get_facts_2.JPG + +The network log will be used to monitor the activity coming in and out of the PDP-D. This log is located at *$POLICY_HOME/logs/network.log*. This will show the notifications that the PDP-D sends out at different stages of processing. The order of successful processing begins with an ACTIVE notification to show that the onset was acknowledged and the operation is beginning transit. + + .. image:: Tut_vFW_policy_active.JPG + +Next a query will be sent to A&AI to get information on the VNF specified from the onset. The picture below shows the query going OUT of the PDP-D and the response coming IN. + +**NOTE:** Policy does A&AI queries for VNF information when the onset is not enriched with A&AI data. In this example only the generic-vnf.vnf-name was provided so a query to A&AI is necessary to retrieve data that is needed in the APPC request. + + .. image:: Tut_vFW_aai_get.JPG + +For the vFW use case, the source entity reported in the onset message may not be the target entity that the APPC operation takes action on. To determine the true target entity, an A&AI named query is performed. The request is shown in the network log. + + .. image:: Tut_vFW_aai_named_query_request.JPG + +The response is also displayed in the network log. + + .. image:: Tut_vFW_aai_named_query_response.JPG + +Once the target entity is found, the PDP-D consults Guard to determine if this operation should be allowed, a series of operation notifications are sent for starting the Guard query, obtaining a PERMIT or DENY, and beginning the operation. + + .. image:: Tut_vFW_policy_guard_start.JPG + +| + + .. image:: Tut_vFW_policy_guard_result.JPG + +| + + .. image:: Tut_vFW_policy_operation_start.JPG + +Once the operation starts an APPC request is sent out. + + .. image:: Tut_vFW_appc_request.JPG + +A simulated APPC response will be injected to the APPC-CL topic, this is the example response used: + + .. image:: Tut_vFW_simulated_appc_response.JPG + +Inject the response using the Telemetry API. + + .. code-block:: bash + + curl -k --silent --user @1b3rt:31nst31n --header "Content-Type: text/plain" --data @appc.legacy.success.json -X PUT https://localhost:9696/policy/pdp/engine/topics/sources/ueb/APPC-CL/events | python -m json.tool + + .. image:: Tut_vFW_insert_appc_response.JPG + +The network log will show the PDP-D sent an operation success notification. + + .. image:: Tut_vFW_policy_operation_success.JPG + +Then a final success notification is sent. + + .. image:: Tut_vFW_policy_final_success.JPG + +After processing there should only be 1 fact left in memory. + + .. image:: Tut_vFW_final_memory.JPG + + + + +End of Document + + + + +.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Tutorial%3A+Testing+the+vFW+flow+in+a+standalone+PDP-D + |
