diff options
| author |   jhh <jorge.hernandez-herrero@att.com> | 2020-06-12 17:01:24 -0500 |
|---|---|---|
| committer | jhh <jorge.hernandez-herrero@att.com> | 2020-06-15 11:56:21 -0500 |
| commit | 108dd8ff62cbdfbbe1ba3589afe43582105ea275 (patch) | |
| tree | 6007bd025b40e1aca92c3cfe1b0672f7645c917d /docs | |
| parent | 11de40286f2a91edc9755f6ea9e621006452527b (diff) | |
drools documentation redo
Issue-ID: POLICY-2622
Signed-off-by: jhh <jorge.hernandez-herrero@att.com>
Change-Id: I568c041f972c76b595964ee3de731c1cde304d8f
Signed-off-by: jhh <jorge.hernandez-herrero@att.com>
Diffstat (limited to 'docs')
108 files changed, 2410 insertions, 2650 deletions
diff --git a/docs/drools/RunEcl_console_output.png b/docs/drools/RunEcl_console_output.png Binary files differdeleted file mode 100755 index d2c39439..00000000 --- a/docs/drools/RunEcl_console_output.png +++ /dev/null diff --git a/docs/drools/RunEcl_drools_pdp_project.png b/docs/drools/RunEcl_drools_pdp_project.png Binary files differdeleted file mode 100755 index bafb94ea..00000000 --- a/docs/drools/RunEcl_drools_pdp_project.png +++ /dev/null diff --git a/docs/drools/RunEcl_frankfurt_project_explorer.png b/docs/drools/RunEcl_frankfurt_project_explorer.png Binary files differdeleted file mode 100644 index 4c1cf13d..00000000 --- a/docs/drools/RunEcl_frankfurt_project_explorer.png +++ /dev/null diff --git a/docs/drools/RunEcl_main.png b/docs/drools/RunEcl_main.png Binary files differdeleted file mode 100755 index 9dec695f..00000000 --- a/docs/drools/RunEcl_main.png +++ /dev/null diff --git a/docs/drools/RunEcl_pdpd_200.png b/docs/drools/RunEcl_pdpd_200.png Binary files differdeleted file mode 100755 index 32e4e5ed..00000000 --- a/docs/drools/RunEcl_pdpd_200.png +++ /dev/null diff --git a/docs/drools/RunEcl_run_as.png b/docs/drools/RunEcl_run_as.png Binary files differdeleted file mode 100755 index 579dc4db..00000000 --- a/docs/drools/RunEcl_run_as.png +++ /dev/null diff --git a/docs/drools/RunEcl_telemetry.png b/docs/drools/RunEcl_telemetry.png Binary files differdeleted file mode 100755 index ae4f65cc..00000000 --- a/docs/drools/RunEcl_telemetry.png +++ /dev/null diff --git a/docs/drools/Tut_cl_confirmAndDirectory.PNG b/docs/drools/Tut_cl_confirmAndDirectory.PNG Binary files differdeleted file mode 100755 index cdb84a89..00000000 --- a/docs/drools/Tut_cl_confirmAndDirectory.PNG +++ /dev/null diff --git a/docs/drools/Tut_cl_finalStep.PNG b/docs/drools/Tut_cl_finalStep.PNG Binary files differdeleted file mode 100755 index b56b06e4..00000000 --- a/docs/drools/Tut_cl_finalStep.PNG +++ /dev/null diff --git a/docs/drools/Tut_cl_preDeploy.PNG b/docs/drools/Tut_cl_preDeploy.PNG Binary files differdeleted file mode 100755 index 69a2cdb1..00000000 --- a/docs/drools/Tut_cl_preDeploy.PNG +++ /dev/null diff --git a/docs/drools/Tut_cl_propFile.PNG b/docs/drools/Tut_cl_propFile.PNG Binary files differdeleted file mode 100755 index 960e182d..00000000 --- a/docs/drools/Tut_cl_propFile.PNG +++ /dev/null diff --git a/docs/drools/Tut_cl_valuesHighlight.png b/docs/drools/Tut_cl_valuesHighlight.png Binary files differdeleted file mode 100755 index 7a4bb790..00000000 --- a/docs/drools/Tut_cl_valuesHighlight.png +++ /dev/null diff --git a/docs/drools/Tut_vCPE_guard_not_queried.JPG b/docs/drools/Tut_vCPE_guard_not_queried.JPG Binary files differdeleted file mode 100755 index 14e52e79..00000000 --- a/docs/drools/Tut_vCPE_guard_not_queried.JPG +++ /dev/null diff --git a/docs/drools/Tut_vCPE_guard_result.JPG b/docs/drools/Tut_vCPE_guard_result.JPG Binary files differdeleted file mode 100755 index b1818d39..00000000 --- a/docs/drools/Tut_vCPE_guard_result.JPG +++ /dev/null diff --git a/docs/drools/Tut_vCPE_inject_appc_response.JPG b/docs/drools/Tut_vCPE_inject_appc_response.JPG Binary files differdeleted file mode 100755 index 6f5f21ba..00000000 --- a/docs/drools/Tut_vCPE_inject_appc_response.JPG +++ /dev/null diff --git a/docs/drools/Tut_vCPE_policy_active.JPG b/docs/drools/Tut_vCPE_policy_active.JPG Binary files differdeleted file mode 100755 index 02544f41..00000000 --- a/docs/drools/Tut_vCPE_policy_active.JPG +++ /dev/null diff --git a/docs/drools/Tut_vCPE_policy_final_success.JPG b/docs/drools/Tut_vCPE_policy_final_success.JPG Binary files differdeleted file mode 100755 index f063d09c..00000000 --- a/docs/drools/Tut_vCPE_policy_final_success.JPG +++ /dev/null diff --git a/docs/drools/Tut_vCPE_policy_operation.JPG b/docs/drools/Tut_vCPE_policy_operation.JPG Binary files differdeleted file mode 100755 index 1666ea62..00000000 --- a/docs/drools/Tut_vCPE_policy_operation.JPG +++ /dev/null diff --git a/docs/drools/Tut_vCPE_policy_operation_success.JPG b/docs/drools/Tut_vCPE_policy_operation_success.JPG Binary files differdeleted file mode 100755 index 9206847f..00000000 --- a/docs/drools/Tut_vCPE_policy_operation_success.JPG +++ /dev/null diff --git a/docs/drools/Tut_vFW_aai_get.JPG b/docs/drools/Tut_vFW_aai_get.JPG Binary files differdeleted file mode 100755 index 1b00d60b..00000000 --- a/docs/drools/Tut_vFW_aai_get.JPG +++ /dev/null diff --git a/docs/drools/Tut_vFW_aai_named_query_request.JPG b/docs/drools/Tut_vFW_aai_named_query_request.JPG Binary files differdeleted file mode 100755 index c7f86f93..00000000 --- a/docs/drools/Tut_vFW_aai_named_query_request.JPG +++ /dev/null diff --git a/docs/drools/Tut_vFW_aai_named_query_response.JPG b/docs/drools/Tut_vFW_aai_named_query_response.JPG Binary files differdeleted file mode 100755 index b3a9fa94..00000000 --- a/docs/drools/Tut_vFW_aai_named_query_response.JPG +++ /dev/null diff --git a/docs/drools/Tut_vFW_final_memory.JPG b/docs/drools/Tut_vFW_final_memory.JPG Binary files differdeleted file mode 100755 index f68aac79..00000000 --- a/docs/drools/Tut_vFW_final_memory.JPG +++ /dev/null diff --git a/docs/drools/Tut_vFW_insert_appc_response.JPG b/docs/drools/Tut_vFW_insert_appc_response.JPG Binary files differdeleted file mode 100755 index d631603c..00000000 --- a/docs/drools/Tut_vFW_insert_appc_response.JPG +++ /dev/null diff --git a/docs/drools/Tut_vFW_onset_injected.JPG b/docs/drools/Tut_vFW_onset_injected.JPG Binary files differdeleted file mode 100755 index ebff2e36..00000000 --- a/docs/drools/Tut_vFW_onset_injected.JPG +++ /dev/null diff --git a/docs/drools/Tut_vFW_policy_active.JPG b/docs/drools/Tut_vFW_policy_active.JPG Binary files differdeleted file mode 100755 index d3530a74..00000000 --- a/docs/drools/Tut_vFW_policy_active.JPG +++ /dev/null diff --git a/docs/drools/Tut_vFW_policy_final_success.JPG b/docs/drools/Tut_vFW_policy_final_success.JPG Binary files differdeleted file mode 100755 index bdb7858b..00000000 --- a/docs/drools/Tut_vFW_policy_final_success.JPG +++ /dev/null diff --git a/docs/drools/Tut_vFW_policy_guard_result.JPG b/docs/drools/Tut_vFW_policy_guard_result.JPG Binary files differdeleted file mode 100755 index 89a2f4f8..00000000 --- a/docs/drools/Tut_vFW_policy_guard_result.JPG +++ /dev/null diff --git a/docs/drools/Tut_vFW_policy_guard_start.JPG b/docs/drools/Tut_vFW_policy_guard_start.JPG Binary files differdeleted file mode 100755 index 1aa5490a..00000000 --- a/docs/drools/Tut_vFW_policy_guard_start.JPG +++ /dev/null diff --git a/docs/drools/Tut_vFW_policy_operation_start.JPG b/docs/drools/Tut_vFW_policy_operation_start.JPG Binary files differdeleted file mode 100755 index 0203c93a..00000000 --- a/docs/drools/Tut_vFW_policy_operation_start.JPG +++ /dev/null diff --git a/docs/drools/Tut_vFW_policy_operation_success.JPG b/docs/drools/Tut_vFW_policy_operation_success.JPG Binary files differdeleted file mode 100755 index 8e4b8e18..00000000 --- a/docs/drools/Tut_vFW_policy_operation_success.JPG +++ /dev/null diff --git a/docs/drools/Tut_vFW_simulated_appc_response.JPG b/docs/drools/Tut_vFW_simulated_appc_response.JPG Binary files differdeleted file mode 100755 index 8ceb89cf..00000000 --- a/docs/drools/Tut_vFW_simulated_appc_response.JPG +++ /dev/null diff --git a/docs/drools/Tut_vFW_simulated_onset.JPG b/docs/drools/Tut_vFW_simulated_onset.JPG Binary files differdeleted file mode 100755 index b6d40113..00000000 --- a/docs/drools/Tut_vFW_simulated_onset.JPG +++ /dev/null diff --git a/docs/drools/clsimulation.rst b/docs/drools/clsimulation.rst deleted file mode 100644 index 10276762..00000000 --- a/docs/drools/clsimulation.rst +++ /dev/null @@ -1,946 +0,0 @@ - -.. 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 - -This section will cover how to interact with the PDP-D using telemetry commands. This assumes that you have a PDP-D running to interact with. Take a look at the page "Methods to run PDP-D" if you do not have a PDP-D running for testing purposes. - -Telemetry -^^^^^^^^^ -The username and password for the Telemetry commands are in *${POLICY_HOME}/config/engine.properties*. -If you are using Eclipse, the credentials can be found in the file **install-drools/src/files/base.conf** within the "drools-pdp" repository. -The environment variables $TELEMETRY_USER and $TELEMETRY_PASSWORD will also have the credentials if they have already been set. - -Recall you can use the command "docker exec -it drools bash" to get the PDP-D running with Docker. - - .. code-block:: bash - - docker exec -it drools bash - -Your terminal should now look similar to "policy@drools:/<path>". This indicates you are in the drools docker container. If you run "policy status" the controller should be running. - - .. image:: img/docker/policyStatus.png - -To enter the telemetry subshell, use the command "telemetry". - - .. code-block:: bash - - telemetry - -Use the "exit" command to exit the telemetry subshell. The terminal will now go back to the docker container. - - .. code-block:: bash - - exit - - .. image:: img/docker/credentials.png - -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/<comm>/<topic>/events @<onsetFile> Content-Type:"text/plain" - -The equivalent "curl" version: - - .. 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/<comm>/<topic>/events - -Note: you may have to replace "https" with "http" depending on how you are running the drools-pdp. - -The <comm> is a messaging communication infrastructure in an ONAP installation. Depending on how a topic has been defined in the configuration, the <comm> is either "dmaap", "ueb", or "noop". -The default messaging communication infrastructure is "dmaap". - -The <topic> is a specific topic name used to send and/or receive information. There are two types of topics: - -1. **source** topics (Example: dmaap.source.topics=APPC-LCM-WRITE or dmaap.source.topics=APPC-CL) - -2. **sink** topics (Example: dmaap.sink.topics=APPC-LCM-READ or dmaap.sink.topics=APPC-CL) - -You can extract <comm> and <topic> from the following example: -Example: dmaap.sink.topics=APPC-LCM-READ - -1. <comm>=dmaap - -2. <topic>=APPC-LCM-READ - -The onset is a json file that contains the data to inject as the onset. The data contained depends on the use case. This is an example for the vFirewall usecase: - - .. code-block:: json - :caption: vFirewall_Sample_Onset - - { - "closedLoopControlName": "ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a", - "closedLoopAlarmStart": 1463679805324, - "closedLoopEventClient": "microservice.stringmatcher", - "closedLoopEventStatus": "ONSET", - "requestID": "c7c6a4aa-bb61-4a15-b831-ba1472dd4a65", - "target_type": "VNF", - "target": "generic-vnf.vnf-name", - "AAI": { - "vserver.is-closed-loop-disabled": "false", - "vserver.prov-status": "ACTIVE", - "generic-vnf.vnf-name": "fw0002vm002fw002", - "vserver.vserver-name": "OzVServer" - }, - "from": "DCAE", - "version": "1.0.2" - } - -Getting Information -------------------- - -To get the name(s) 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 - - # Example output when running PDP-D with Docker: - - policy@drools:/opt/app/policy/config$ echo $TELEMETRY_USER - - demo@people.osaaf.org - - policy@drools:/opt/app/policy/config$ echo $TELEMETRY_PASSWORD - - demo123456! - - policy@drools:/opt/app/policy/config$ curl --insecure --silent --user demo@people.osaaf.org:demo123456! -X GET https://localhost:9696/policy/pdp/engine/controllers | python -m json.tool - [ - "frankfurt", - "usecases" - ] - -To check the facts currently in working memory, use the following command. - - .. code-block:: bash - - curl --insecure --silent --user <username>:<password> -X GET https://localhost:9696/policy/pdp/engine/controllers/<controllerName>/drools/facts | python -m json.tool - - # Example output: - - policy@drools:/opt/app/policy/config$ curl --insecure --silent --user demo@people.osaaf.org:demo123456! -X GET https://localhost:9696/policy/pdp/engine/controllers/frankfurt/drools/facts/ | python -m json.tool - { - "frankfurt": 0 - } - policy@drools:/opt/app/policy/config$ curl --insecure --silent --user demo@people.osaaf.org:demo123456! -X GET https://localhost:9696/policy/pdp/engine/controllers/usecases/drools/facts/ | python -m json.tool - { - "usecases": 0 - } - -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 - - # Example output: - - policy@drools:/opt/app/policy/config$ curl --insecure --silent --user demo@people.osaaf.org:demo123456! -X GET https://localhost:9696/policy/pdp/engine/controllers/frankfurt/ | python -m json.tool - { - "alive": true, - "name": "frankfurt", - "topicSinks": [ - { - "effectiveTopic": "APPC-CL", - "topicCommInfrastructure": "NOOP", - "servers": [ - "NOOP" - ], - "alive": true, - "topic": "APPC-CL", - "recentEvents": [], - "locked": false - }, - { - "effectiveTopic": "APPC-LCM-READ", - "topicCommInfrastructure": "NOOP", - "servers": [ - "NOOP" - ], - "alive": true, - "topic": "APPC-LCM-READ", - "recentEvents": [], - "locked": false - }, - { - "effectiveTopic": "POLICY-CL-MGT", - "topicCommInfrastructure": "NOOP", - "servers": [ - "NOOP" - ], - "alive": true, - "topic": "POLICY-CL-MGT", - "recentEvents": [], - "locked": false - }, - { - "effectiveTopic": "SDNR-CL", - "topicCommInfrastructure": "NOOP", - "servers": [ - "NOOP" - ], - "alive": true, - "topic": "SDNR-CL", - "recentEvents": [], - "locked": false - }, - { - "effectiveTopic": "DCAE_CL_RSP", - "topicCommInfrastructure": "NOOP", - "servers": [ - "NOOP" - ], - "alive": true, - "topic": "DCAE_CL_RSP", - "recentEvents": [], - "locked": false - } - ], - "drools": { - "sessions": [ - "frankfurt" - ], - "alive": true, - "brained": true, - "groupId": "org.onap.policy.drools-applications.controlloop.common", - "recentSourceEvents": [], - "version": "1.6.0", - "modelClassLoaderHash": -1185895883, - "baseDomainNames": [ - "onap.policies.controlloop.operational.common.Drools", - "onap.policies.controlloop.Operational" - ], - "artifactId": "controller-frankfurt", - "recentSinkEvents": [], - "sessionCoordinates": [ - "org.onap.policy.drools-applications.controlloop.common:controller-frankfurt:1.6.0:frankfurt" - ], - "locked": false - }, - "policyTypes": [ - { - "name": "onap.policies.controlloop.operational.common.Drools", - "version": "1.0.0" - }, - { - "name": "onap.policies.controlloop.Operational", - "version": "1.0.0" - } - ], - "locked": false, - "topicSources": [ - { - "effectiveTopic": "DCAE_TOPIC", - "topicCommInfrastructure": "NOOP", - "servers": [ - "NOOP" - ], - "alive": false, - "topic": "DCAE_TOPIC", - "recentEvents": [], - "locked": false - }, - { - "effectiveTopic": "APPC-CL", - "topicCommInfrastructure": "NOOP", - "servers": [ - "NOOP" - ], - "alive": false, - "topic": "APPC-CL", - "recentEvents": [], - "locked": false - }, - { - "effectiveTopic": "APPC-LCM-WRITE", - "topicCommInfrastructure": "NOOP", - "servers": [ - "NOOP" - ], - "alive": false, - "topic": "APPC-LCM-WRITE", - "recentEvents": [], - "locked": false - }, - { - "effectiveTopic": "SDNR-CL-RSP", - "topicCommInfrastructure": "NOOP", - "servers": [ - "NOOP" - ], - "alive": false, - "topic": "SDNR-CL-RSP", - "recentEvents": [], - "locked": false - } - ] - } - -Within the telemetry subshell, it is easy to get information. Simply navigate to a specific directory using "cd". Use the "get" command to get information. This is a shorter alternatve to using the "curl" requests as shown above. - -To get information about the engine: - - .. image:: img/docker/getEngine.png - -To list the names of the active controllers: - - .. image:: img/docker/getControllers.png - -To get information about the specific "frankfurt" controller: - - .. image:: img/docker/getFrankfurt.png - -To get information about the PDP-D environment: - - .. image:: img/docker/getEnvironment.png - -To get a list of features that are currently enabled: - - .. image:: img/docker/getFeatures.png - -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: - -1. A&AI - localhost:6666 - -2. SO - localhost:6667 - -3. vFC - localhost:6668 - -4. guard - localhost: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 responses 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: "*policy 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 needed. In the Util class, there are six methods to start the six different simulators: *buildAaiSim()*, *buildSoSim()*, *buildVfcSim()*, *buildGuardSim()*, *buildSdnc()*, and *buildDmaap()*. 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()*. - -Sample 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 diff --git a/docs/drools/drools.rst b/docs/drools/drools.rst index a7705b0f..ccbad75a 100644 --- a/docs/drools/drools.rst +++ b/docs/drools/drools.rst @@ -3,12 +3,53 @@ .. _drools-label: Policy Drools PDP Engine ------------------------- +######################## + +.. contents:: + :depth: 1 + +The Drools PDP, aka PDP-D, is the PDP in the Policy Framework that uses the +`Drools BRMS <https://www.drools.org/>`__ to enforce policies. + +The PDP-D functionality has been partitioned into two functional areas: + +- PDP-D Engine. +- PDP-D Applications. + +**PDP-D Engine** + +The PDP-D Engine is the infrastructure that *policy applications* use. +It provides networking services, resource grouping, and diagnostics. + +The PDP-D Engine supports the following Tosca Native Policy Types: + +- onap.policies.native.Drools +- onap.policies.native.drools.Controller + +These types are used to dynamically add and configure new application controllers. + +The PDP-D Engine hosts applications by means of *controllers*. +*Controllers* may support other Tosca Policy Types. The +types supported by the *Control Loop* applications are: + +- onap.policies.controlloop.operational.common.Drools +- onap.policies.controlloop.Operational + + +**PDP-D Applications** + +A PDP-D application, ie. a *controller*, contains references to the +resources that the application needs. These include networked endpoint references, +and maven coordinates. + +*Control Loop* applications are used in ONAP to enforce operational policies. + + +The following guides offer more information in these two functional areas. + .. toctree:: :maxdepth: 2 - droolsFeaturesIndex.rst - droolsTutorialsIndex.rst - + pdpdEngine.rst + pdpdApps.rst -End of Document diff --git a/docs/drools/droolsFeaturesIndex.rst b/docs/drools/droolsFeaturesIndex.rst deleted file mode 100644 index 869bc7af..00000000 --- a/docs/drools/droolsFeaturesIndex.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. 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_clmgt.rst - feature_clfrankfurt.rst - feature_clusecases.rst - feature_eelf.rst - feature_healthcheck.rst - feature_lifecycle.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 deleted file mode 100644 index ae6a2610..00000000 --- a/docs/drools/droolsTutorialsIndex.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -.. _drools-tutorials-label: - -PDP-D Tutorials ----------------- - -.. toctree:: - :maxdepth: 1 - - runningPDPD.rst - runningEclipse.rst - clsimulation.rst - guardpdp.rst - modAAIdata.rst - modTemplate.rst - tutorial_cl.rst - tutorial_vCPE.rst - tutorial_vDNS.rst - tutorial_vFW.rst - - -End of Document diff --git a/docs/drools/feature_activestdbymgmt.rst b/docs/drools/feature_activestdbymgmt.rst index a7c3fb97..1ed655c9 100644 --- a/docs/drools/feature_activestdbymgmt.rst +++ b/docs/drools/feature_activestdbymgmt.rst @@ -2,25 +2,22 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 +.. _feature-asm-label: + ********************************** -Feature: Active/Standby Management +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: @@ -49,7 +46,7 @@ The Drools PDP must be stopped prior to enabling/disabling features and then res Description Details -^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~ Election Algorithm ------------------ @@ -70,7 +67,7 @@ The Standby State Change Handler (*PMStandbyStateChangeHandler* class) extends t 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 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 @@ -86,19 +83,19 @@ 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 + :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 + # 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 diff --git a/docs/drools/feature_clfrankfurt.rst b/docs/drools/feature_clfrankfurt.rst deleted file mode 100644 index 629b3afd..00000000 --- a/docs/drools/feature_clfrankfurt.rst +++ /dev/null @@ -1,37 +0,0 @@ - -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -******************************* -Feature: Control Loop Frankfurt -******************************* - -.. contents:: - :depth: 3 - -Summary -^^^^^^^ - -The "controlloop-frankfurt" feature enables the "frankfurt" controller in a PDP-D. -The "frankfurt" controller supports the official ONAP use cases for Frankfurt. - -.. note:: - This feature is enabled by default vs the usecases controller which will be deprecated. In the Guilin release we will - be renaming this feature back to usecases. - -Usage -^^^^^ - -The feature is enabled by default. The lifecycle "enabled" property can be toggled with -the "features" command line tool. - - .. code-block:: bash - :caption: PDPD Features Command - - policy stop - - features disable controlloop-frankfurt # enable/disable toggles the activation of the feature. - - policy start - -End of Document diff --git a/docs/drools/feature_clmgt.rst b/docs/drools/feature_clmgt.rst deleted file mode 100644 index 63cdb015..00000000 --- a/docs/drools/feature_clmgt.rst +++ /dev/null @@ -1,86 +0,0 @@ - -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -******************************** -Feature: Control Loop Management -******************************** - -.. contents:: - :depth: 3 - -Summary -^^^^^^^ - -The Control Loop Management feature augments the telemetry tooling to allow -introspection of runtime operational policies. - -Usage -^^^^^ - -The feature is enabled by default. The lifecycle "enabled" property can be toggled with -the "features" command line tool. - - .. code-block:: bash - :caption: PDPD Features Command - - policy stop - - features disable controlloop-management # enable/disable toggles the activation of the feature. - - policy start - -The "telemetry" tool can be used to list the control loops and associated Operational Polices at runtime. - - .. code-block:: bash - :caption: PDPD Features Command - - bash-4.4$ telemetry - Version: 1.0.0 - https://localhost:9696/policy/pdp/engine> cd controllers/usecases/drools/facts/usecases/controlloops - https://localhost:9696/policy/pdp/engine/controllers/usecases/drools/facts/usecases/controlloops> get - HTTP/1.1 200 OK - Content-Length: 132 - Content-Type: application/json - Date: Mon, 03 Jun 2019 20:23:38 GMT - Server: Jetty(9.4.14.v20181114) - - [ - "LOOP_vLoadBalancerMS_v3_0_vLoadBalancerMS0_k8s-tca-clamp-policy-05162019", - "ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e" - ] - - https://localhost:9696/policy/pdp/engine/controllers/usecases/drools/facts/usecases/controlloops> get ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e/policy - HTTP/1.1 200 OK - Content-Length: 612 - Content-Type: text/plain - Date: Mon, 03 Jun 2019 20:23:58 GMT - Server: Jetty(9.4.14.v20181114) - - controlLoop: - version: 2.0.0 - controlLoopName: ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e - trigger_policy: unique-policy-id-1-restart - timeout: 3600 - abatement: true - - policies: - - id: unique-policy-id-1-restart - name: Restart the VM - description: - actor: APPC - recipe: Restart - target: - type: VM - retry: 3 - timeout: 1200 - success: final_success - failure: final_failure - failure_timeout: final_failure_timeout - failure_retries: final_failure_retries - failure_exception: final_failure_exception - failure_guard: final_failure_guard - - https://localhost:9696/policy/pdp/engine/controllers/usecases/drools/facts/usecases/controlloops> - -End of Document diff --git a/docs/drools/feature_clusecases.rst b/docs/drools/feature_clusecases.rst deleted file mode 100644 index ae6fae5c..00000000 --- a/docs/drools/feature_clusecases.rst +++ /dev/null @@ -1,38 +0,0 @@ - -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -******************************* -Feature: Control Loop Use Cases -******************************* - -.. contents:: - :depth: 3 - -Summary -^^^^^^^ - -The "controlloop-usecases" feature enables the "usecases" controller in a PDP-D. -The "usecases" controller is carried forward from the El Alto release and will be deprecated in favor of the -"frankfurt" controller. - -.. note:: - This feature is disabled by default. Please use the 'frankfurt' feature in lieu of this. We will be renaming the 'frankfurt' - controller feature back to use cases in the Guilin release. - -Usage -^^^^^ - -The feature is disabled by default. The lifecycle "enabled" property can be toggled with -the "features" command line tool. - - .. code-block:: bash - :caption: PDPD Features Command - - policy stop - - features disable controlloop-usecases # enable/disable toggles the activation of the feature. - - policy start - -End of Document diff --git a/docs/drools/feature_controllerlogging.rst b/docs/drools/feature_controllerlogging.rst index 0677030e..561c2be7 100644 --- a/docs/drools/feature_controllerlogging.rst +++ b/docs/drools/feature_controllerlogging.rst @@ -9,13 +9,8 @@ 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 diff --git a/docs/drools/feature_eelf.rst b/docs/drools/feature_eelf.rst index 7daeb76d..a505490c 100644 --- a/docs/drools/feature_eelf.rst +++ b/docs/drools/feature_eelf.rst @@ -3,14 +3,12 @@ .. http://creativecommons.org/licenses/by/4.0 ************************************************* -Feature: EELF (Event and Error Logging Framework) +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`_. @@ -18,9 +16,6 @@ The EELF feature provides backwards compatibility with R0 logging functionality. .. _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 diff --git a/docs/drools/feature_healthcheck.rst b/docs/drools/feature_healthcheck.rst deleted file mode 100644 index a0793e92..00000000 --- a/docs/drools/feature_healthcheck.rst +++ /dev/null @@ -1,117 +0,0 @@ - -.. 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_lifecycle.rst b/docs/drools/feature_lifecycle.rst deleted file mode 100644 index ca892131..00000000 --- a/docs/drools/feature_lifecycle.rst +++ /dev/null @@ -1,39 +0,0 @@ - -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -****************** -Feature: Lifecycle -****************** - -.. contents:: - :depth: 3 - -Summary -^^^^^^^ - -The "lifecycle" feature enables a PDP-D to work with the Dublin Release Policy architectural framework. - -The lifecycle feature maintains three states: TERMINATED, PASSIVE, and ACTIVE. -The PAP (Dublin style) interacts with the lifecycle feature to put a PDP-D in PASSIVE or ACTIVE states. -The PASSIVE state allows for Tosca Operational policies to be deployed. -Policy execution is enabled when the PDP-D transitions to the ACTIVE state. - -This feature can coexist side by side with the legacy mode of operation that predates the Dublin release. - -Usage -^^^^^ - -The feature is enabled by default. -The lifecycle "enabled" property can be toggled with the "features" command line tool available in PDP-D containers. - - .. code-block:: bash - :caption: PDPD Features Command - - policy stop - - features disable lifecycle # enable/disable toggles the activation of the feature. - - policy start - -End of Document diff --git a/docs/drools/feature_locking.rst b/docs/drools/feature_locking.rst deleted file mode 100644 index 1236c93f..00000000 --- a/docs/drools/feature_locking.rst +++ /dev/null @@ -1,47 +0,0 @@ - -.. 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 index b0f5543d..df779401 100644 --- a/docs/drools/feature_mdcfilters.rst +++ b/docs/drools/feature_mdcfilters.rst @@ -9,13 +9,8 @@ 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 @@ -26,7 +21,7 @@ Before enabling the feature, the network log contains the entire content of each 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: @@ -63,7 +58,7 @@ This filter is specifying that the dmaap source topic *DCAE-CL* will search each 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: @@ -81,7 +76,7 @@ Now when the filter is searching for closedLoopControlName it will check the fir 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: @@ -105,7 +100,7 @@ The "value" portion consists of two headers in bracket notation, the first heade 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: diff --git a/docs/drools/feature_pooling.rst b/docs/drools/feature_pooling.rst index f7d3579d..ba950a3d 100644 --- a/docs/drools/feature_pooling.rst +++ b/docs/drools/feature_pooling.rst @@ -2,13 +2,12 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 + .. _feature-pool: + **************** 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: @@ -16,7 +15,7 @@ The pool is adjusted automatically, with no manual intervention when: * 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 @@ -25,7 +24,7 @@ Assumptions and Limitations 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 @@ -38,7 +37,8 @@ Key Points * 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 @@ -51,7 +51,8 @@ Example Scenario .. 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 @@ -62,7 +63,7 @@ Bucket Reassignment .. image:: poolingBuckets.png Usage -^^^^^ +===== For pooling to be enabled, the distributed-locking feature must be also be enabled. diff --git a/docs/drools/feature_statemgmt.rst b/docs/drools/feature_statemgmt.rst index 960ff396..29497003 100644 --- a/docs/drools/feature_statemgmt.rst +++ b/docs/drools/feature_statemgmt.rst @@ -2,15 +2,15 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 +.. _feature-sm-label: + ************************* -Feature: State Management +Feature: State Management ************************* .. contents:: :depth: 2 -Summary -^^^^^^^ The State Management Feature provides: - Node-level health monitoring @@ -24,11 +24,9 @@ The State Management Feature provides: - 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: @@ -56,34 +54,34 @@ The Drools PDP must be stopped prior to enabling/disabling features and then res 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 + - 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 @@ -93,13 +91,13 @@ The state model follows the ITU X.731 standard for state management. The suppor - 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 @@ -110,7 +108,7 @@ The state model follows the ITU X.731 standard for state management. The suppor - The transition from ProvidingService to HotStandby is triggered by a Demote operation Database --------- +~~~~~~~~ The State Management feature creates a StateManagement database having three tables: @@ -130,7 +128,7 @@ The State Management feature creates a StateManagement database having three tab - **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 @@ -141,16 +139,16 @@ The State Management feature creates a StateManagement database having three tab - **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. - + + 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** @@ -177,9 +175,9 @@ Node Health Monitoring 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 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. @@ -189,33 +187,33 @@ The following is from the README file included with the Site Manager. 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' @@ -223,7 +221,7 @@ 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}}. @@ -235,7 +233,7 @@ The feature-state-mangement.properties file controls the function of the State M 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 @@ -244,9 +242,9 @@ The feature-state-mangement.properties file controls the function of the State M # 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 @@ -259,9 +257,9 @@ The feature-state-mangement.properties file controls the function of the State M 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 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. + # 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= @@ -270,18 +268,17 @@ The feature-state-mangement.properties file controls the function of the State M 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 + # 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 + # 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 + # 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. @@ -293,14 +290,14 @@ The feature-state-mangement.properties file controls the function of the State M 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 diff --git a/docs/drools/feature_testtransaction.rst b/docs/drools/feature_testtransaction.rst index 488ee1a5..8bec1421 100644 --- a/docs/drools/feature_testtransaction.rst +++ b/docs/drools/feature_testtransaction.rst @@ -2,6 +2,8 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 +.. _feature-tt-label: + ************************* Feature: Test Transaction ************************* @@ -9,9 +11,6 @@ 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. @@ -20,16 +19,13 @@ The injection of the event triggers the "TT" rule (see *TestTransactionTemplate. 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 * ================================================================================ @@ -38,9 +34,9 @@ Prior to being enabled, the following drools rules need to be appended to the ru * 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. @@ -48,15 +44,15 @@ Prior to being enabled, the following drools rules need to be appended to the ru * 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 @@ -64,9 +60,9 @@ Prior to being enabled, the following drools rules need to be appended to the ru fp.setCounter(0L); insert(fp); end - + rule "TT" - when + when $fp : ForwardProgress() $tt : EventObject(source == "43868e59-d1f3-43c2-bd6f-86f89a61eea5") then diff --git a/docs/drools/guardpdp.rst b/docs/drools/guardpdp.rst deleted file mode 100644 index 0fdb4ab2..00000000 --- a/docs/drools/guardpdp.rst +++ /dev/null @@ -1,153 +0,0 @@ - -.. 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 the guard connection from PDP-D (drools-pdp) to PDP-X (xacml-pdp). 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 (guard.url and guard.jdbc.url) 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/img/docker/credentials.png b/docs/drools/img/docker/credentials.png Binary files differdeleted file mode 100644 index 6fa68498..00000000 --- a/docs/drools/img/docker/credentials.png +++ /dev/null diff --git a/docs/drools/img/docker/dockerComposeDown.png b/docs/drools/img/docker/dockerComposeDown.png Binary files differdeleted file mode 100644 index 057a5197..00000000 --- a/docs/drools/img/docker/dockerComposeDown.png +++ /dev/null diff --git a/docs/drools/img/docker/dockerComposeUp.png b/docs/drools/img/docker/dockerComposeUp.png Binary files differdeleted file mode 100644 index 2bd73aa5..00000000 --- a/docs/drools/img/docker/dockerComposeUp.png +++ /dev/null diff --git a/docs/drools/img/docker/exampleTopics.png b/docs/drools/img/docker/exampleTopics.png Binary files differdeleted file mode 100644 index 17d0a559..00000000 --- a/docs/drools/img/docker/exampleTopics.png +++ /dev/null diff --git a/docs/drools/img/docker/getControllers.png b/docs/drools/img/docker/getControllers.png Binary files differdeleted file mode 100644 index 8d2065b0..00000000 --- a/docs/drools/img/docker/getControllers.png +++ /dev/null diff --git a/docs/drools/img/docker/getEngine.png b/docs/drools/img/docker/getEngine.png Binary files differdeleted file mode 100644 index 9811329a..00000000 --- a/docs/drools/img/docker/getEngine.png +++ /dev/null diff --git a/docs/drools/img/docker/getEnvironment.png b/docs/drools/img/docker/getEnvironment.png Binary files differdeleted file mode 100644 index 0131505a..00000000 --- a/docs/drools/img/docker/getEnvironment.png +++ /dev/null diff --git a/docs/drools/img/docker/getFeatures.png b/docs/drools/img/docker/getFeatures.png Binary files differdeleted file mode 100644 index 9d1239cd..00000000 --- a/docs/drools/img/docker/getFeatures.png +++ /dev/null diff --git a/docs/drools/img/docker/getFrankfurt.png b/docs/drools/img/docker/getFrankfurt.png Binary files differdeleted file mode 100644 index 78df267d..00000000 --- a/docs/drools/img/docker/getFrankfurt.png +++ /dev/null diff --git a/docs/drools/img/docker/policyStatus.png b/docs/drools/img/docker/policyStatus.png Binary files differdeleted file mode 100644 index de8199bd..00000000 --- a/docs/drools/img/docker/policyStatus.png +++ /dev/null diff --git a/docs/drools/img/docker/telemetryCmd.png b/docs/drools/img/docker/telemetryCmd.png Binary files differdeleted file mode 100644 index 7b1f358f..00000000 --- a/docs/drools/img/docker/telemetryCmd.png +++ /dev/null diff --git a/docs/drools/img/docker/yamlClone.png b/docs/drools/img/docker/yamlClone.png Binary files differdeleted file mode 100644 index ecf0f6e6..00000000 --- a/docs/drools/img/docker/yamlClone.png +++ /dev/null diff --git a/docs/drools/img/eclipse/consoleOutputExample.png b/docs/drools/img/eclipse/consoleOutputExample.png Binary files differdeleted file mode 100644 index 9dabb8b0..00000000 --- a/docs/drools/img/eclipse/consoleOutputExample.png +++ /dev/null diff --git a/docs/drools/img/eclipse/importMavenProject.png b/docs/drools/img/eclipse/importMavenProject.png Binary files differdeleted file mode 100644 index 1416b4c2..00000000 --- a/docs/drools/img/eclipse/importMavenProject.png +++ /dev/null diff --git a/docs/drools/img/eclipse/mainAppSelection.png b/docs/drools/img/eclipse/mainAppSelection.png Binary files differdeleted file mode 100644 index f562bf6d..00000000 --- a/docs/drools/img/eclipse/mainAppSelection.png +++ /dev/null diff --git a/docs/drools/img/eclipse/runAsJavaApp.png b/docs/drools/img/eclipse/runAsJavaApp.png Binary files differdeleted file mode 100644 index e1f26186..00000000 --- a/docs/drools/img/eclipse/runAsJavaApp.png +++ /dev/null diff --git a/docs/drools/img/eclipse/selectDirectory.png b/docs/drools/img/eclipse/selectDirectory.png Binary files differdeleted file mode 100644 index c1db03f7..00000000 --- a/docs/drools/img/eclipse/selectDirectory.png +++ /dev/null diff --git a/docs/drools/img/eclipse/selectProjectsToImport.png b/docs/drools/img/eclipse/selectProjectsToImport.png Binary files differdeleted file mode 100644 index 395fdb31..00000000 --- a/docs/drools/img/eclipse/selectProjectsToImport.png +++ /dev/null diff --git a/docs/drools/img/frankfurt_project_explorer.png b/docs/drools/img/frankfurt_project_explorer.png Binary files differdeleted file mode 100644 index 4c1cf13d..00000000 --- a/docs/drools/img/frankfurt_project_explorer.png +++ /dev/null diff --git a/docs/drools/img/frankfurt_project_explorer2.png b/docs/drools/img/frankfurt_project_explorer2.png Binary files differdeleted file mode 100644 index bee1f422..00000000 --- a/docs/drools/img/frankfurt_project_explorer2.png +++ /dev/null diff --git a/docs/drools/mat_add_local_catalog.JPG b/docs/drools/mat_add_local_catalog.JPG Binary files differdeleted file mode 100755 index e71dcc54..00000000 --- a/docs/drools/mat_add_local_catalog.JPG +++ /dev/null diff --git a/docs/drools/mat_amsterdam_controller.JPG b/docs/drools/mat_amsterdam_controller.JPG Binary files differdeleted file mode 100755 index c095082a..00000000 --- a/docs/drools/mat_amsterdam_controller.JPG +++ /dev/null diff --git a/docs/drools/mat_amsterdam_drl.JPG b/docs/drools/mat_amsterdam_drl.JPG Binary files differdeleted file mode 100755 index 01b0126c..00000000 --- a/docs/drools/mat_amsterdam_drl.JPG +++ /dev/null diff --git a/docs/drools/mat_amsterdam_project.JPG b/docs/drools/mat_amsterdam_project.JPG Binary files differdeleted file mode 100755 index 4a494065..00000000 --- a/docs/drools/mat_amsterdam_project.JPG +++ /dev/null diff --git a/docs/drools/mat_archetype_checkparams.png b/docs/drools/mat_archetype_checkparams.png Binary files differdeleted file mode 100755 index 88b67443..00000000 --- a/docs/drools/mat_archetype_checkparams.png +++ /dev/null diff --git a/docs/drools/mat_archetype_params.JPG b/docs/drools/mat_archetype_params.JPG Binary files differdeleted file mode 100755 index bca06360..00000000 --- a/docs/drools/mat_archetype_params.JPG +++ /dev/null diff --git a/docs/drools/mat_archetypes.JPG b/docs/drools/mat_archetypes.JPG Binary files differdeleted file mode 100755 index 87ee3ce4..00000000 --- a/docs/drools/mat_archetypes.JPG +++ /dev/null diff --git a/docs/drools/mat_build_success.JPG b/docs/drools/mat_build_success.JPG Binary files differdeleted file mode 100755 index cd2c2988..00000000 --- a/docs/drools/mat_build_success.JPG +++ /dev/null diff --git a/docs/drools/mat_clean_install.JPG b/docs/drools/mat_clean_install.JPG Binary files differdeleted file mode 100755 index 0a2a5c81..00000000 --- a/docs/drools/mat_clean_install.JPG +++ /dev/null diff --git a/docs/drools/mat_configure.JPG b/docs/drools/mat_configure.JPG Binary files differdeleted file mode 100755 index 0965e679..00000000 --- a/docs/drools/mat_configure.JPG +++ /dev/null diff --git a/docs/drools/mat_console_output.JPG b/docs/drools/mat_console_output.JPG Binary files differdeleted file mode 100755 index 23689fa9..00000000 --- a/docs/drools/mat_console_output.JPG +++ /dev/null diff --git a/docs/drools/mat_error.JPG b/docs/drools/mat_error.JPG Binary files differdeleted file mode 100755 index 565266f6..00000000 --- a/docs/drools/mat_error.JPG +++ /dev/null diff --git a/docs/drools/mat_hello_world.JPG b/docs/drools/mat_hello_world.JPG Binary files differdeleted file mode 100755 index d52e4c75..00000000 --- a/docs/drools/mat_hello_world.JPG +++ /dev/null diff --git a/docs/drools/mat_local_archetypes.png b/docs/drools/mat_local_archetypes.png Binary files differdeleted file mode 100755 index 2172e636..00000000 --- a/docs/drools/mat_local_archetypes.png +++ /dev/null diff --git a/docs/drools/mat_maven_build.JPG b/docs/drools/mat_maven_build.JPG Binary files differdeleted file mode 100755 index 2752a633..00000000 --- a/docs/drools/mat_maven_build.JPG +++ /dev/null diff --git a/docs/drools/mat_maven_project.JPG b/docs/drools/mat_maven_project.JPG Binary files differdeleted file mode 100755 index 3d8efe38..00000000 --- a/docs/drools/mat_maven_project.JPG +++ /dev/null diff --git a/docs/drools/mat_new_project.JPG b/docs/drools/mat_new_project.JPG Binary files differdeleted file mode 100755 index 2deed0d8..00000000 --- a/docs/drools/mat_new_project.JPG +++ /dev/null diff --git a/docs/drools/mat_nexus_catalog.JPG b/docs/drools/mat_nexus_catalog.JPG Binary files differdeleted file mode 100755 index 4240eaa3..00000000 --- a/docs/drools/mat_nexus_catalog.JPG +++ /dev/null diff --git a/docs/drools/mat_nexus_local_catalog.png b/docs/drools/mat_nexus_local_catalog.png Binary files differdeleted file mode 100755 index b12533e8..00000000 --- a/docs/drools/mat_nexus_local_catalog.png +++ /dev/null diff --git a/docs/drools/mat_project_location.JPG b/docs/drools/mat_project_location.JPG Binary files differdeleted file mode 100755 index 34c3cb93..00000000 --- a/docs/drools/mat_project_location.JPG +++ /dev/null diff --git a/docs/drools/mat_run_as.JPG b/docs/drools/mat_run_as.JPG Binary files differdeleted file mode 100755 index d4401b11..00000000 --- a/docs/drools/mat_run_as.JPG +++ /dev/null diff --git a/docs/drools/mat_select_archetypes.png b/docs/drools/mat_select_archetypes.png Binary files differdeleted file mode 100755 index 07991c49..00000000 --- a/docs/drools/mat_select_archetypes.png +++ /dev/null diff --git a/docs/drools/mdc_enablefeature.png b/docs/drools/mdc_enablefeature.png Binary files differindex 26ae55a4..26ae55a4 100755..100644 --- a/docs/drools/mdc_enablefeature.png +++ b/docs/drools/mdc_enablefeature.png diff --git a/docs/drools/modAAI_getAllVserver.PNG b/docs/drools/modAAI_getAllVserver.PNG Binary files differdeleted file mode 100755 index 611992f4..00000000 --- a/docs/drools/modAAI_getAllVserver.PNG +++ /dev/null diff --git a/docs/drools/modAAI_getByVserverName.PNG b/docs/drools/modAAI_getByVserverName.PNG Binary files differdeleted file mode 100755 index 7670ff89..00000000 --- a/docs/drools/modAAI_getByVserverName.PNG +++ /dev/null diff --git a/docs/drools/modAAI_getCloudRegions.png b/docs/drools/modAAI_getCloudRegions.png Binary files differdeleted file mode 100755 index 82fb659c..00000000 --- a/docs/drools/modAAI_getCloudRegions.png +++ /dev/null diff --git a/docs/drools/modAAI_namedQueryVnfId.PNG b/docs/drools/modAAI_namedQueryVnfId.PNG Binary files differdeleted file mode 100755 index 14ca3121..00000000 --- a/docs/drools/modAAI_namedQueryVnfId.PNG +++ /dev/null diff --git a/docs/drools/modAAIdata.rst b/docs/drools/modAAIdata.rst deleted file mode 100644 index eef0d0c4..00000000 --- a/docs/drools/modAAIdata.rst +++ /dev/null @@ -1,127 +0,0 @@ - -.. 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: - 1. Skynet/CL-MR1 - 2. AMIST/AMCR1 - 3. 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/modTemplate.rst b/docs/drools/modTemplate.rst deleted file mode 100644 index 1e02a0c8..00000000 --- a/docs/drools/modTemplate.rst +++ /dev/null @@ -1,131 +0,0 @@ - -.. 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 (https://nexus.onap.org/content/groups/staging/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 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -// TODO Modify for frankfurt - -**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/pdpdApps.rst b/docs/drools/pdpdApps.rst new file mode 100644 index 00000000..331f3ac6 --- /dev/null +++ b/docs/drools/pdpdApps.rst @@ -0,0 +1,879 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +.. _pdpd-apps-label: + +PDP-D Applications +################## + +.. contents:: + :depth: 2 + +Overview +======== + +PDP-D applications uses the PDP-D Engine middleware to provide domain specific services. +See :ref:`pdpd-engine-label` for the description of the PDP-D infrastructure. + +At this time *Control Loops* are the only type of applications supported. + +*Control Loop* applications must support at least one of the following *Policy Types*: + +- **onap.policies.controlloop.Operational** (Operational Policies for Legacy Control Loops) +- **onap.policies.controlloop.operational.common.Drools** (Tosca Compliant Operational Policies) + +Software +======== + +Source Code repositories +~~~~~~~~~~~~~~~~~~~~~~~~ + +The PDP-D Applications software resides on the `policy/drools-applications <https://git.onap.org/policy/drools-applications>`__ repository. The actor libraries introduced in the *frankfurt* release reside in +the `policy/models repository <https://git.onap.org/policy/models>`__. + +At this time, the *control loop* application is the only application supported in ONAP. +All the application projects reside under the +`controlloop directory <https://git.onap.org/policy/drools-applications/tree/controlloop>`__. + +Docker Image +~~~~~~~~~~~~ + +See the *drools-applications* +`released versions <https://wiki.onap.org/display/DW/Policy+Framework+Project%3A+Component+Versions>`__ +for the latest images: + +.. code-block:: bash + + docker pull onap/policy-pdpd-cl:1.6.4 + +At the time of this writing *1.6.4* is the latest version. + +The *onap/policy-pdpd-cl* image extends the *onap/policy-drools* image with +the *frankfurt* controller that realizes the *control loop* application. + +Frankfurt Controller +==================== + +The `frankfurt <https://git.onap.org/policy/drools-applications/tree/controlloop/common/controller-frankfurt>`__ +controller is the *control loop* application in ONAP. + +There are three parts in this controller: + +* The `drl rules <https://git.onap.org/policy/drools-applications/tree/controlloop/common/controller-frankfurt/src/main/resources/frankfurt.drl>`__. +* The `kmodule.xml <https://git.onap.org/policy/drools-applications/tree/controlloop/common/controller-frankfurt/src/main/resources/META-INF/kmodule.xml>`__. +* The `dependencies <https://git.onap.org/policy/drools-applications/tree/controlloop/common/controller-frankfurt/pom.xml>`__. + +The `kmodule.xml` specifies only one session, and declares in the *kbase* section the two operational policy types that +it supports. + +The Frankfurt controller relies on the new Actor framework to interact with remote +components, part of a control loop transaction. The reader is referred to the +*Policy Platform Actor Development Guidelines* in the documentation for further information. + +Operational Policy Types +======================== + +The *frankfurt* controller supports the two Operational policy types: + +- *onap.policies.controlloop.Operational*. +- *onap.policies.controlloop.operational.common.Drools*. + +The *onap.policies.controlloop.Operational* is the legacy operational type, used before +the *frankfurt* release. The *onap.policies.controlloop.operational.common.Drools* +is the Tosca compliant policy type introduced in *frankfurt*. + +The legacy operational policy type is defined at the +`onap.policies.controlloop.Operational.yaml <https://git.onap.org/policy/models/tree/models-examples/src/main/resources/policytypes/onap.policies.controlloop.Operational.yaml>`__. + +The Tosca Compliant Operational Policy Type is defined at the +`onap.policies.controlloop.operational.common.Drools <https://git.onap.org/policy/models/tree/models-examples/src/main/resources/policytypes/onap.policies.controlloop.operational.common.Drools.yaml>`__. + +An example of a Legacy Operational Policy can be found +`here <https://git.onap.org/policy/models/tree/models-examples/src/main/resources/policies/vDNS.policy.operational.legacy.input.json>`__. + +An example of a Tosca Compliant Operational Policy can be found +`here <https://git.onap.org/policy/models/tree/models-examples/src/main/resources/policies/vDNS.policy.operational.input.tosca.json>`__. + +Features +======== + +Since the PDP-D Control Loop Application image was created from the PDP-D Engine one (*onap/policy-drools*), +it inherits all features and functionality. + +The enabled features in the *onap/policy-pdpd-cl* image are: + +- **distributed locking**: distributed resource locking. +- **healthcheck**: healthcheck. +- **lifecycle**: enables the lifecycle APIs. +- **controlloop-trans**: control loop transaction tracking. +- **controlloop-management**: generic controller capabilities. +- **controlloop-frankfurt**: new *controller* introduced in the frankfurt release to realize the ONAP use cases. + +The following features are installed but disabled: + +- **controlloop-usecases**: *controller* used pre-frankfurt releases. +- **controlloop-utils**: *actor* simulators. + +Control Loops Transaction (controlloop-trans) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It tracks Control Loop Transactions and Operations. These are recorded in +the *$POLICY_LOGS/audit.log* and *$POLICY_LOGS/metrics.log*, and accessible +through the telemetry APIs. + +Control Loops Management (controlloop-management) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It installs common control loop application resources, and provides +telemetry API extensions. *Actor* configurations are packaged in this +feature. + +Frankfurt Controller (controlloop-frankfurt) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is the *frankfurt* release implementation of the ONAP use cases. +It relies on the new *Actor* model framework to carry out a policy's +execution. + +Usecases Controller (controlloop-usecases) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is the deprecated pre-frankfurt controller. + +Utilities (controlloop-utils) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enables *actor simulators* for testing purposes. + +Offline Mode +============ + +The default ONAP installation in *onap/policy-pdpd-cl:1.6.4* is *OFFLINE*. +In this configuration, the *rules* artifact and the *dependencies* are all in the local +maven repository. This requires that the maven dependencies are preloaded in the local +repository. + +An offline configuration requires two configuration items: + +- *OFFLINE* environment variable set to true (see `values.yaml <https://git.onap.org/oom/tree/kubernetes/policy/values.yaml>`__. +- override of the default *settings.xml* (see + `settings.xml <https://git.onap.org/oom/tree/kubernetes/policy/charts/drools/resources/configmaps/settings.xml>`__) override. + +Running the PDP-D Control Loop Application in a single container +================================================================ + +Environment File +~~~~~~~~~~~~~~~~ + +First create an environment file (in this example *env.conf*) to configure the PDP-D. + +.. code-block:: bash + + # SYSTEM software configuration + + POLICY_HOME=/opt/app/policy + POLICY_LOGS=/var/log/onap/policy/pdpd + KEYSTORE_PASSWD=Pol1cy_0nap + TRUSTSTORE_PASSWD=Pol1cy_0nap + + # Telemetry credentials + + TELEMETRY_PORT=9696 + TELEMETRY_HOST=0.0.0.0 + TELEMETRY_USER=demo@people.osaaf.org + TELEMETRY_PASSWORD=demo123456! + + # nexus repository + + SNAPSHOT_REPOSITORY_ID= + SNAPSHOT_REPOSITORY_URL= + RELEASE_REPOSITORY_ID= + RELEASE_REPOSITORY_URL= + REPOSITORY_USERNAME= + REPOSITORY_PASSWORD= + REPOSITORY_OFFLINE=true + + MVN_SNAPSHOT_REPO_URL= + MVN_RELEASE_REPO_URL= + + # Relational (SQL) DB access + + SQL_HOST= + SQL_USER= + SQL_PASSWORD= + + # AAF + + AAF=false + AAF_NAMESPACE=org.onap.policy + AAF_HOST=aaf.api.simpledemo.onap.org + + # PDP-D DMaaP configuration channel + + PDPD_CONFIGURATION_TOPIC=PDPD-CONFIGURATION + PDPD_CONFIGURATION_API_KEY= + PDPD_CONFIGURATION_API_SECRET= + PDPD_CONFIGURATION_CONSUMER_GROUP= + PDPD_CONFIGURATION_CONSUMER_INSTANCE= + PDPD_CONFIGURATION_PARTITION_KEY= + + # PAP-PDP configuration channel + + POLICY_PDP_PAP_TOPIC=POLICY-PDP-PAP + POLICY_PDP_PAP_GROUP=defaultGroup + + # Symmetric Key for encoded sensitive data + + SYMM_KEY= + + # Healthcheck Feature + + HEALTHCHECK_USER=demo@people.osaaf.org + HEALTHCHECK_PASSWORD=demo123456! + + # Pooling Feature + + POOLING_TOPIC=POOLING + + # PAP + + PAP_HOST= + PAP_USERNAME= + PAP_PASSWORD= + + # PAP legacy + + PAP_LEGACY_USERNAME= + PAP_LEGACY_PASSWORD= + + # PDP-X + + PDP_HOST=localhost + PDP_PORT=6669 + PDP_CONTEXT_URI=pdp/api/getDecision + PDP_USERNAME=policy + PDP_PASSWORD=password + GUARD_DISABLED=true + + # DCAE DMaaP + + DCAE_TOPIC=unauthenticated.DCAE_CL_OUTPUT + DCAE_SERVERS=localhost + DCAE_CONSUMER_GROUP=dcae.policy.shared + + # Open DMaaP + + DMAAP_SERVERS=localhost + + # AAI + + AAI_HOST=localhost + AAI_PORT=6666 + AAI_CONTEXT_URI= + AAI_USERNAME=policy + AAI_PASSWORD=policy + + # SO + + SO_HOST=localhost + SO_PORT=6667 + SO_CONTEXT_URI= + SO_URL=https://localhost:6667/ + SO_USERNAME=policy + SO_PASSWORD=policy + + # VFC + + VFC_HOST=localhost + VFC_PORT=6668 + VFC_CONTEXT_URI=api/nslcm/v1/ + VFC_USERNAME=policy + VFC_PASSWORD=policy + + # SDNC + + SDNC_HOST=localhost + SDNC_PORT=6670 + SDNC_CONTEXT_URI=restconf/operations/ + +Configuration +~~~~~~~~~~~~~ + +noop.pre.sh +""""""""""" + +In order to avoid the noise in the logs that relate to dmaap configuration, a startup script (*noop.pre.sh*) is added +to convert *dmaap* endpoints to *noop* in the host directory to be mounted. + +.. code-block:: bash + + #!/bin/bash -x + + sed -i "s/^dmaap/noop/g" $POLICY_HOME/config/*.properties + +features.pre.sh +""""""""""""""" + +We can enable the *controlloop-utils* and disable the *distributed-locking* feature to avoid using the database. + +.. code-block:: bash + + #!/bin/bash -x + + bash -c "/opt/app/policy/bin/features disable distributed-locking" + bash -c "/opt/app/policy/bin/features enable controlloop-utils" + +active.post.sh +"""""""""""""" + +The *active.post.sh* script makes the PDP-D active. + +.. code-block:: bash + + #!/bin/bash -x + + bash -c "http --verify=no -a ${TELEMETRY_USER}:${TELEMETRY_PASSWORD} PUT https://localhost:9696/policy/pdp/engine/lifecycle/state/ACTIVE" + +Actor Properties +"""""""""""""""" + +In the *frankfurt* release, some *actors* configurations need to be overridden to support *http* for compatibility +with the *controlloop-utils* feature. + +AAI-http-client.properties +"""""""""""""""""""""""""" + +.. code-block:: bash + + http.client.services=AAI + + http.client.services.AAI.managed=true + http.client.services.AAI.https=false + http.client.services.AAI.host=${envd:AAI_HOST} + http.client.services.AAI.port=${envd:AAI_PORT} + http.client.services.AAI.userName=${envd:AAI_USERNAME} + http.client.services.AAI.password=${envd:AAI_PASSWORD} + http.client.services.AAI.contextUriPath=${envd:AAI_CONTEXT_URI} + +SDNC-http-client.properties +""""""""""""""""""""""""""" + +.. code-block:: bash + + http.client.services=SDNC + + http.client.services.SDNC.managed=true + http.client.services.SDNC.https=false + http.client.services.SDNC.host=${envd:SDNC_HOST} + http.client.services.SDNC.port=${envd:SDNC_PORT} + http.client.services.SDNC.userName=${envd:SDNC_USERNAME} + http.client.services.SDNC.password=${envd:SDNC_PASSWORD} + http.client.services.SDNC.contextUriPath=${envd:SDNC_CONTEXT_URI} + +VFC-http-client.properties +"""""""""""""""""""""""""" + +.. code-block:: bash + + http.client.services=VFC + + http.client.services.VFC.managed=true + http.client.services.VFC.https=false + http.client.services.VFC.host=${envd:VFC_HOST} + http.client.services.VFC.port=${envd:VFC_PORT} + http.client.services.VFC.userName=${envd:VFC_USERNAME} + http.client.services.VFC.password=${envd:VFC_PASSWORD} + http.client.services.VFC.contextUriPath=${envd:VFC_CONTEXT_URI:api/nslcm/v1/} + +settings.xml +"""""""""""" + +The *standalone-settings.xml* file is the default maven settings override in the container. + +.. code-block:: bash + + <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> + + <offline>true</offline> + + <profiles> + <profile> + <id>policy-local</id> + <repositories> + <repository> + <id>file-repository</id> + <url>file:${user.home}/.m2/file-repository</url> + <releases> + <enabled>true</enabled> + <updatePolicy>always</updatePolicy> + </releases> + <snapshots> + <enabled>true</enabled> + <updatePolicy>always</updatePolicy> + </snapshots> + </repository> + </repositories> + </profile> + </profiles> + + <activeProfiles> + <activeProfile>policy-local</activeProfile> + </activeProfiles> + + </settings> + +Bring up the PDP-D Control Loop Application +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + docker run --rm -p 9696:9696 -v ${PWD}/config:/tmp/policy-install/config --env-file ${PWD}/env/env.conf -it --name PDPD -h pdpd nexus3.onap.org:10001/onap/policy-pdpd-cl:1.6.4 + +To run the container in detached mode, add the *-d* flag. + +Note that we are opening the *9696* telemetry API port to the outside world, mounting the *config* host directory, +and setting environment variables. + +To open a shell into the PDP-D: + +.. code-block:: bash + + docker exec -it pdp-d bash + +Once in the container, run tools such as *telemetry*, *db-migrator*, *policy* to look at the system state: + +.. code-block:: bash + + docker exec -it PDPD bash -c "/opt/app/policy/bin/telemetry" + docker exec -it PDPD bash -c "/opt/app/policy/bin/policy status" + docker exec -it PDPD bash -c "/opt/app/policy/bin/db-migrator -s ALL -o report" + +Controlled instantiation of the PDP-D Control Loop Appplication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes a developer may want to start and stop the PDP-D manually: + +.. code-block:: bash + + # start a bash + + docker run --rm -p 9696:9696 -v ${PWD}/config:/tmp/policy-install/config --env-file ${PWD}/env/env.conf -it --name PDPD -h pdpd nexus3.onap.org:10001/onap/policy-pdpd-cl:1.6.4 bash + + # use this command to start policy applying host customizations from /tmp/policy-install/config + + pdpd-cl-entrypoint.sh vmboot + + # or use this command to start policy without host customization + + policy start + + # at any time use the following command to stop the PDP-D + + policy stop + + # and this command to start the PDP-D back again + + policy start + +Scale-out use case testing +========================== + +First step is to create the *operational.scaleout* policy. + +policy.vdns.json +~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + { + "type": "onap.policies.controlloop.operational.common.Drools", + "type_version": "1.0.0", + "name": "operational.scaleout", + "version": "1.0.0", + "metadata": { + "policy-id": "operational.scaleout" + }, + "properties": { + "id": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3", + "timeout": 60, + "abatement": false, + "trigger": "unique-policy-id-1-scale-up", + "operations": [ + { + "id": "unique-policy-id-1-scale-up", + "description": "Create a new VF Module", + "operation": { + "actor": "SO", + "operation": "VF Module Create", + "target": { + "targetType": "VFMODULE", + "entityIds": { + "modelInvariantId": "e6130d03-56f1-4b0a-9a1d-e1b2ebc30e0e", + "modelVersionId": "94b18b1d-cc91-4f43-911a-e6348665f292", + "modelName": "VfwclVfwsnkBbefb8ce2bde..base_vfw..module-0", + "modelVersion": 1, + "modelCustomizationId": "47958575-138f-452a-8c8d-d89b595f8164" + } + }, + "payload": { + "requestParameters": "{\"usePreload\":true,\"userParams\":[]}", + "configurationParameters": "[{\"ip-addr\":\"$.vf-module-topology.vf-module-parameters.param[9]\",\"oam-ip-addr\":\"$.vf-module-topology.vf-module-parameters.param[16]\",\"enabled\":\"$.vf-module-topology.vf-module-parameters.param[23]\"}]" + } + }, + "timeout": 20, + "retries": 0, + "success": "final_success", + "failure": "final_failure", + "failure_timeout": "final_failure_timeout", + "failure_retries": "final_failure_retries", + "failure_exception": "final_failure_exception", + "failure_guard": "final_failure_guard" + } + ] + } + } + +To provision the *scale-out policy*, issue the following command: + +.. code-block:: bash + + http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" https://localhost:9696/policy/pdp/engine/lifecycle/policies @usecases/policy.vdns.json + +Verify that the policy shows with the telemetry tools: + +.. code-block:: bash + + docker exec -it PDPD bash -c "/opt/app/policy/bin/telemetry" + > get /policy/pdp/engine/lifecycle/policies + > get /policy/pdp/engine/controllers/frankfurt/drools/facts/frankfurt/controlloops + + +dcae.vdns.onset.json +~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + { + "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3", + "closedLoopAlarmStart": 1463679805324, + "closedLoopEventClient": "microservice.stringmatcher", + "closedLoopEventStatus": "ONSET", + "requestID": "c7c6a4aa-bb61-4a15-b831-ba1472dd4a65", + "target_type": "VNF", + "target": "vserver.vserver-name", + "AAI": { + "vserver.is-closed-loop-disabled": "false", + "vserver.prov-status": "ACTIVE", + "vserver.vserver-name": "OzVServer" + }, + "from": "DCAE", + "version": "1.0.2" + } + +To initiate a control loop transaction, simulate a DCAE ONSET to Policy: + +.. code-block:: bash + + http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/DCAE_TOPIC/events @dcae.vdns.onset.json Content-Type:'text/plain' + +This will trigger the scale out control loop transaction that will interact with the *SO* +simulator to complete the transaction. + +Verify in *$POLICY_LOGS/network.log* that a *FINAL: SUCCESS* notification is sent over the POLICY-CL-MGT channel. +An entry in the *$POLICY_LOGS/audit.log* should indicate successful completion as well. + +vCPE use case testing +===================== + +First step is to create the *operational.restart* policy. + +policy.vcpe.json +~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + { + "type": "onap.policies.controlloop.operational.common.Drools", + "type_version": "1.0.0", + "name": "operational.restart", + "version": "1.0.0", + "metadata": { + "policy-id": "operational.restart" + }, + "properties": { + "id": "ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e", + "timeout": 300, + "abatement": false, + "trigger": "unique-policy-id-1-restart", + "operations": [ + { + "id": "unique-policy-id-1-restart", + "description": "Restart the VM", + "operation": { + "actor": "APPC", + "operation": "Restart", + "target": { + "targetType": "VNF" + } + }, + "timeout": 240, + "retries": 0, + "success": "final_success", + "failure": "final_failure", + "failure_timeout": "final_failure_timeout", + "failure_retries": "final_failure_retries", + "failure_exception": "final_failure_exception", + "failure_guard": "final_failure_guard" + } + ] + } + } + +To provision the *operational.restart policy* issue the following command: + +.. code-block:: bash + + http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" https://localhost:9696/policy/pdp/engine/lifecycle/policies @usecases/policy.vcpe.json + +Verify that the policy shows with the telemetry tools: + +.. code-block:: bash + + docker exec -it PDPD bash -c "/opt/app/policy/bin/telemetry" + > get /policy/pdp/engine/lifecycle/policies + > get /policy/pdp/engine/controllers/frankfurt/drools/facts/frankfurt/controlloops + + +dcae.vcpe.onset.json +~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + { + "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" + } + +To initiate a control loop transaction, simulate a DCAE ONSET to Policy: + +.. code-block:: bash + + http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/DCAE_TOPIC/events @dcae.vcpe.onset.json Content-Type:'text/plain' + +This will spawn a vCPE control loop transaction in the PDP-D. Policy will send a *restart* message over the +*APPC-LCM-READ* channel to APPC and wait for a response. + +Verify that you see this message in the network.log by looking for *APPC-LCM-READ* messages. + +Note the *sub-request-id* value from the restart message in the *APPC-LCM-READ* channel. + +Replace *REPLACEME* in the *appc.vcpe.success.json* with this sub-request-id. + +appc.vcpe.success.json +~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + { + "body": { + "output": { + "common-header": { + "timestamp": "2017-08-25T21:06:23.037Z", + "api-ver": "5.00", + "originator-id": "664be3d2-6c12-4f4b-a3e7-c349acced200", + "request-id": "664be3d2-6c12-4f4b-a3e7-c349acced200", + "sub-request-id": "REPLACEME", + "flags": {} + }, + "status": { + "code": 400, + "message": "Restart Successful" + } + } + }, + "version": "2.0", + "rpc-name": "restart", + "correlation-id": "664be3d2-6c12-4f4b-a3e7-c349acced200-1", + "type": "response" + } + + +Send a simulated APPC response back to the PDP-D over the *APPC-LCM-WRITE* channel. + +.. code-block:: bash + + http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/APPC-LCM-WRITE/events @appc.vcpe.success.json Content-Type:'text/plain' + +Verify in *$POLICY_LOGS/network.log* that a *FINAL: SUCCESS* notification is sent over the *POLICY-CL-MGT* channel, +and an entry is added to the *$POLICY_LOGS/audit.log* indicating successful completion. + +vFirewall use case testing +=========================== + +First step is to create the *operational.modifyconfig* policy. + +policy.vfw.json +~~~~~~~~~~~~~~~ + +.. code-block:: bash + + { + "type": "onap.policies.controlloop.operational.common.Drools", + "type_version": "1.0.0", + "name": "operational.modifyconfig", + "version": "1.0.0", + "metadata": { + "policy-id": "operational.modifyconfig" + }, + "properties": { + "id": "ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a", + "timeout": 300, + "abatement": false, + "trigger": "unique-policy-id-1-modifyConfig", + "operations": [ + { + "id": "unique-policy-id-1-modifyConfig", + "description": "Modify the packet generator", + "operation": { + "actor": "APPC", + "operation": "ModifyConfig", + "target": { + "targetType": "VNF", + "entityIds": { + "resourceID": "bbb3cefd-01c8-413c-9bdd-2b92f9ca3d38" + } + }, + "payload": { + "streams": "{\"active-streams\": 5 }" + } + }, + "timeout": 240, + "retries": 0, + "success": "final_success", + "failure": "final_failure", + "failure_timeout": "final_failure_timeout", + "failure_retries": "final_failure_retries", + "failure_exception": "final_failure_exception", + "failure_guard": "final_failure_guard" + } + ] + } + } + + +To provision the *operational.modifyconfig policy*, issue the following command: + +.. code-block:: bash + + http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" https://localhost:9696/policy/pdp/engine/lifecycle/policies @usecases/policy.vfw.json + +Verify that the policy shows with the telemetry tools: + +.. code-block:: bash + + docker exec -it PDPD bash -c "/opt/app/policy/bin/telemetry" + > get /policy/pdp/engine/lifecycle/policies + > get /policy/pdp/engine/controllers/frankfurt/drools/facts/frankfurt/controlloops + + +dcae.vfw.onset.json +~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + { + "closedLoopControlName": "ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a", + "closedLoopAlarmStart": 1463679805324, + "closedLoopEventClient": "microservice.stringmatcher", + "closedLoopEventStatus": "ONSET", + "requestID": "c7c6a4aa-bb61-4a15-b831-ba1472dd4a65", + "target_type": "VNF", + "target": "generic-vnf.vnf-name", + "AAI": { + "vserver.is-closed-loop-disabled": "false", + "vserver.prov-status": "ACTIVE", + "generic-vnf.vnf-name": "fw0002vm002fw002", + "vserver.vserver-name": "OzVServer" + }, + "from": "DCAE", + "version": "1.0.2" + } + + +To initiate a control loop transaction, simulate a DCAE ONSET to Policy: + +.. code-block:: bash + + http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/DCAE_TOPIC/events @dcae.vfw.onset.json Content-Type:'text/plain' + +This will spawn a vFW control loop transaction in the PDP-D. Policy will send a *ModifyConfig* message over the +*APPC-CL* channel to APPC and wait for a response. This can be seen by searching the network.log for *APPC-CL*. + +Note the *SubRequestId* field in the *ModifyConfig* message in the *APPC-CL* topic in the network.log + +Send a simulated APPC response back to the PDP-D over the *APPC-CL* channel. +To do this, change the *REPLACEME* text in the *appc.vcpe.success.json* with this *SubRequestId*. + +appc.vcpe.success.json +~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + { + "CommonHeader": { + "TimeStamp": 1506051879001, + "APIver": "1.01", + "RequestID": "c7c6a4aa-bb61-4a15-b831-ba1472dd4a65", + "SubRequestID": "REPLACEME", + "RequestTrack": [], + "Flags": [] + }, + "Status": { + "Code": 400, + "Value": "SUCCESS" + }, + "Payload": { + "generic-vnf.vnf-id": "f17face5-69cb-4c88-9e0b-7426db7edddd" + } + } + +.. code-block:: bash + + http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/APPC-CL/events @appc.vcpe.success.json Content-Type:'text/plain' + +Verify in *$POLICY_LOGS/network.log* that a *FINAL: SUCCESS* notification is sent over the POLICY-CL-MGT channel, +and an entry is added to the *$POLICY_LOGS/audit.log* indicating successful completion. + + +Running PDP-D Control Loop Application with other components +============================================================ + +The reader can also look at the `integration/csit repository <https://git.onap.org/integration/csit>`__. +More specifically, these directories have examples of other PDP-D Control Loop configurations: + +* `plans <https://git.onap.org/integration/csit/tree/plans/policy/drools-applications>`__: startup scripts. +* `scripts <https://git.onap.org/integration/csit/tree/scripts/policy/drools-apps/docker-compose-drools-apps.yml>`__: docker-compose and related files. +* `plans <https://git.onap.org/integration/csit/tree/tests/policy/drools-applications>`__: test plan. + +Additional information +====================== + +For additional information, please see the +`Drools PDP Development and Testing (In Depth) <https://wiki.onap.org/display/DW/2020+Frankfurt+Tutorials>`__ page. + + diff --git a/docs/drools/pdpdEngine.rst b/docs/drools/pdpdEngine.rst new file mode 100644 index 00000000..3456cc6d --- /dev/null +++ b/docs/drools/pdpdEngine.rst @@ -0,0 +1,1405 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +.. _pdpd-engine-label: + +PDP-D Engine +############ + +.. contents:: + :depth: 2 + +Overview +======== + +The PDP-D Core Engine provides an infrastructure and services for `drools <https://www.drools.org/>`__ based applications +in the context of Policies and ONAP. + +A PDP-D supports applications by means of *controllers*. A *controller* is a named +grouping of resources. These typically include references to communication endpoints, +maven artifact coordinates, and *coders* for message mapping. + +*Controllers* use *communication endpoints* to interact +with remote networked entities typically using messaging (dmaap or ueb), +or http. + +PDP-D Engine capabilities can be extended via *features*. Integration with other +Policy Framework components (API, PAP, and PDP-X) is through one of them (*feature-lifecycle*). + +The PDP-D Engine infrastructure provides mechanisms for data migration, diagnostics, and application management. + +Software +======== + +Source Code repositories +~~~~~~~~~~~~~~~~~~~~~~~~ + +The PDP-D software is mainly located in the `policy/drools repository <https://git.onap.org/policy/drools-pdp>`__ with the *communication endpoints* software residing in the `policy/common repository <https://git.onap.org/policy/common>`__ and Tosca policy models in the `policy/models repository <https://git.onap.org/policy/models>`__. + +Docker Image +~~~~~~~~~~~~ + +Check the *drools-pdp* `released versions <https://wiki.onap.org/display/DW/Policy+Framework+Project%3A+Component+Versions>`__ page for the latest versions. +At the time of this writing *1.6.3* is the latest version. + +.. code-block:: bash + + docker pull onap/policy-drools:1.6.3 + +A container instantiated from this image will run under the non-priviledged *policy* account. + +The PDP-D root directory is located at the */opt/app/policy* directory (or *$POLICY_HOME*), with the +exception of the *$HOME/.m2* which contains the local maven repository. +The PDP-D configuration resides in the following directories: + +- **/opt/app/policy/config**: (*$POLICY_HOME/config* or *$POLICY_CONFIG*) contains *engine*, *controllers*, and *endpoint* configuration. +- **/home/policy/.m2**: (*$HOME/.m2*) maven repository configuration. +- **/opt/app/policy/etc/**: (*$POLICY_HOME/etc*) miscellaneous configuration such as certificate stores. + +The following command can be used to explore the directory layout. + +.. code-block:: bash + + docker run --rm -it nexus3.onap.org:10001/onap/policy-drools:1.6.3 -- bash + +Communication Endpoints +======================= + +PDP-D supports the following networked infrastructures. This is also referred to as +*communication infrastructures* in the source code. + +- DMaaP +- UEB +- NOOP +- Http Servers +- Http Clients + +The source code is located at +`the policy-endpoints module <https://git.onap.org/policy/common/tree/policy-endpoints>`__ +in the *policy/commons* repository. + +These network resources are *named* and typically have a *global* scope, therefore typically visible to +the PDP-D engine (for administration purposes), application *controllers*, +and *features*. + +DMaaP, UEB, and NOOP are message-based communication infrastructures, hence the terminology of +source and sinks, to denote their directionality into or out of the *controller*, respectively. + +An endpoint can either be *managed* or *unmanaged*. The default for an endpoint is to be *managed*, +meaning that they are globally accessible by name, and managed by the PDP-D engine. +*Unmanaged* topics are used when neither global visibility, or centralized PDP-D management is desired. +The software that uses *unmanaged* topics is responsible for their lifecycle management. + +DMaaP Endpoints +~~~~~~~~~~~~~~~ + +These are messaging enpoints that use DMaaP as the communication infrastructure. + +Typically, a *managed* endpoint configuration is stored in the *<topic-name>-topic.properties* files. + +For example, the +`DCAE_TOPIC-topic.properties <https://git.onap.org/policy/drools-applications/tree/controlloop/common/feature-controlloop-management/src/main/feature/config/DCAE_TOPIC-topic.properties>`__ is defined as + +.. code-block:: bash + + dmaap.source.topics=DCAE_TOPIC + + dmaap.source.topics.DCAE_TOPIC.effectiveTopic=${env:DCAE_TOPIC} + dmaap.source.topics.DCAE_TOPIC.servers=${env:DMAAP_SERVERS} + dmaap.source.topics.DCAE_TOPIC.consumerGroup=${env:DCAE_CONSUMER_GROUP} + dmaap.source.topics.DCAE_TOPIC.https=true + +In this example, the generic name of the *source* endpoint +is *DCAE_TOPIC*. This is known as the *canonical* name. +The actual *topic* used in communication exchanges in a physical lab is contained +in the *$DCAE_TOPIC* environment variable. This environment variable is usually +set up by *devops* on a per installation basis to meet the needs of each +lab spec. + +In the previous example, *DCAE_TOPIC* is a source-only topic. + +Sink topics are similarly specified but indicating that are sink endpoints +from the perspective of the *controller*. For example, the *APPC-CL* topic +is configured as + +.. code-block:: bash + + dmaap.source.topics=APPC-CL + dmaap.sink.topics=APPC-CL + + dmaap.source.topics.APPC-CL.servers=${env:DMAAP_SERVERS} + dmaap.source.topics.APPC-CL.https=true + + dmaap.sink.topics.APPC-CL.servers=${env:DMAAP_SERVERS} + dmaap.sink.topics.APPC-CL.https=true + +Although not shown in these examples, additional configuration options are available such as *user name*, +*password*, *security keys*, *consumer group* and *consumer instance*. + +UEB Endpoints +~~~~~~~~~~~~~ + +Similary, UEB endpoints are messaging endpoints, similar to the DMaaP ones. + +For example, the +`DCAE_TOPIC-topic.properties <https://git.onap.org/policy/drools-applications/tree/controlloop/common/feature-controlloop-management/src/main/feature/config/DCAE_TOPIC-topic.properties>`__ can be converted to an *UEB* one, by replacing the +*dmaap* prefix with *ueb*. For example: + +.. code-block:: bash + + ueb.source.topics=DCAE_TOPIC + + ueb.source.topics.DCAE_TOPIC.effectiveTopic=${env:DCAE_TOPIC} + ueb.source.topics.DCAE_TOPIC.servers=${env:DMAAP_SERVERS} + ueb.source.topics.DCAE_TOPIC.consumerGroup=${env:DCAE_CONSUMER_GROUP} + ueb.source.topics.DCAE_TOPIC.https=true + +NOOP Endpoints +~~~~~~~~~~~~~~ + +NOOP (no-operation) endpoints are messaging endpoints that don't have any network attachments. +They are used for testing convenience. +To convert the +`DCAE_TOPIC-topic.properties <https://git.onap.org/policy/drools-applications/tree/controlloop/common/feature-controlloop-management/src/main/feature/config/DCAE_TOPIC-topic.properties>`__ to a *NOOP* endpoint, simply replace the *dmaap* prefix with *noop*: + +.. code-block:: bash + + noop.source.topics=DCAE_TOPIC + noop.source.topics.DCAE_TOPIC.effectiveTopic=${env:DCAE_TOPIC} + +HTTP Clients +~~~~~~~~~~~~ + +HTTP Clients are typically stored in files following the naming convention: *<name>-http-client.properties* convention. +One such example is +the `AAI HTTP Client <https://git.onap.org/policy/drools-applications/tree/controlloop/common/feature-controlloop-management/src/main/feature/config/AAI-http-client.properties>`__: + +.. code-block:: bash + + http.client.services=AAI + + http.client.services.AAI.managed=true + http.client.services.AAI.https=true + http.client.services.AAI.host=${envd:AAI_HOST} + http.client.services.AAI.port=${envd:AAI_PORT} + http.client.services.AAI.userName=${envd:AAI_USERNAME} + http.client.services.AAI.password=${envd:AAI_PASSWORD} + http.client.services.AAI.contextUriPath=${envd:AAI_CONTEXT_URI} + +HTTP Servers +~~~~~~~~~~~~ + +HTTP Servers are stored in files that follow a similar naming convention *<name>-http-server.properties*. +The following is an example of a server named *CONFIG*, getting most of its configuration from +environment variables. + +.. code-block:: bash + + http.server.services=CONFIG + + http.server.services.CONFIG.host=${envd:TELEMETRY_HOST} + http.server.services.CONFIG.port=7777 + http.server.services.CONFIG.userName=${envd:TELEMETRY_USER} + http.server.services.CONFIG.password=${envd:TELEMETRY_PASSWORD} + http.server.services.CONFIG.restPackages=org.onap.policy.drools.server.restful + http.server.services.CONFIG.managed=false + http.server.services.CONFIG.swagger=true + http.server.services.CONFIG.https=true + http.server.services.CONFIG.aaf=${envd:AAF:false} + +*Endpoints* configuration resides in the *$POLICY_HOME/config* (or *$POLICY_CONFIG*) directory in a container. + +Controllers +=========== + +*Controllers* are the means for the PDP-D to run *applications*. Controllers are +defined in *<name>-controller.properties* files. + +For example, see the +`frankfurt controller configuration <https://git.onap.org/policy/drools-applications/tree/controlloop/common/feature-controlloop-frankfurt/src/main/feature/config/frankfurt-controller.properties>`__. + +This configuration file has two sections: *a)* application maven coordinates, and *b)* endpoint references and coders. + +Maven Coordinates +~~~~~~~~~~~~~~~~~ + +The coordinates section (*rules*) points to the *controller-frankfurt* *kjar* artifact. +It is the *brain* of the control loop application. + +.. code-block:: bash + + controller.name=frankfurt + + rules.groupId=${project.groupId} + rules.artifactId=controller-frankfurt + rules.version=${project.version} + ..... + +This *kjar* contains the +`frankfurt DRL <https://git.onap.org/policy/drools-applications/tree/controlloop/common/controller-frankfurt/src/main/resources/frankfurt.drl>`__ file (there may be more than one DRL file included). + +.. code-block:: bash + + ... + rule "NEW.TOSCA.POLICY" + when + $policy : ToscaPolicy() + then + + ... + + ControlLoopParams params = ControlLoopUtils.toControlLoopParams($policy); + if (params != null) { + insert(params); + } + end + ... + +The DRL in conjuction with the dependent java libraries in the kjar +`pom <https://git.onap.org/policy/drools-applications/tree/controlloop/common/controller-frankfurt/pom.xml>`__ +realizes the application's function. For intance, it realizes the +vFirewall, vCPE, and vDNS use cases in ONAP. + +.. code-block:: bash + + .. + <dependency> + <groupId>org.onap.policy.models.policy-models-interactions.model-actors</groupId> + <artifactId>actor.appclcm</artifactId> + <version>${policy.models.version}</version> + <scope>provided</scope> + </dependency> + ... + +Endpoints References and Coders +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The *frankfurt-controller.properties* configuration also contains a mix of +source (of incoming controller traffic) and sink (of outgoing controller traffic) +configuration. This configuration also contains specific +filtering and mapping rules for incoming and outgoing dmaap messages +known as *coders*. + +.. code-block:: bash + + ... + dmaap.source.topics=DCAE_TOPIC,APPC-CL,APPC-LCM-WRITE,SDNR-CL-RSP + dmaap.sink.topics=APPC-CL,APPC-LCM-READ,POLICY-CL-MGT,SDNR-CL,DCAE_CL_RSP + + + dmaap.source.topics.APPC-LCM-WRITE.events=org.onap.policy.appclcm.AppcLcmDmaapWrapper + dmaap.source.topics.APPC-LCM-WRITE.events.org.onap.policy.appclcm.AppcLcmDmaapWrapper.filter=[?($.type == 'response')] + dmaap.source.topics.APPC-LCM-WRITE.events.custom.gson=org.onap.policy.appclcm.util.Serialization,gson + + dmaap.sink.topics.APPC-CL.events=org.onap.policy.appc.Request + dmaap.sink.topics.APPC-CL.events.custom.gson=org.onap.policy.appc.util.Serialization,gsonPretty + ... + +In this example, the *coders* specify that incoming messages over the DMaaP endpoint +reference *APPC-LCM-WRITE*, that have a field called *type* under the root JSON object with +value *response* are allowed into the *controller* application. In this case, the incoming +message is converted into an object (fact) of type *org.onap.policy.appclcm.AppcLcmDmaapWrapper*. +The *coder* has attached a custom implementation provided by the *application* with class +*org.onap.policy.appclcm.util.Serialization*. Note that the *coder* filter is expressed in JSONPath notation. + +Note that not all the communication endpoint references need to be explicitly referenced within the +*controller* configuration file. For example, *Http clients* do not. +The reasons are historical, as the PDP-D was initially intended to only communicate +through messaging-based protocols such as UEB or DMaaP in asynchronous unidirectional mode. +The introduction of *Http* with synchronous bi-directional communication with remote endpoints made +it more convenient for the application to manage each network exchange. + +*Controllers* configuration resides in the *$POLICY_HOME/config* (or *$POLICY_CONFIG*) directory in a container. + +Other Configuration Files +~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are other types of configuration files that *controllers* can use, for example *.environment* files +that provides a means to share data across applications. The +`controlloop.properties.environment <https://git.onap.org/policy/drools-applications/tree/controlloop/common/feature-controlloop-management/src/main/feature/config/controlloop.properties.environment>`__ is one such example. + + +Tosca Policies +============== + +PDP-D supports Tosca Policies through the *feature-lifecycle*. The *PDP-D* receives its policy set +from the *PAP*. A policy conforms to its Policy Type specification. +Policy Types and policy creation is done by the *API* component. +Policy deployments are orchestrated by the *PAP*. + +All communication between *PAP* and PDP-D is over the DMaaP *POLICY-PDP-PAP* topic. + +Native Policy Types +~~~~~~~~~~~~~~~~~~~ + +The PDP-D Engine supports two (native) Tosca policy types by means of the *lifecycle* +feature: + +- *onap.policies.native.drools.Controller* +- *onap.policies.native.drools.Artifact* + +These types can be used to dynamically deploy or undeploy application *controllers*, +assign policy types, and upgrade or downgrade their attached maven artifact versions. + +For instance, an +`example native controller <https://git.onap.org/policy/drools-pdp/tree/feature-lifecycle/src/test/resources/tosca-policy-native-controller-example.json>`__ policy is shown below. + +.. code-block:: bash + + { + "tosca_definitions_version": "tosca_simple_yaml_1_0_0", + "topology_template": { + "policies": [ + { + "example.controller": { + "type": "onap.policies.native.drools.Controller", + "type_version": "1.0.0", + "version": "1.0.0", + "name": "example.controller", + "metadata": { + "policy-id": "example.controller" + }, + "properties": { + "controllerName": "lifecycle", + "sourceTopics": [ + { + "topicName": "DCAE_TOPIC", + "events": [ + { + "eventClass": "java.util.HashMap", + "eventFilter": "[?($.closedLoopEventStatus == 'ONSET')]" + }, + { + "eventClass": "java.util.HashMap", + "eventFilter": "[?($.closedLoopEventStatus == 'ABATED')]" + } + ] + } + ], + "sinkTopics": [ + { + "topicName": "APPC-CL", + "events": [ + { + "eventClass": "java.util.HashMap", + "eventFilter": "[?($.CommonHeader && $.Status)]" + } + ] + } + ], + "customConfig": { + "field1" : "value1" + } + } + } + } + ] + } + } + +The actual application coordinates are provided with a policy of type onap.policies.native.drools.Artifact, +see the `example native artifact <https://git.onap.org/policy/drools-pdp/tree/feature-lifecycle/src/test/resources/tosca-policy-native-artifact-example.json>`__ + +.. code-block:: bash + + { + "tosca_definitions_version": "tosca_simple_yaml_1_0_0", + "topology_template": { + "policies": [ + { + "example.artifact": { + "type": "onap.policies.native.drools.Artifact", + "type_version": "1.0.0", + "version": "1.0.0", + "name": "example.artifact", + "metadata": { + "policy-id": "example.artifact" + }, + "properties": { + "rulesArtifact": { + "groupId": "org.onap.policy.drools.test", + "artifactId": "lifecycle", + "version": "1.0.0" + }, + "controller": { + "name": "lifecycle" + } + } + } + } + ] + } + } + +Operational Policy Types +~~~~~~~~~~~~~~~~~~~~~~~~ + +The PDP-D also recognizes Tosca Operational Policies, although it needs an +application *controller* that understands them to execute them. These are: + +- *onap.policies.controlloop.operational.common.Drools* +- *onap.policies.controlloop.Operational* + +A minimum of one application *controller* that supports these capabilities +must be installed in order to honor the *operational policy types*. +One such controller is the *frankfurt* controller residing in the +`policy/drools-applications <https://git.onap.org/policy/drools-applications>`__ +repository. + +Controller Policy Type Support +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Note that a *controller* may support other policy types. A controller may declare them +explicitly in a native *onap.policies.native.drools.Controller* policy. + +.. code-block:: bash + + "customConfig": { + "controller.policy.types" : "policy.type.A" + } + +The *controller* application could declare its supported policy types in the *kjar*. +For example, the *frankfurt controller* packages this information in the +`kmodule.xml <https://git.onap.org/policy/drools-applications/tree/controlloop/common/controller-frankfurt/src/main/resources/META-INF/kmodule.xml>`__. One advantage of this approach is that the PDP-D would only +commit to execute policies against these policy types if a supporting controller is up and running. + +.. code-block:: bash + + <kmodule xmlns="http://jboss.org/kie/6.0.0/kmodule"> + <kbase name="onap.policies.controlloop.operational.common.Drools" default="false" equalsBehavior="equality"/> + <kbase name="onap.policies.controlloop.Operational" equalsBehavior="equality" + packages="org.onap.policy.controlloop" includes="onap.policies.controlloop.operational.common.Drools"> + <ksession name="frankfurt"/> + </kbase> + </kmodule> + +Software Architecture +====================== + +PDP-D is divided into 2 layers: + +- core (`policy-core <https://git.onap.org/policy/drools-pdp/tree/policy-core>`__) +- management (`policy-management <https://git.onap.org/policy/drools-pdp/tree/policy-management>`__) + +Core Layer +~~~~~~~~~~ + +The core layer directly interfaces with the *drools* libraries with 2 main abstractions: + +* `PolicyContainer <https://git.onap.org/policy/drools-pdp/tree/policy-core/src/main/java/org/onap/policy/drools/core/PolicyContainer.java>`__, and +* `PolicySession <https://git.onap.org/policy/drools-pdp/tree/policy-core/src/main/java/org/onap/policy/drools/core/PolicySession.java>`__. + +Policy Container and Sessions +""""""""""""""""""""""""""""" + +The *PolicyContainer* abstracts the drools *KieContainer*, while a *PolicySession* abstracts a drools *KieSession*. +PDP-D uses stateful sessions in active mode (*fireUntilHalt*) (please visit the `drools <https://www.drools.org/>`__ +website for additional documentation). + +Management Layer +~~~~~~~~~~~~~~~~ + +The management layer manages the PDP-D and builds on top of the *core* capabilities. + +PolicyEngine +"""""""""""" + +The PDP-D `PolicyEngine <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/java/org/onap/policy/drools/system/PolicyEngine.java>`__ is the top abstraction and abstracts away the PDP-D and all the +resources it holds. The reader looking at the source code can start looking at this component +in a top-down fashion. Note that the *PolicyEngine* abstraction should not be confused with the +sofware in the *policy/engine* repository, there is no relationship whatsoever other than in the naming. + +The *PolicyEngine* represents the PDP-D, holds all PDP-D resources, and orchestrates activities among those. + +The *PolicyEngine* manages applications via the `PolicyController <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/java/org/onap/policy/drools/system/PolicyController.java>`__ abstractions in the base code. The +relationship between the *PolicyEngine* and *PolicyController* is one to many. + +The *PolicyEngine* holds other global resources such as a *thread pool*, *policies validator*, *telemetry* server, +and *unmanaged* topics for administration purposes. + +The *PolicyEngine* has interception points that allow +`*features* <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/java/org/onap/policy/drools/features/PolicyEngineFeatureApi.java>`__ +to observe and alter the default *PolicyEngine* behavior. + +The *PolicyEngine* implements the `*Startable* <https://git.onap.org/policy/common/tree/capabilities/src/main/java/org/onap/policy/common/capabilities/Startable.java>`__ and `*Lockable* <https://git.onap.org/policy/common/tree/capabilities/src/main/java/org/onap/policy/common/capabilities/Lockable.java>`__ interfaces. These operations +have a cascading effect on the resources the *PolicyEngine* holds, as it is the top level entity, thus +affecting *controllers* and *endpoints*. These capabilities are intended to be used for extensions, +for example active/standby multi-node capabilities. This programmability is +exposed via the *telemetry* API, and *feature* hooks. + +Configuration +^^^^^^^^^^^^^ + +*PolicyEngine* related configuration is located in the +`engine.properties <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/server/config/engine.properties>`__, +and `engine-system.properties <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/server/config/engine.properties>`__. + +The *engine* configuration files reside in the *$POLICY_CONFIG* directory. + +PolicyController +"""""""""""""""" + +A *PolicyController* represents an application. Each *PolicyController* has an instance of a +`DroolsController <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/java/org/onap/policy/drools/system/PolicyController.java>`__. The *PolicyController* provides the means to group application specific resources +into a single unit. Such resources include the application's *maven coordinates*, *endpoint references*, and *coders*. + +A *PolicyController* uses a +`DroolsController <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/java/org/onap/policy/drools/controller/DroolsController.java>`__ to interface with the *core* layer (*PolicyContainer* and *PolicySession*). + +The relationship between the *PolicyController* and the *DroolsController* is one-to-one. +The *DroolsController* currently supports 2 implementations, the +`MavenDroolsController <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/java/org/onap/policy/drools/controller/internal/MavenDroolsController.java>`__, and the +`NullDroolsController <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/java/org/onap/policy/drools/controller/internal/NullDroolsController.java>`__. +The *DroolsController*'s polymorphic behavior depends on whether a maven artifact is attached to the controller or not. + +Configuration +^^^^^^^^^^^^^ + +The *controllers* configuration resides in the *$POLICY_CONFIG* directory. + +Programmability +~~~~~~~~~~~~~~~ + +PDP-D is programmable through: + +- Features and Event Listeners. +- Maven-Drools applications. + +Using Features and Listeners +"""""""""""""""""""""""""""" + +Features hook into the interception points provided by the the *PDP-D* main entities. + +*Endpoint Listeners*, see `here <https://git.onap.org/policy/common/tree/policy-endpoints/src/main/java/org/onap/policy/common/endpoints/event/comm/TopicListener.java>`__ +and `here <https://git.onap.org/policy/common/tree/policy-endpoints/src/main/java/org/onap/policy/common/endpoints/listeners>`__, can be used in conjuction with features for additional capabilities. + +Using Maven-Drools applications +""""""""""""""""""""""""""""""" + +Maven-based drools applications can run any arbitrary functionality structured with rules and java logic. + +Recommended Flow +"""""""""""""""" + +Whenever possible it is suggested that PDP-D related operations flow through the +*PolicyEngine* downwards in a top-down manner. This imposed order implies that +all the feature hooks are always invoked in a deterministic fashion. It is also +a good mechanism to safeguard against deadlocks. + +Telemetry Extensions +"""""""""""""""""""" + +It is recommended to *features* (extensions) to offer a diagnostics REST API +to integrate with the telemetry API. This is done by placing JAX-RS files under +the package *org.onap.policy.drools.server.restful*. The root context path +for all the telemetry services is */policy/pdp/engine*. + +Features +======== + +*Features* is an extension mechanism for the PDP-D functionality. +Features can be toggled on and off. +A feature is composed of: + +- Java libraries. +- Scripts and configuration files. + +Java Extensions +~~~~~~~~~~~~~~~ + +Additional functionality can be provided in the form of java libraries that hook into the +*PolicyEngine*, *PolicyController*, *DroolsController*, and *PolicySession* interception +points to observe or alter the PDP-D logic. + +See the Feature APIs available in the +`management <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/java/org/onap/policy/drools/features>`__ +and +`core <https://git.onap.org/policy/drools-pdp/tree/policy-core/src/main/java/org/onap/policy/drools/core/PolicySessionFeatureApi.java>`__ layers. + +The convention used for naming these extension modules are *api-<name>* for interfaces, +and *feature-<name>* for the actual java extensions. + +Configuration Items +~~~~~~~~~~~~~~~~~~~ + +Installation items such as scripts, SQL, maven artifacts, and configuration files. + +The reader can refer to the `policy/drools-pdp repository <https://git.onap.org/policy/drools-pdp>`__ +and the <https://git.onap.org/policy/drools-applications>`__ repository for miscellaneous feature +implementations. + +Layout +"""""" + +A feature is packaged in a *feature-<name>.zip* and has this internal layout: + +.. code-block:: bash + + # ####################################################################################### + # Features Directory Layout: + # + # $POLICY_HOME/ + # L─ features/ + # L─ <feature-name>*/ + # L─ [config]/ + # | L─ <config-file>+ + # L─ [bin]/ + # | L─ <bin-file>+ + # L─ lib/ + # | L─ [dependencies]/ + # | | L─ <dependent-jar>+ + # │ L─ feature/ + # │ L─ <feature-jar> + # L─ [db]/ + # │ L─ <db-name>/+ + # │ L─ sql/ + # │ L─ <sql-scripts>* + # L─ [artifacts]/ + # L─ <artifact>+ + # L─ [install] + # L─ [enable] + # L─ [disable] + # L─ [other-directories-or-files] + # + # notes: [] = optional , * = 0 or more , + = 1 or more + # <feature-name> directory without "feature-" prefix. + # [config] feature configuration directory that contains all configuration + # needed for this features + # [config]/<config-file> preferably named with "feature-<feature-name>" prefix to + # precisely match it against the exact features, source code, and + # associated wiki page for configuration details. + # [bin] feature bin directory that contains helper scripts for this feature + # [bin]/<executable-file> preferably named with "feature-<feature-name>" prefix. + # lib jar libraries needed by this features + # lib/[dependencies] 3rd party jar dependencies not provided by base installation + # of pdp-d that are necessary for <feature-name> to operate + # correctly. + # lib/feature the single feature jar that implements the feature. + # [db] database directory, if the feature contains sql. + # [db]/<db-name> database to which underlying sql scripts should be applied. + # ideally, <db-name> = <feature-name> so it is easily to associate + # the db data with a feature itself. In addition, since a feature is + # a somewhat independent isolated unit of functionality,the <db-name> + # database ideally isolates all its data. + # [db]/<db-name>/sql directory with all the sql scripts. + # [db]/<db-name>/sql/<sql-scripts> for this feature, sql + # upgrade scripts should be suffixed with ".upgrade.sql" + # and downgrade scripts should be suffixed with ".downgrade.sql" + # [artifacts] maven artifacts to be deployed in a maven repository. + # [artifacts]/<artifact> maven artifact with identifiable maven coordinates embedded + # in the artifact. + # [install] custom installation directory where custom enable or disable scripts + # and other free form data is included to be used for the enable and + # and disable scripts. + # [install]/[enable] enable script executed when the enable operation is invoked in + # the feature. + # [install]/[disable] disable script executed when the disable operation is invoked in + # the feature. + # [install]/[other-directories-or-files] other executables, or data that can be used + # by the feature for any of its operations. The content is determined + # by the feature designer. + # ######################################################################################## + +The `features <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/server-gen/bin/features>`__ +is the tool used for administration purposes: + +.. code-block:: bash + + Usage: features status + Get enabled/disabled status on all features + features enable <feature> ... + Enable the specified feature + features disable <feature> ... + Disable the specified feature + features install [ <feature> | <file-name> ] ... + Install the specified feature + features uninstall <feature> ... + Uninstall the specified feature + +Features available in the Docker image +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The only enabled feature in the *onap/policy-drools* image is: + +- **lifecycle**: enables the lifecycle capability to integrate with the Policy Framework components. + +The following features are included in the image but disabled. + +- **distributed locking**: distributed resource locking. +- **healthcheck**: basic PDP-D Engine healthcheck. + +Healthcheck +""""""""""" + +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. + +When enabled, the feature takes as input a properties file named "*feature-healtcheck.properties*. +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. + +Lifecycle +""""""""" + +The "lifecycle" feature enables a PDP-D to work with the architectural framework introduced in the +Dublin release. + +The lifecycle feature maintains three states: TERMINATED, PASSIVE, and ACTIVE. +The PAP interacts with the lifecycle feature to put a PDP-D in PASSIVE or ACTIVE states. +The PASSIVE state allows for Tosca Operational policies to be deployed. +Policy execution is enabled when the PDP-D transitions to the ACTIVE state. + +This feature can coexist side by side with the legacy mode of operation that pre-dates the Dublin release. + +Distributed Locking +""""""""""""""""""" + +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. + +Other features +~~~~~~~~~~~~~~ + +The following features have been contributed to the *policy/drools-pdp* but are either +unnecessary or have not been thoroughly tested: + +.. toctree:: + :maxdepth: 1 + + feature_activestdbymgmt.rst + feature_controllerlogging.rst + feature_eelf.rst + feature_mdcfilters.rst + feature_pooling.rst + feature_sesspersist.rst + feature_statemgmt.rst + feature_testtransaction.rst + +Data Migration +============== + +PDP-D data is migrated across releases with the +`db-migrator <https://git.onap.org/policy/drools-pdp/tree/policy-management/src/main/server-gen/bin/db-migrator>`__. + +The migration occurs when different release data is detected. *db-migrator* will look under the +*$POLICY_HOME/etc/db/migration* for databases and SQL scripts to migrate. + +.. code-block:: bash + + $POLICY_HOME/etc/db/migration/<schema-name>/sql/<sql-file> + +where *<sql-file>* is of the form: + +.. code-block:: bash + + <VERSION>-<pdp|feature-name>[-description](.upgrade|.downgrade).sql + +The db-migrator tool syntax is + +.. code-block:: bash + + syntax: db-migrator + -s <schema-name> + [-b <migration-dir>] + [-f <from-version>] + [-t <target-version>] + -o <operations> + + where <operations>=upgrade|downgrade|auto|version|erase|report + + Configuration Options: + -s|--schema|--database: schema to operate on ('ALL' to apply on all) + -b|--basedir: overrides base DB migration directory + -f|--from: overrides current release version for operations + -t|--target: overrides target release to upgrade/downgrade + + Operations: + upgrade: upgrade operation + downgrade: performs a downgrade operation + auto: autonomous operation, determines upgrade or downgrade + version: returns current version, and in conjunction if '-f' sets the current version + erase: erase all data related <schema> (use with care) + report: migration detailed report on an schema + ok: is the migration status valid + +See the +`feature-distributed-locking sql directory <https://git.onap.org/policy/drools-pdp/tree/feature-distributed-locking/src/main/feature/db/pooling/sql>`__ +for an example of upgrade/downgrade scripts. + +The following command will provide a report on the upgrade or downgrade activies: + +.. code-block:: bash + + db-migrator -s ALL -o report + +For example in the official frankfurt delivery: + +.. code-block:: bash + + policy@dev-drools-0:/tmp/policy-install$ db-migrator -s ALL -o report + +---------+---------+ + | name | version | + +---------+---------+ + | pooling | 1811 | + +---------+---------+ + +-------------------------------------+-----------+---------+---------------------+ + | script | operation | success | atTime | + +-------------------------------------+-----------+---------+---------------------+ + | 1804-distributedlocking.upgrade.sql | upgrade | 1 | 2020-05-22 19:33:09 | + | 1811-distributedlocking.upgrade.sql | upgrade | 1 | 2020-05-22 19:33:09 | + +-------------------------------------+-----------+---------+---------------------+ + +In order to use the *db-migrator* tool, the system must be configured with a database. + +.. code-block:: bash + + SQL_HOST=mariadb + +Maven Repositories +================== + +The drools libraries in the PDP-D uses maven to fetch rules artifacts and software dependencies. + +The default *settings.xml* file specifies the repositories to search. This configuration +can be overriden with a custom copy that would sit in a mounted configuration +directory. See an example of the OOM override +`settings.xml <https://git.onap.org/oom/tree/kubernetes/policy/charts/drools/resources/configmaps/settings.xml>`__. + +The default ONAP installation of the *control loop* child image *onap/policy-pdpd-cl:1.6.4* is *OFFLINE*. +In this configuration, the *rules* artifact and the *dependencies* retrieves all the artifacts from the local +maven repository. Of course, this requires that the maven dependencies are preloaded in the local +repository for it to work. + +An offline configuration requires two items: + +- *OFFLINE* environment variable set to true. +- override *settings.xml* customization, see + `settings.xml <https://git.onap.org/oom/tree/kubernetes/policy/charts/drools/resources/configmaps/settings.xml>`__. + +The default mode in the *onap/policy-drools:1.6.3* is ONLINE instead. + +In *ONLINE* mode, the *controller* initialization can take a significant amount of time. + +The Policy ONAP installation includes a *nexus* repository component that can be used to host any arbitrary +artifacts that an PDP-D application may require. +The following environment variables configure its location: + +.. code-block:: bash + + SNAPSHOT_REPOSITORY_ID=policy-nexus-snapshots + SNAPSHOT_REPOSITORY_URL=http://nexus:8080/nexus/content/repositories/snapshots/ + RELEASE_REPOSITORY_ID=policy-nexus-releases + RELEASE_REPOSITORY_URL=http://nexus:8080/nexus/content/repositories/releases/ + REPOSITORY_OFFLINE=false + +The *deploy-artifact* tool is used to deploy artifacts to the local or remote maven repositories. +It also allows for dependencies to be installed locally. The *features* tool invokes it when artifacts are +to be deployed as part of a feature. The tool can be useful for developers to test a new application +in a container. + +.. code-block:: bash + + syntax: deploy-artifact + [-f|-l|-d] + -s <custom-settings> + -a <artifact> + + Options: + -f|--file-repo: deploy in the file repository + -l|--local-repo: install in the local repository + -d|--dependencies: install dependencies in the local repository + -s|--settings: custom settings.xml + -a|--artifact: file artifact (jar or pom) to deploy and/or install + +AAF +=== + +Policy can talk to AAF for authorization requests. To enable AAF set +the following environment variables: + +.. code-block:: bash + + AAF=true + AAF_NAMESPACE=org.onap.policy + AAF_HOST=aaf-locate.onap + +By default AAF is disabled. + +Policy Tool +=========== + +The *policy* tool can be used to stop, start, and provide status on the PDP-D. + +.. code-block:: bash + + syntax: policy [--debug] status|start|stop + +The *status* option provides generic status of the system. + +.. code-block:: bash + + [drools-pdp-controllers] + L []: Policy Management (pid 408) is running + 0 cron jobs installed. + + [features] + name version status + ---- ------- ------ + healthcheck 1.6.3 enabled + distributed-locking 1.6.3 enabled + lifecycle 1.6.3 enabled + controlloop-management 1.6.4 enabled + controlloop-utils 1.6.4 enabled + controlloop-trans 1.6.4 enabled + controlloop-frankfurt 1.6.4 enabled + controlloop-usecases 1.6.4 disabled + + [migration] + pooling: OK @ 1811 + +It contains 3 sections: + +- *PDP-D* running status +- *features* applied +- Data migration status on a per database basis. + +The *start* and *stop* commands are useful for developers testing functionality on a docker container instance. + +Telemetry Shell +=============== + +*PDP-D* offers an ample set of REST APIs to debug, introspect, and change state on a running PDP-D. This is known as the +*telemetry* API. The *telemetry* shell wraps these APIs for shell-like access using +`http-prompt <http://http-prompt.com/>`__. + +.. code-block:: bash + + policy@dev-drools-0:~$ telemetry + Version: 1.0.0 + https://localhost:9696/policy/pdp/engine> get controllers + HTTP/1.1 200 OK + Content-Length: 13 + Content-Type: application/json + Date: Thu, 04 Jun 2020 01:07:38 GMT + Server: Jetty(9.4.24.v20191120) + + [ + "frankfurt" + ] + + https://localhost:9696/policy/pdp/engine> exit + Goodbye! + policy@dev-drools-0:~$ + + +Other tools +=========== + +Refer to the *$POLICY_HOME/bin/* directory for additional tooling. + +PDP-D Docker Container Configuration +==================================== + +Both the PDP-D *onap/policy-drools* and *onap/policy-pdpd-cl* images can be used without other components. + +There are 2 types of configuration data provided to the container: + +1. environment variables. +2. configuration files and shell scripts. + +Environment variables +~~~~~~~~~~~~~~~~~~~~~ + +As it was shown in the *controller* and *endpoint* sections, PDP-D configuration can rely +on environment variables. In a container environment, these variables are set up by the user +in the host environment. + +Configuration Files and Shell Scripts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +PDP-D is very flexible in its configuration. + +The following file types are recognized when mounted under */tmp/policy-install/config*. + +These are the configuration items that can reside externally and override the default configuration: + +- **settings.xml** if working with external nexus repositories. +- **standalone-settings.xml** if an external *policy* nexus repository is not available. +- ***.conf** files containing environment variables. This is an alternative to use environment variables, + as these files will be sourced in before the PDP-D starts. +- **features*.zip** to load any arbitrary feature not present in the image. +- ***.pre.sh** scripts that will be executed before the PDP-D starts. +- ***.post.sh** scripts that will be executed after the PDP-D starts. +- **policy-keystore** to override the default PDP-D java keystore. +- **policy-truststore** to override the default PDP-D java truststore. +- **aaf-cadi.keyfile** to override the default AAF CADI Key generated by AAF. +- ***.properties** to override or add any properties file for the PDP-D, this includes *controller*, *endpoint*, + *engine* or *system* configurations. +- **logback*.xml** to override the default logging configuration. +- ***.xml** to override other .xml configuration that may be used for example by an *application*. +- ***.json** *json* configuration that may be used by an *application*. + + +Running PDP-D with a single container +===================================== + +Environment File +~~~~~~~~~~~~~~~~ + +First create an environment file (in this example *env.conf*) to configure the PDP-D. + +.. code-block:: bash + + # SYSTEM software configuration + + POLICY_HOME=/opt/app/policy + POLICY_LOGS=/var/log/onap/policy/pdpd + KEYSTORE_PASSWD=Pol1cy_0nap + TRUSTSTORE_PASSWD=Pol1cy_0nap + + # Telemetry credentials + + TELEMETRY_PORT=9696 + TELEMETRY_HOST=0.0.0.0 + TELEMETRY_USER=demo@people.osaaf.org + TELEMETRY_PASSWORD=demo123456! + + # nexus repository + + SNAPSHOT_REPOSITORY_ID= + SNAPSHOT_REPOSITORY_URL= + RELEASE_REPOSITORY_ID= + RELEASE_REPOSITORY_URL= + REPOSITORY_USERNAME= + REPOSITORY_PASSWORD= + REPOSITORY_OFFLINE=true + + # Relational (SQL) DB access + + SQL_HOST= + SQL_USER= + SQL_PASSWORD= + + # AAF + + AAF=false + AAF_NAMESPACE=org.onap.policy + AAF_HOST=aaf.api.simpledemo.onap.org + + # PDP-D DMaaP configuration channel + + PDPD_CONFIGURATION_TOPIC=PDPD-CONFIGURATION + PDPD_CONFIGURATION_API_KEY= + PDPD_CONFIGURATION_API_SECRET= + PDPD_CONFIGURATION_CONSUMER_GROUP= + PDPD_CONFIGURATION_CONSUMER_INSTANCE= + PDPD_CONFIGURATION_PARTITION_KEY= + + # PAP-PDP configuration channel + + POLICY_PDP_PAP_TOPIC=POLICY-PDP-PAP + POLICY_PDP_PAP_API_KEY= + POLICY_PDP_PAP_API_SECRET= + + # DMaaP + + DMAAP_SERVERS=localhost + +Note that *SQL_HOST*, and *REPOSITORY* are empty, so the PDP-D does not attempt +to integrate with those components. + +Configuration +~~~~~~~~~~~~~ + +In order to avoid the noise in the logs that relate to dmaap configuration, a startup script (*noop.pre.sh*) is added +to convert *dmaap* endpoints to *noop* in the host directory to be mounted. + +noop.pre.sh +""""""""""" + +.. code-block:: bash + + #!/bin/bash -x + + sed -i "s/^dmaap/noop/g" $POLICY_HOME/config/*.properties + + +active.post.sh +"""""""""""""" + +To put the controller directly in active mode at initialization, place an *active.post.sh* script under the +mounted host directory: + +.. code-block:: bash + + #!/bin/bash -x + + bash -c "http --verify=no -a ${TELEMETRY_USER}:${TELEMETRY_PASSWORD} PUT https://localhost:9696/policy/pdp/engine/lifecycle/state/ACTIVE" + +Bring up the PDP-D +~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + docker run --rm -p 9696:9696 -v ${PWD}/config:/tmp/policy-install/config --env-file ${PWD}/env/env.conf -it --name PDPD -h pdpd nexus3.onap.org:10001/onap/policy-drools:1.6.3 + +To run the container in detached mode, add the *-d* flag. + +Note that in this command, we are opening the *9696* telemetry API port to the outside world, the config directory +(where the *noop.pre.sh* customization script resides) is mounted as /tmp/policy-install/config, +and the customization environment variables (*env/env.conf*) are passed into the container. + +To open a shell into the PDP-D: + +.. code-block:: bash + + docker exec -it pdp-d bash + +Once in the container, run tools such as *telemetry*, *db-migrator*, *policy* to look at the system state: + +To run the *telemetry shell* and other tools from the host: + +.. code-block:: bash + + docker exec -it PDPD bash -c "/opt/app/policy/bin/telemetry" + docker exec -it PDPD bash -c "/opt/app/policy/bin/policy status" + docker exec -it PDPD bash -c "/opt/app/policy/bin/db-migrator -s ALL -o report" + +Controlled instantiation of the PDP-D +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes a developer may want to start and stop the PDP-D manually: + +.. code-block:: bash + + # start a bash + + docker run --rm -p 9696:9696 -v ${PWD}/config:/tmp/policy-install/config --env-file ${PWD}/env/env.conf -it --name PDPD -h pdpd nexus3.onap.org:10001/onap/policy-drools:1.6.3 bash + + # use this command to start policy applying host customizations from /tmp/policy-install/config + + pdpd-entrypoint.sh vmboot + + # or use this command to start policy without host customization + + policy start + + # at any time use the following command to stop the PDP-D + + policy stop + + # and this command to start the PDP-D back again + + policy start + +Running PDP-D with nexus and mariadb +==================================== + +*docker-compose* can be used to test the PDP-D with other components. This is an example configuration +that brings up *nexus*, *mariadb* and the PDP-D (*docker-compose-pdp.yml*) + +docker-compose-pdp.yml +~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + version: '3' + services: + mariadb: + image: mariadb:10.2.25 + container_name: mariadb + hostname: mariadb + command: ['--lower-case-table-names=1', '--wait_timeout=28800'] + env_file: + - ${PWD}/db/db.conf + volumes: + - ${PWD}/db:/docker-entrypoint-initdb.d + ports: + - "3306:3306" + nexus: + image: sonatype/nexus:2.14.8-01 + container_name: nexus + hostname: nexus + ports: + - "8081:8081" + drools: + image: nexus3.onap.org:10001/onap/policy-drools:1.6.3 + container_name: drools + depends_on: + - mariadb + - nexus + hostname: drools + ports: + - "9696:9696" + volumes: + - ${PWD}/config:/tmp/policy-install/config + env_file: + - ${PWD}/env/env.conf + +with *${PWD}/db/db.conf*: + +db.conf +~~~~~~~ + +.. code-block:: bash + + MYSQL_ROOT_PASSWORD=secret + MYSQL_USER=policy_user + MYSQL_PASSWORD=policy_user + +and *${PWD}/db/db.sh*: + +db.sh +~~~~~ + +.. code-block:: bash + + for db in support onap_sdk log migration operationshistory10 pooling policyadmin operationshistory + do + mysql -uroot -p"${MYSQL_ROOT_PASSWORD}" --execute "CREATE DATABASE IF NOT EXISTS ${db};" + mysql -uroot -p"${MYSQL_ROOT_PASSWORD}" --execute "GRANT ALL PRIVILEGES ON \`${db}\`.* TO '${MYSQL_USER}'@'%' ;" + done + + mysql -uroot -p"${MYSQL_ROOT_PASSWORD}" --execute "FLUSH PRIVILEGES;" + +env.conf +~~~~~~~~ + +The environment file *env/env.conf* for *PDP-D* can be set up with appropriate variables to point to the *nexus* instance +and the *mariadb* database: + +.. code-block:: bash + + # SYSTEM software configuration + + POLICY_HOME=/opt/app/policy + POLICY_LOGS=/var/log/onap/policy/pdpd + KEYSTORE_PASSWD=Pol1cy_0nap + TRUSTSTORE_PASSWD=Pol1cy_0nap + + # Telemetry credentials + + TELEMETRY_PORT=9696 + TELEMETRY_HOST=0.0.0.0 + TELEMETRY_USER=demo@people.osaaf.org + TELEMETRY_PASSWORD=demo123456! + + # nexus repository + + SNAPSHOT_REPOSITORY_ID=policy-nexus-snapshots + SNAPSHOT_REPOSITORY_URL=http://nexus:8081/nexus/content/repositories/snapshots/ + RELEASE_REPOSITORY_ID=policy-nexus-releases + RELEASE_REPOSITORY_URL=http://nexus:8081/nexus/content/repositories/releases/ + REPOSITORY_USERNAME=admin + REPOSITORY_PASSWORD=admin123 + REPOSITORY_OFFLINE=false + + MVN_SNAPSHOT_REPO_URL=https://nexus.onap.org/content/repositories/snapshots/ + MVN_RELEASE_REPO_URL=https://nexus.onap.org/content/repositories/releases/ + + # Relational (SQL) DB access + + SQL_HOST=mariadb + SQL_USER=policy_user + SQL_PASSWORD=policy_user + + # AAF + + AAF=false + AAF_NAMESPACE=org.onap.policy + AAF_HOST=aaf.api.simpledemo.onap.org + + # PDP-D DMaaP configuration channel + + PDPD_CONFIGURATION_TOPIC=PDPD-CONFIGURATION + PDPD_CONFIGURATION_API_KEY= + PDPD_CONFIGURATION_API_SECRET= + PDPD_CONFIGURATION_CONSUMER_GROUP= + PDPD_CONFIGURATION_CONSUMER_INSTANCE= + PDPD_CONFIGURATION_PARTITION_KEY= + + # PAP-PDP configuration channel + + POLICY_PDP_PAP_TOPIC=POLICY-PDP-PAP + POLICY_PDP_PAP_API_KEY= + POLICY_PDP_PAP_API_SECRET= + + # DMaaP + + DMAAP_SERVERS=localhost + +prepare.pre.sh +~~~~~~~~~~~~~~ + +A pre-start script *config/prepare.pres.sh"can be added the custom config directory +to prepare the PDP-D to activate the distributed-locking feature (using the database) +and to use "noop" topics instead of *dmaap* topics: + +.. code-block:: bash + + #!/bin/bash + + bash -c "/opt/app/policy/bin/features enable distributed-locking" + sed -i "s/^dmaap/noop/g" $POLICY_HOME/config/*.properties + +active.post.sh +~~~~~~~~~~~~~~ + +A post-start script *config/active.post.sh* can place PDP-D in *active* mode at initialization: + + .. code-block:: bash + + bash -c "http --verify=no -a ${TELEMETRY_USER}:${TELEMETRY_PASSWORD} PUT https://localhost:9696/policy/pdp/engine/lifecycle/state/ACTIVE" + +Bring up the PDP-D, nexus, and mariadb +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To bring up the containers: + +.. code-block:: bash + + docker-compose -f docker-compose-pdpd.yaml up -d + +To take it down: + +.. code-block:: bash + + docker-compose -f docker-compose-pdpd.yaml down -v + +Other examples +~~~~~~~~~~~~~~ + +The reader can also look at the `integration/csit repository <https://git.onap.org/integration/csit>`__. +More specifically, these directories have examples of other PDP-D configurations: + +* `plans <https://git.onap.org/integration/csit/tree/plans/policy/drools-pdp>`__: startup scripts. +* `scripts <https://git.onap.org/integration/csit/tree/scripts/policy/docker-compose-drools.yml>`__: docker-compose related files. +* `plans <https://git.onap.org/integration/csit/tree/tests/policy/drools-pdp>`__: test plan. + +Configuring the PDP-D in an OOM Kubernetes installation +======================================================= + +The `PDP-D OOM chart <https://git.onap.org/oom/tree/kubernetes/policy/charts/drools>`__ can be +customized at the following locations: + +* `values.yaml <https://git.onap.org/oom/tree/kubernetes/policy/charts/drools/values.yaml>`__: custom values for your installation. +* `configmaps <https://git.onap.org/oom/tree/kubernetes/policy/charts/drools/resources/configmaps>`__: place in this directory any configuration extensions or overrides to customize the PDP-D that does not contain sensitive information. +* `secrets <https://git.onap.org/oom/tree/kubernetes/policy/charts/drools/resources/secrets>`__: place in this directory any configuration extensions or overrides to customize the PDP-D that does contain sensitive information. + +The same customization techniques described in the docker sections for PDP-D, fully apply here, by placing the corresponding +files or scripts in these two directories. + +Additional information +====================== + +For additional information, please see the +`Drools PDP Development and Testing (In Depth) <https://wiki.onap.org/display/DW/2020+Frankfurt+Tutorials>`__ page. diff --git a/docs/drools/runningEclipse.rst b/docs/drools/runningEclipse.rst deleted file mode 100644 index 5123a540..00000000 --- a/docs/drools/runningEclipse.rst +++ /dev/null @@ -1,59 +0,0 @@ - -.. 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 Frankfurt release, the project directory will look as follows assuming all drools-pdp projects were selected when importing. - - .. image:: img/frankfurt_project_explorer2.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. Ensure you are using the correct username and password specified for your setup. - - .. code-block:: bash - - curl -k --silent --user <username>:<password> -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>`_. - -.. seealso:: To use other telemetry commands to interact with the PDP-D, refer to `Getting Information <clsimulation.html#getting-information>`_. - - -End of Document - - -.. SSNote: Wiki page ref. https://wiki.onap.org/display/DW/Running+PDP-D+in+Eclipse - - diff --git a/docs/drools/runningPDPD.rst b/docs/drools/runningPDPD.rst deleted file mode 100644 index 0934c8c9..00000000 --- a/docs/drools/runningPDPD.rst +++ /dev/null @@ -1,164 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -********************************************************** -Methods to run PDP-D -********************************************************** - -.. contents:: - :depth: 2 - -There are two methods you can use to run a PDP-D for testing purposes: - -1. Using Docker - -2. Using Eclipse - -Using Docker -^^^^^^^^^^^^ -**Step 1:** Clone the integration/csit repository. - -You can find the repo here: https://gerrit.onap.org/r/admin/repos/integration/csit. -Although this repository is used for CSIT testing, we can use this as a means to get a PDP-D up and running with docker. - - .. code-block:: bash - - git clone "https://gerrit.onap.org/r/integration/csit" - -**Step 2:** Note the "docker-compose" commands that will be used. - - .. code-block:: bash - - docker-compose -f ${WORKSPACE}/scripts/policy/docker-compose-drools-apps.yml up -d - - docker-compose -f ${WORKSPACE}/scripts/policy/docker-compose-drools-apps.yml down -v - -Note that ${WORKSPACE} refers to the local path where the csit repository is. - -**Step 3:** Edit the "docker-compose-drools-apps.yml" file. - -Take a look at the "csit/scripts/policy/docker-compose-drools-apps.yml" file. It should look similar to this: - - .. image:: img/docker/yamlClone.png - -The following changes need to be made based on which version you are running and your local setup. - - .. code-block:: bash - - ${POLICY_MARIADB_VER} should be "10.2.14" (without quotes, version subject to change) - - ${WORKSPACE} should be the absolute path to the cloned "csit" repository. - - ${POLICY_DROOLS_APPS_VERSION} should be "1.6.0" (without quotes, version subject to change). - -If you are using MacOS, you will also need to make the following changes: - - .. code-block:: bash - - expose: - - 6969 - - 9696 - - will need to be changed to: - - ports: - - "6969:6969" - - "9696:9696" - -**Step 4:** Start containers and interact with PDP-D. - - .. code-block:: bash - - docker-compose -f scripts/policy/docker-compose-drools-apps.yml up -d - docker container ls - docker exec -it drools bash - - .. image:: img/docker/dockerComposeUp.png - - .. code-block:: bash - - policy status - - .. image:: img/docker/policyStatus.png - - .. code-block:: bash - - # launches subshell where telemetry commands can be executed - telemetry - - ls - - cd controllers - - # Get the current controllers - get - - .. image:: img/docker/telemetryCmd.png - - .. code-block:: bash - - # Get information about the "frankfurt" controller - get frankfurt - - .. image:: img/docker/getFrankfurt.png - - - .. code-block:: bash - - docker-compose -f scripts/policy/docker-compose-drools-apps.yml down -v - - .. image:: img/docker/dockerComposeDown.png - -In the next section, you will see more about using telemetry commands and interacting with the PDP-D. - -Using Eclipse -^^^^^^^^^^^^^ - -**Step 1:** Clone 'drools-pdp' repository and create a new directory for eclipse workspace. - -Link to repository: https://gerrit.onap.org/r/admin/repos/policy/drools-pdp -For the purposes of this demo, we will create an new directory to use as a workspace for eclipse. - - .. code-block:: bash - - $ git clone "https://gerrit.onap.org/r/policy/drools-pdp" - Cloning into 'drools-pdp'... - remote: Counting objects: 59, done - remote: Finding sources: 100% (30/30) - remote: Total 14406 (delta 0), reused 14399 (delta 0) - Receiving objects: 100% (14406/14406), 3.23 MiB | 628.00 KiB/s, done. - Resolving deltas: 100% (6630/6630), done. - Checking out files: 100% (588/588), done. - - $ mkdir workspace-drools-pdp - - $ ls - drools-pdp/ workspace-drools-pdp/ - -The "drools-pdp/" directory contains the cloned repository and "workspace-drools-pdp/" is an empty directory. - -**Step 2:** Import "drools-pdp" as an existing maven project. - -Open Eclipse. Hit the **browse** button and navigate to the "workspace-drools-pdp/" directory. Select that folder as the workspace directory and hit **launch**. - - .. image:: img/eclipse/selectDirectory.png - -Select File -> Import -> Maven -> Existing Maven Projects -> Next - - .. image:: img/eclipse/importMavenProject.png - -Select **Browse** and navigate to the root directory of the cloned project. Hit **Select All** to make sure all projects are included and select **Finish**. - - .. image:: img/eclipse/selectProjectsToImport.png - -**Step 3:** Run "policy-management" as a java application - -All of the projects will appear in the package explorer after they finish importing. Right click on "policy-management", select "Run As", and select "Java Application". - - .. image:: img/eclipse/runAsJavaApp.png - -Type "main" and select the option "Main - org.onap.policy.drools.system" then hit **OK**. - - .. image:: img/eclipse/mainAppSelection.png - -If everything is successful, the PDP-D will start running and you will notice output displayed in the console. In the next section, you will see how to interact with the PDP-D using telemetry commands. diff --git a/docs/drools/tutorial_cl.rst b/docs/drools/tutorial_cl.rst deleted file mode 100644 index d7c2430c..00000000 --- a/docs/drools/tutorial_cl.rst +++ /dev/null @@ -1,107 +0,0 @@ - -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -*********************************************************************************************** -Using the Control Loop PDP-D docker image for standalone testing -*********************************************************************************************** - -.. contents:: - :depth: 3 - -In this tutorial will start a Control Loop PDP-D container to use to test Operational Policies -without companion components. - -**Step 1:** Copy a template *base.conf* with configuration to instantiate the container. - - .. code-block:: bash - - mkdir config - cd config - wget https://git.onap.org/policy/docker/plain/config/drools/base.conf?h=dublin -O base.conf - - -**Step 2:** Simplify *base.conf* for a standalone configuration (by disabling db and nexus access): - - .. code-block:: bash - - cd config - sed -i "s/^SQL_HOST=.*$/SQL_HOST=/g" base.conf - sed -i "s/^SNAPSHOT_REPOSITORY_ID=.*$/SNAPSHOT_REPOSITORY_ID=/g" base.conf - sed -i "s/^SNAPSHOT_REPOSITORY_URL=.*$/SNAPSHOT_REPOSITORY_URL=/g" base.conf - sed -i "s/^RELEASE_REPOSITORY_ID=.*$/RELEASE_REPOSITORY_ID=/g" base.conf - sed -i "s/^RELEASE_REPOSITORY_URL=.*$/RELEASE_REPOSITORY_URL=/g" base.conf - - Note: For MacOS use - sed -i'' -e "s/^SQL_HOST=.*$/SQL_HOST=/g" base.conf and similar for all sed commands. - -**Step 3:** Open a *bash* shell into the PDP-D Control Loop container. - - .. code-block:: bash - - docker run --rm --env-file config/base.conf -p 9696:9696 -p 6969:6969 -it --name pdpd -h pdpd nexus3.onap.org:10001/onap/policy-pdpd-cl:1.4.1 bash - -**Step 4:** Disable the distributed-locking feature, since this is a single CL PDP-D instance. - - .. code-block:: bash - - features disable distributed-locking - -**Step 5:** If using simulators (see tutorials), enable the *controlloop-utils* feature. - - .. code-block:: bash - - features enable controlloop-utils - -**Step 6:** To reduce error logs due to being unable to communicate with DMaaP, change the official configuration to use *noop* topics instead (no network IO involved). - - .. code-block:: bash - - cd $POLICY_HOME/config - sed -i "s/^dmaap/noop/g" *.properties - -**Step 7:** Disable PDP-X guard functionality. - - .. code-block:: bash - - cd $POLICY_HOME/config - sed -i "s/^guard.disabled=*$/guard.disabled=true/g" $POLICY_HOME/config/controlloop.properties.environment - sed -i "s/^aai.customQuery=*$/aai.customQuery=false/g" $POLICY_HOME/config/controlloop.properties.environment - -**Step 8:** Start the CL PDP-D. - - .. code-block:: bash - - policy start - -**Step 9:** Place the CL PDP-D in *ACTIVE* mode. - - .. code-block:: bash - - cat pdp-state-change.json - { - "state": "ACTIVE", - "messageName": "PDP_STATE_CHANGE", - "requestId": "385146af-adeb-4157-b97d-6ae85c1ddcb3", - "timestampMs": 1555791893587, - "name": "pdpd", - "pdpGroup": "controlloop", - "pdpSubgroup": "drools" - } - - http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/POLICY-PDP-PAP/events @pdp-state-change.json Content-Type:'text/plain' - - telemetry # to verify - > get lifecycle/fsm/state # verify that state is ACTIVE - -Note that *name* in *pdp-state-change.json* can be obtained from running *hostname* in the container. - -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>`_ - -.. seealso:: `Methods to run PDP-D <runningPDPD.html>`_. - - -End of Document diff --git a/docs/drools/tutorial_vCPE.rst b/docs/drools/tutorial_vCPE.rst deleted file mode 100644 index 2bda592b..00000000 --- a/docs/drools/tutorial_vCPE.rst +++ /dev/null @@ -1,146 +0,0 @@ - -.. 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, it is assumed that the set up steps from section -*Using the Control Loop PDP-D docker image for standalone testing* has been followed. - -Running the Flow -^^^^^^^^^^^^^^^^ - -**Step 1:** Deploy the vCPE Operational Policy. - - .. code-block:: bash - - cat pdp-update-vcpe.json - { - "policies": [ - { - "type": "onap.policies.controlloop.Operational", - "type_version": "1.0.0", - "properties": { - "content": "controlLoop%3A%0A%20%20version%3A%202.0.0%0A%20%20controlLoopName%3A%20ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e%0A%20%20trigger_policy%3A%20unique-policy-id-1-restart%0A%20%20timeout%3A%203600%0A%20%20abatement%3A%20false%0A%20%0Apolicies%3A%0A%20%20-%20id%3A%20unique-policy-id-1-restart%0A%20%20%20%20name%3A%20Restart%20the%20VM%0A%20%20%20%20description%3A%0A%20%20%20%20actor%3A%20APPC%0A%20%20%20%20recipe%3A%20Restart%0A%20%20%20%20target%3A%0A%20%20%20%20%20%20type%3A%20VM%0A%20%20%20%20retry%3A%203%0A%20%20%20%20timeout%3A%201200%0A%20%20%20%20success%3A%20final_success%0A%20%20%20%20failure%3A%20final_failure%0A%20%20%20%20failure_timeout%3A%20final_failure_timeout%0A%20%20%20%20failure_retries%3A%20final_failure_retries%0A%20%20%20%20failure_exception%3A%20final_failure_exception%0A%20%20%20%20failure_guard%3A%20final_failure_guard" - }, - "name": "operational.restart", - "version": "1.0.0" - } - ], - "messageName": "PDP_UPDATE", - "requestId": "a7a32d3b-37b4-4fb7-9322-b90c6a6fe365", - "timestampMs": 1556125347251, - "name": "pdpd", - "pdpGroup": "controlloop", - "pdpSubgroup": "drools" - } - - http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/POLICY-PDP-PAP/events @pdp-update-vcpe.json Content-Type:'text/plain' - - telemetry # verify - > get controllers/usecases/drools/facts/usecases/controlloops - > get controllers/usecases/drools/facts/usecases/controlloops/ControlLoop-vCPE-48f0c2c3-a172-4192-9ae3-052274181b6e - -**Step 2:** Inject a simulated *ONSET* message. - - .. code-block:: bash - - cat dcae.vcpe.onset.json - { - "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" - } - - http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/DCAE_TOPIC/switches/activation # activate noop source - - http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/DCAE_TOPIC/events @dcae.vcpe.onset.json Content-Type:'text/plain' # send onset - -**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 8 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. - -The network log will be used to monitor the activity coming in and out of the PDP-D. This log is located at *$POLICY_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 - -**Step 3:** Inject an APPC response in the APPC-LCM-WRITE topic - - .. code-block:: bash - - cat appc.lcm.success.json - { - "body": { - "output": { - "common-header": { - "timestamp": "2017-08-25T21:06:23.037Z", - "api-ver": "5.00", - "originator-id": "664be3d2-6c12-4f4b-a3e7-c349acced200", - "request-id": "664be3d2-6c12-4f4b-a3e7-c349acced200", - "sub-request-id": "1", - "flags": {} - }, - "status": { - "code": 400, - "message": "Restart Successful" - } - } - }, - "version": "2.0", - "rpc-name": "restart", - "correlation-id": "664be3d2-6c12-4f4b-a3e7-c349acced200-1", - "type": "response" - } - - http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/APPC-LCM-WRITE/switches/activation # activate noop source - - http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/APPC-LCM-WRITE/events @appc.lcm.success.json Content-Type:'text/plain' - - .. 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 - -Once the transaction has completed, a final success notification is sent from the PDP-D. - - .. image:: Tut_vCPE_policy_final_success.JPG - -After processing there should only be 2 facts left in memory. - -End of Document diff --git a/docs/drools/tutorial_vDNS.rst b/docs/drools/tutorial_vDNS.rst deleted file mode 100644 index e9056b30..00000000 --- a/docs/drools/tutorial_vDNS.rst +++ /dev/null @@ -1,118 +0,0 @@ - -.. 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 test the vDNS flow in a standalone PDP-D docker container. - -Initial Setup -^^^^^^^^^^^^^ - -It is assumed that the set up steps from section -*Using the Control Loop PDP-D docker image for standalone testing* has been followed for -this tutorial. - -Running the Flow -^^^^^^^^^^^^^^^^ - -**Step 1:** Deploy the vDNS Operational Policy. - - .. code-block:: bash - - cat pdp-update-vdns.json - { - "policies": [ - { - "type": "onap.policies.controlloop.Operational", - "type_version": "1.0.0", - "properties": { - "content": "controlLoop%3A%0A%20%20version%3A%202.0.0%0A%20%20controlLoopName%3A%20ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3%0A%20%20services%3A%0A%20%20%20%20-%20serviceName%3A%20d4738992-6497-4dca-9db9%0A%20%20%20%20%20%20serviceInvariantUUID%3A%20dc112d6e-7e73-4777-9c6f-1a7fb5fd1b6f%0A%20%20%20%20%20%20serviceUUID%3A%202eea06c6-e1d3-4c3a-b9c4-478c506eeedf%0A%20%20trigger_policy%3A%20unique-policy-id-1-scale-up%0A%20%20timeout%3A%2060%0A%20%0Apolicies%3A%0A%20%20-%20id%3A%20unique-policy-id-1-scale-up%0A%20%20%20%20name%3A%20Create%20a%20new%20VF%20Module%0A%20%20%20%20description%3A%0A%20%20%20%20actor%3A%20SO%0A%20%20%20%20recipe%3A%20VF%20Module%20Create%0A%20%20%20%20target%3A%0A%20%20%20%20%20%20type%3A%20VFMODULE%0A%20%20%20%20%20%20modelInvariantId%3A%2090b793b5-b8ae-4c36-b10b-4b6372859d3a%0A%20%20%20%20%20%20modelVersionId%3A%202210154d-e61a-4d7f-8fb9-0face1aee3f8%0A%20%20%20%20%20%20modelName%3A%20SproutScalingVf..scaling_sprout..module-1%0A%20%20%20%20%20%20modelVersion%3A%201%0A%20%20%20%20%20%20modelCustomizationId%3A%203e2d67ad-3495-4732-82f6-b0b872791fff%0A%20%20%20%20payload%3A%0A%20%20%20%20%20%20requestParameters%3A%20%27%7B%22usePreload%22%3Atrue%2C%22userParams%22%3A%5B%5D%7D%27%0A%20%20%20%20%20%20configurationParameters%3A%20%27%5B%7B%22ip-addr%22%3A%22%24.vf-module-topology.vf-module-parameters.param%5B9%5D%22%2C%22oam-ip-addr%22%3A%22%24.vf-module-topology.vf-module-parameters.param%5B16%5D%22%2C%22enabled%22%3A%22%24.vf-module-topology.vf-module-parameters.param%5B23%5D%22%7D%5D%27%0A%20%20%20%20retry%3A%200%0A%20%20%20%20timeout%3A%2030%0A%20%20%20%20success%3A%20final_success%0A%20%20%20%20failure%3A%20final_failure%0A%20%20%20%20failure_timeout%3A%20final_failure_timeout%0A%20%20%20%20failure_retries%3A%20final_failure_retries%0A%20%20%20%20failure_exception%3A%20final_failure_exception%0A%20%20%20%20failure_guard%3A%20final_failure_guard%0A" - }, - "name": "operational.scaleout", - "version": "1.0.0" - } - ], - "messageName": "PDP_UPDATE", - "requestId": "a7a32d3b-37b4-4fb7-9322-b90c6a6fe365", - "timestampMs": 1556125347251, - "name": "pdpd", - "pdpGroup": "controlloop", - "pdpSubgroup": "drools" - } - - http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/POLICY-PDP-PAP/events @pdp-update-vdns.json Content-Type:'text/plain' - - telemetry - > get controllers/usecases/drools/facts/usecases/controlloops - > get controllers/usecases/drools/facts/usecases/controlloops/ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3 - -**Step 2:** Inject a simulated *ONSET* message. - - .. code-block:: bash - - cat dcae.vdns.onset.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" - } - - http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/DCAE_TOPIC/switches/activation # activate noop source - - http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/DCAE_TOPIC/events @dcae.vdns.onset.json Content-Type:'text/plain' # send onset - -The network log can be used to monitor the PDP-D network input/output operations. This log is located at *$POLICY_LOGS/network.log*. The log file will show interactions with the AAI and SO simulator to fulfill the flow. Once the transaction has completed, a final success notification will be recorded in this file. - - .. code-block:: bash - - { - "AAI": { - "vserver.prov-status": "ACTIVE", - "vserver.is-closed-loop-disabled": "false", - "vserver.vserver-name": "dfw1lb01lb01" - }, - "closedLoopAlarmStart": 1484677482204798, - "closedLoopControlName": "ControlLoop-vDNS-6f37f56d-a87d-4b85-b6a9-cc953cf779b3", - "version": "1.0.2", - "requestId": "e4f95e0c-a013-4530-8e59-c5c5f9e539b6", - "closedLoopEventClient": "DCAE_INSTANCE_ID.dcae-tca", - "targetType": "VNF", - "target": "vserver.vserver-name", - "from": "policy:usecases", - "policyScope": "onap.policies.controlloop.Operational:1.0.0", - "policyName": "operational.scaleout.EVENT.MANAGER", - "policyVersion": "1.0.0", - "notification": "FINAL: SUCCESS", - "notificationTime": "2019-06-24 20:52:16.370000+00:00", - "history": [ - { - "actor": "SO", - "operation": "VF Module Create", - "target": "Target [type=VFMODULE, resourceId=null]", - "start": 1561409536125, - "end": 1561409536368, - "subRequestId": "1", - "outcome": "Success", - "message": "200 Success" - } - ] - } - -End of Document diff --git a/docs/drools/tutorial_vFW.rst b/docs/drools/tutorial_vFW.rst deleted file mode 100644 index fa21ec1d..00000000 --- a/docs/drools/tutorial_vFW.rst +++ /dev/null @@ -1,176 +0,0 @@ - -.. 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, it is assumed that the set up steps from section -*Using the Control Loop PDP-D docker image for standalone testing* has been followed. - -Running the Flow -^^^^^^^^^^^^^^^^ - -**Step 1:** Deploy the vFW Operational Policy. - - .. code-block:: bash - - cat pdp-update-vfw.json - { - "policies": [ - { - "type": "onap.policies.controlloop.Operational", - "type_version": "1.0.0", - "properties": { - "content": "controlLoop%3A%0A++++version%3A+2.0.0%0A++++controlLoopName%3A+ControlLoop-vFirewall-135835e3-eed7-497a-83ab-8c315f37fa4a%0A++++trigger_policy%3A+unique-policy-id-1-modifyConfig%0A++++timeout%3A+1200%0A++++abatement%3A+false%0Apolicies%3A%0A++++-+id%3A+unique-policy-id-1-modifyConfig%0A++++++name%3A+modify_packet_gen_config%0A++++++description%3A%0A++++++actor%3A+APPC%0A++++++recipe%3A+ModifyConfig%0A++++++target%3A%0A++++++++++resourceID%3A+Eace933104d443b496b8.nodes.heat.vpg%0A++++++++++type%3A+VNF%0A++++++payload%3A%0A++++++++++streams%3A+%27%7B%22active-streams%22%3A5%7D%27%0A++++++retry%3A+0%0A++++++timeout%3A+300%0A++++++success%3A+final_success%0A++++++failure%3A+final_failure%0A++++++failure_timeout%3A+final_failure_timeout%0A++++++failure_retries%3A+final_failure_retries%0A++++++failure_exception%3A+final_failure_exception%0A++++++failure_guard%3A+final_failure_guard%0A" - }, - "name": "operational.modifyconfig", - "version": "1.0.0" - } - ], - "messageName": "PDP_UPDATE", - "requestId": "a7a32d3b-37b4-4fb7-9322-b90c6a6fe365", - "timestampMs": 1556125347251, - "name": "pdpd", - "pdpGroup": "controlloop", - "pdpSubgroup": "drools" - } - - http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/POLICY-PDP-PAP/events @pdp-update-vfw.json Content-Type:'text/plain' - - telemetry - > get controllers/usecases/drools/facts/usecases/controlloops - > get controllers/usecases/drools/facts/usecases/controlloops/ControlLoop-vFirewall-135835e3-eed7-497a-83ab-8c315f37fa4a - -**Step 2:** Inject a simulated *ONSET* message. - - .. code-block:: bash - - cat dcae.vfw.onset.json - { - "closedLoopControlName": "ControlLoop-vFirewall-135835e3-eed7-497a-83ab-8c315f37fa4a", - "closedLoopAlarmStart": 1463679805324, - "closedLoopEventClient": "microservice.stringmatcher", - "closedLoopEventStatus": "ONSET", - "requestID": "c7c6a4aa-bb61-4a15-b831-ba1472dd4a65", - "target_type": "VNF", - "target": "generic-vnf.vnf-id", - "AAI": { - "generic-vnf.is-closed-loop-disabled": "false", - "generic-vnf.prov-status": "ACTIVE", - "generic-vnf.vnf-id": "fw0002vm002fw002" - }, - "from": "DCAE", - "version": "1.0.2" - } - - # activate NOOP sources - - http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/DCAE_TOPIC/switches/activation - - http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/APPC-CL/switches/activation - - http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/DCAE_TOPIC/events @dcae.vfw.onset.json Content-Type:'text/plain' # send onset - -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. - -There should be 8 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. - -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 - -**Step 3:** Inject an APPC response in the APPC-CL topic - -A simulated APPC response will be injected to the APPC-CL topic. - - .. code-block:: bash - - cat appc.legacy.success.json - { - "CommonHeader": { - "TimeStamp": 1506051879001, - "APIver": "1.01", - "RequestID": "c7c6a4aa-bb61-4a15-b831-ba1472dd4a65", - "SubRequestID": "1", - "RequestTrack": [], - "Flags": [] - }, - "Status": { - "Code": 400, - "Value": "SUCCESS" - }, - "Payload": { - "streams": { - "active-streams": 5.0 - }, - "generic-vnf.vnf-id": "7da01f3d-1e1f-374f-b049-f6385fe8d067" - } - } - - http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/APPC-CL/switches/activation # activate noop source - - http --verify=no -a "${TELEMETRY_USER}:${TELEMETRY_PASSWORD}" PUT https://localhost:9696/policy/pdp/engine/topics/sources/noop/APPC-CL/events @appc.legacy.success.json Content-Type:'text/plain' - -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 2 facts left in memory. - -End of Document |
