diff options
| author |   Peyton Puckett <peyton.puckett@att.com> | 2020-03-26 18:13:29 -0500 |
|---|---|---|
| committer | Peyton Puckett <peyton.puckett@att.com> | 2020-04-02 08:12:02 -0500 |
| commit | 32da597e59acbc9f59941cf78cea2b85cf1e5cd2 (patch) | |
| tree | 369ba8e4f728251bcea1256179ac68096aca0c4f /docs | |
| parent | 332b03d0f42734fcc1acfb3e79d86a64eb018732 (diff) | |
Update drools tutorials documentation
Issue-ID: POLICY-2399
Change-Id: I9756a660f80348eb69b217e6f1de6bad7a7b6f00
Signed-off-by: Peyton Puckett <peyton.puckett@att.com>
Diffstat (limited to 'docs')
31 files changed, 488 insertions, 69 deletions
diff --git a/docs/drools/RunEcl_frankfurt_project_explorer.png b/docs/drools/RunEcl_frankfurt_project_explorer.png Binary files differnew file mode 100644 index 00000000..4c1cf13d --- /dev/null +++ b/docs/drools/RunEcl_frankfurt_project_explorer.png diff --git a/docs/drools/clsimulation.rst b/docs/drools/clsimulation.rst index 8efff0a8..10276762 100644 --- a/docs/drools/clsimulation.rst +++ b/docs/drools/clsimulation.rst @@ -9,14 +9,42 @@ 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. +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: @@ -24,33 +52,48 @@ Use the command: http --verify=no --default-scheme=https -a <userName>:<password> PUT :9696/policy/pdp/engine/topics/sources/<comm>/<topic>/events @<onsetFile> Content-Type:"text/plain" -where <comm> is either "dmaap", "ueb", or "noop", depending on how the topic has been defined in the -configuration. "dmaap" is the default deployed messaging communication infrastructure in an ONAP installation. -The following is the equivalent "curl" version: +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 -The topic being used is *unauthenticated.DCAE_CL_OUTPUT*, which is subject to change. The onset file is a file that contains the data to inject as the onset. The data contained depends on the use case. This is an example for VoLTE: +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: VoLTE_Sample_Onset + :caption: vFirewall_Sample_Onset { - "closedLoopControlName": "ControlLoop-VOLTE-2179b738-fd36-4843-a71a-a8c24c70c55b", - "closedLoopAlarmStart": 1484677482204798, - "closedLoopEventClient": "DCAE.HolmesInstance", + "closedLoopControlName": "ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a", + "closedLoopAlarmStart": 1463679805324, + "closedLoopEventClient": "microservice.stringmatcher", "closedLoopEventStatus": "ONSET", - "requestID": "97964e10-686e-4790-8c45-bdfa61df770f", - "target_type": "VM", - "target": "vserver.vserver-name", + "requestID": "c7c6a4aa-bb61-4a15-b831-ba1472dd4a65", + "target_type": "VNF", + "target": "generic-vnf.vnf-name", "AAI": { "vserver.is-closed-loop-disabled": "false", - "vserver.vserver-name": "dfw1lb01lb01", - "service-instance.service-instance-id" : "vserver-name-16102016-aai3255-data-11-1", - "generic-vnf.vnf-id" : "vnf-id-16102016-aai3255-data-11-1", - "generic-vnf.vnf-name" : "vnf-name-16102016-aai3255-data-11-1" + "vserver.prov-status": "ACTIVE", + "generic-vnf.vnf-name": "fw0002vm002fw002", + "vserver.vserver-name": "OzVServer" }, "from": "DCAE", "version": "1.0.2" @@ -59,17 +102,44 @@ The topic being used is *unauthenticated.DCAE_CL_OUTPUT*, which is subject to ch Getting Information ------------------- -To get the name of the active controller(s), use: +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 -To check the facts currently in memory, use the following command. There should be 1 each of org.onap.policy.controlloop.PapParams and org.onap.policy.controlloop.Params per policy pushed. + # 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/<artifactId> | python -m json.tool + 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: @@ -77,16 +147,193 @@ To get additional information about the controller, use: 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: A&AI – 6666, SO – 6667, vFC – 6668, and guard – 6669. They all respond with hard-coded values representing their various success messages except for with certain inputs. For the A&AI simulator, if the value being queried with a “GET” query is “getFail” the simulator returns an exception message, if the value being queried in a “GET” query is “disableClosedLoop” the simulator returns a response with the value of “is-closed-loop-disabled” set to true, and if the value being queried in a named query is “error” the response from the simulator is A&AI’s failure message. The other simulator that can return multiple response is the guard simulator, and that returns a deny response if the closed loop control name passed in is “denyGuard” +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: "*features status*". If the feature controlloop-utils is enabled, the simulators are being used, otherwise, they are not. +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** @@ -99,24 +346,25 @@ To check the status of the simulators, run the command: "*features status*". If - 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*”. + - Finally restart the controller by running “*policy start*”. - Run “*features status*” again and the *feature controlloop-utils* will be **disabled**. **For Junits** - For Junits, the package *org.onap.policy.simulators* is neeeded. In the Util class, there are four methods to start the four different simulators: *buildAaiSim()*, *buildSoSim()*, *buildVfcSim()*, and *buildGuardSim()*. Once the method is called, the simulator should be up and waiting to respond to requests. To bring down the simulators, call *HttpServletServer.factory.destroy()*. + 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()*. -Responses ---------- +Sample Responses +^^^^^^^^^^^^^^^^ -**A&AI** +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-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", @@ -128,7 +376,7 @@ Responses "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 + "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": [{ @@ -174,7 +422,7 @@ Responses .. code-block:: bash :caption: vnf-GET-fail - //This is returned if you query on the value "getFail" + // This is returned if you query on the value "getFail" { "requestError": { "serviceException": { @@ -230,7 +478,7 @@ Responses .. code-block:: bash :caption: vserver-GET-error - //This is returned if you query on the value "getFail" + // This is returned if you query on the value "getFail" { "requestError": { "serviceException": { @@ -611,7 +859,8 @@ Responses } -**SO** +SO +------ .. code-block:: bash :caption: SO-response @@ -633,7 +882,8 @@ Responses -**vFC** +vFC +------- .. code-block:: bash :caption: vFC-POST-response @@ -671,7 +921,8 @@ Responses } -**GUARD** +GUARD +--------- .. code-block:: bash :caption: permit-response @@ -685,7 +936,7 @@ Responses .. code-block:: bash :caption: deny-response - //This is returned if the closed loop name is denyGuard + // This is returned if the closed loop name is denyGuard { "decision": "DENY", "details": "Decision Deny. You asked for it" diff --git a/docs/drools/droolsTutorialsIndex.rst b/docs/drools/droolsTutorialsIndex.rst index 008a821d..a1ccf844 100644 --- a/docs/drools/droolsTutorialsIndex.rst +++ b/docs/drools/droolsTutorialsIndex.rst @@ -8,11 +8,10 @@ PDP-D Tutorials .. toctree:: :maxdepth: 1 - clsimulation.rst - guardpdp.rst - modAAIdata.rst - modAmsterTemplate.rst - runningEclipse.rst + runningPDPD.rst + clsimulation.rst + guardpdp.rst + modAAIdata.rst tutorial_cl.rst tutorial_vCPE.rst tutorial_vDNS.rst diff --git a/docs/drools/guardpdp.rst b/docs/drools/guardpdp.rst index 797557fc..0fdb4ab2 100644 --- a/docs/drools/guardpdp.rst +++ b/docs/drools/guardpdp.rst @@ -3,23 +3,23 @@ .. http://creativecommons.org/licenses/by/4.0 ************************ -Using guard in the PDP-D +Using guard in the PDP-D ************************ .. contents:: :depth: 2 -This guide will help configure and test guard connection from PDP-D to PDP-X. This guide assumes that the PDP-D is installed and running policy properly with other properties being set properly. +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* +- 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 @@ -39,7 +39,7 @@ Guard Properties **guard.disabled** - For enabling / disabling guard functionality. - For example, to enable set it to false. - - When this is set to true, the previous two properties will be ignored. + - 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. @@ -63,16 +63,16 @@ For testing these properties before running policy, see Verification below. **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. +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 ---------------- @@ -80,29 +80,29 @@ 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", diff --git a/docs/drools/img/docker/credentials.png b/docs/drools/img/docker/credentials.png Binary files differnew file mode 100644 index 00000000..6fa68498 --- /dev/null +++ b/docs/drools/img/docker/credentials.png diff --git a/docs/drools/img/docker/dockerComposeDown.png b/docs/drools/img/docker/dockerComposeDown.png Binary files differnew file mode 100644 index 00000000..057a5197 --- /dev/null +++ b/docs/drools/img/docker/dockerComposeDown.png diff --git a/docs/drools/img/docker/dockerComposeUp.png b/docs/drools/img/docker/dockerComposeUp.png Binary files differnew file mode 100644 index 00000000..2bd73aa5 --- /dev/null +++ b/docs/drools/img/docker/dockerComposeUp.png diff --git a/docs/drools/img/docker/exampleTopics.png b/docs/drools/img/docker/exampleTopics.png Binary files differnew file mode 100644 index 00000000..17d0a559 --- /dev/null +++ b/docs/drools/img/docker/exampleTopics.png diff --git a/docs/drools/img/docker/getControllers.png b/docs/drools/img/docker/getControllers.png Binary files differnew file mode 100644 index 00000000..8d2065b0 --- /dev/null +++ b/docs/drools/img/docker/getControllers.png diff --git a/docs/drools/img/docker/getEngine.png b/docs/drools/img/docker/getEngine.png Binary files differnew file mode 100644 index 00000000..9811329a --- /dev/null +++ b/docs/drools/img/docker/getEngine.png diff --git a/docs/drools/img/docker/getEnvironment.png b/docs/drools/img/docker/getEnvironment.png Binary files differnew file mode 100644 index 00000000..0131505a --- /dev/null +++ b/docs/drools/img/docker/getEnvironment.png diff --git a/docs/drools/img/docker/getFeatures.png b/docs/drools/img/docker/getFeatures.png Binary files differnew file mode 100644 index 00000000..9d1239cd --- /dev/null +++ b/docs/drools/img/docker/getFeatures.png diff --git a/docs/drools/img/docker/getFrankfurt.png b/docs/drools/img/docker/getFrankfurt.png Binary files differnew file mode 100644 index 00000000..78df267d --- /dev/null +++ b/docs/drools/img/docker/getFrankfurt.png diff --git a/docs/drools/img/docker/policyStatus.png b/docs/drools/img/docker/policyStatus.png Binary files differnew file mode 100644 index 00000000..de8199bd --- /dev/null +++ b/docs/drools/img/docker/policyStatus.png diff --git a/docs/drools/img/docker/telemetryCmd.png b/docs/drools/img/docker/telemetryCmd.png Binary files differnew file mode 100644 index 00000000..7b1f358f --- /dev/null +++ b/docs/drools/img/docker/telemetryCmd.png diff --git a/docs/drools/img/docker/yamlClone.png b/docs/drools/img/docker/yamlClone.png Binary files differnew file mode 100644 index 00000000..ecf0f6e6 --- /dev/null +++ b/docs/drools/img/docker/yamlClone.png diff --git a/docs/drools/img/eclipse/consoleOutputExample.png b/docs/drools/img/eclipse/consoleOutputExample.png Binary files differnew file mode 100644 index 00000000..9dabb8b0 --- /dev/null +++ b/docs/drools/img/eclipse/consoleOutputExample.png diff --git a/docs/drools/img/eclipse/importMavenProject.png b/docs/drools/img/eclipse/importMavenProject.png Binary files differnew file mode 100644 index 00000000..1416b4c2 --- /dev/null +++ b/docs/drools/img/eclipse/importMavenProject.png diff --git a/docs/drools/img/eclipse/mainAppSelection.png b/docs/drools/img/eclipse/mainAppSelection.png Binary files differnew file mode 100644 index 00000000..f562bf6d --- /dev/null +++ b/docs/drools/img/eclipse/mainAppSelection.png diff --git a/docs/drools/img/eclipse/runAsJavaApp.png b/docs/drools/img/eclipse/runAsJavaApp.png Binary files differnew file mode 100644 index 00000000..e1f26186 --- /dev/null +++ b/docs/drools/img/eclipse/runAsJavaApp.png diff --git a/docs/drools/img/eclipse/selectDirectory.png b/docs/drools/img/eclipse/selectDirectory.png Binary files differnew file mode 100644 index 00000000..c1db03f7 --- /dev/null +++ b/docs/drools/img/eclipse/selectDirectory.png diff --git a/docs/drools/img/eclipse/selectProjectsToImport.png b/docs/drools/img/eclipse/selectProjectsToImport.png Binary files differnew file mode 100644 index 00000000..395fdb31 --- /dev/null +++ b/docs/drools/img/eclipse/selectProjectsToImport.png diff --git a/docs/drools/img/frankfurt_project_explorer.png b/docs/drools/img/frankfurt_project_explorer.png Binary files differnew file mode 100644 index 00000000..4c1cf13d --- /dev/null +++ b/docs/drools/img/frankfurt_project_explorer.png diff --git a/docs/drools/img/frankfurt_project_explorer2.png b/docs/drools/img/frankfurt_project_explorer2.png Binary files differnew file mode 100644 index 00000000..bee1f422 --- /dev/null +++ b/docs/drools/img/frankfurt_project_explorer2.png diff --git a/docs/drools/modAAIdata.rst b/docs/drools/modAAIdata.rst index 220d38f4..eef0d0c4 100644 --- a/docs/drools/modAAIdata.rst +++ b/docs/drools/modAAIdata.rst @@ -49,7 +49,10 @@ Follow these steps to get all of the vservers. This is useful to get a couple o curl --silent -k -u "<userName>:<password>" --header "X-FromAppId: <fromApp>" --header "Content-Type: application/json" --header "Accept: application/json" --header "X-TransactionId: <requestID>" -X GET https://aai.api.simpledemo.openecomp.org:8443/aai/v11/cloud-infrastructure/cloud-regions | python -m json.tool - Take note of all the cloud-owner/cloud-region combinations. In this example, there are 3 combinations: Skynet/CL-MR1, AMIST/AMCR1, and Rackspace/DFW. + 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 diff --git a/docs/drools/modAmsterTemplate.rst b/docs/drools/modTemplate.rst index 4456f292..1e02a0c8 100644 --- a/docs/drools/modAmsterTemplate.rst +++ b/docs/drools/modTemplate.rst @@ -9,11 +9,10 @@ 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... @@ -39,7 +38,7 @@ Installing the Archetype Project in Eclipse .. image:: mat_add_local_catalog.JPG - **STEP 5.1.2:** Add the ONAP Staging repository archetype-catalog.xml with a description if desired. Click "OK" then "Apply", then "OK". + **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 @@ -84,7 +83,9 @@ Installing the Archetype Project in Eclipse 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: diff --git a/docs/drools/runningEclipse.rst b/docs/drools/runningEclipse.rst index 136efe73..5123a540 100644 --- a/docs/drools/runningEclipse.rst +++ b/docs/drools/runningEclipse.rst @@ -3,7 +3,7 @@ .. http://creativecommons.org/licenses/by/4.0 ************************ -Running PDP-D in Eclipse +Running PDP-D in Eclipse ************************ .. contents:: @@ -12,10 +12,11 @@ Running PDP-D in Eclipse This tutorial is intended for developers who would like to run the PDP-D in an Eclipse environment. It is assumed that the drools-pdp git project has been imported in an Eclipse workspace. Starting the PDP-D -^^^^^^^^^^^^^^^^^^ -For the Amsterdam release, the project directory will look as follows assuming all drools-pdp projects were selected when importing. +^^^^^^^^^^^^^^^^^^ - .. image:: RunEcl_drools_pdp_project.png +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" @@ -32,11 +33,11 @@ The PDP-D will start running; the console will display output. 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. +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 @1b3rt:31nst31n -X GET https://localhost:9696/policy/pdp/engine/ | python -m json.tool + curl -k --silent --user <username>:<password> -X GET https://localhost:9696/policy/pdp/engine/ | python -m json.tool .. image:: RunEcl_telemetry.png @@ -47,6 +48,8 @@ An HTTP 200 message for the GET request will also appear in the console in Eclip .. 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 diff --git a/docs/drools/runningPDPD.rst b/docs/drools/runningPDPD.rst new file mode 100644 index 00000000..0934c8c9 --- /dev/null +++ b/docs/drools/runningPDPD.rst @@ -0,0 +1,164 @@ +.. 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 index ee719cab..d7c2430c 100644 --- a/docs/drools/tutorial_cl.rst +++ b/docs/drools/tutorial_cl.rst @@ -101,7 +101,7 @@ Proceed with testing your new policy as described in the specific tutorials: • 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:: To deploy a control loop in Eclipse from the control loop archetype template, refer to `Modifying the Release Template <modAmsterTemplate.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 index d22747ed..2bda592b 100644 --- a/docs/drools/tutorial_vCPE.rst +++ b/docs/drools/tutorial_vCPE.rst @@ -9,7 +9,6 @@ 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. diff --git a/docs/drools/tutorial_vFW.rst b/docs/drools/tutorial_vFW.rst index 02ebb7ad..fa21ec1d 100644 --- a/docs/drools/tutorial_vFW.rst +++ b/docs/drools/tutorial_vFW.rst @@ -9,7 +9,6 @@ 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. |
