From b0c7e3bd5a3fa546c1f87298ca4312b728a25495 Mon Sep 17 00:00:00 2001 From: Saryu Shah Date: Tue, 1 May 2018 01:12:23 +0000 Subject: [PATCH] Updated installation documentation Updated installation documentation ------------------------------------------------------------- Change-Id: I71d24c0806fc5d53691c505f87425c71e2f0a04f Issue-ID: POLICY-536 Signed-off-by: Saryu Shah --- docs/platform/index.rst | 12 +- docs/platform/installAmsterController.rst | 325 ++++++++++++++++++++++++ docs/platform/installBeijingController.rst | 384 +++++++++++++++++++++++++++++ docs/platform/installation.rst | 92 +++---- docs/platform/installationVM.rst | 269 ++++++++++++++++++++ 5 files changed, 1028 insertions(+), 54 deletions(-) create mode 100644 docs/platform/installAmsterController.rst create mode 100644 docs/platform/installBeijingController.rst create mode 100644 docs/platform/installationVM.rst diff --git a/docs/platform/index.rst b/docs/platform/index.rst index c0cbaa3f4..3f58f353e 100644 --- a/docs/platform/index.rst +++ b/docs/platform/index.rst @@ -8,10 +8,20 @@ Policy Engine Platform architecture.rst offeredapis.rst - installation.rst policygui.rst deployment.rst +Policy Installation +------------------- + +.. toctree:: + :maxdepth: 1 + + installation.rst + installationVM.rst + installAmsterController.rst + installBeijingController.rst + Policy Software Architecture ---------------------------- diff --git a/docs/platform/installAmsterController.rst b/docs/platform/installAmsterController.rst new file mode 100644 index 000000000..d294865f9 --- /dev/null +++ b/docs/platform/installAmsterController.rst @@ -0,0 +1,325 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Installation of Amsterdam Controller and vCPE Policy +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. contents:: + :depth: 2 + +This article explains how to install the Amsterdam policy controller and the Amsterdam policies on a raw ONAP Policy Framework installation running in Docker. + +To build a raw Policy Framework installation, please follow either of the HowTo articles below prior to using this HowTo: + + * `Standalone Quick Start `_ + * `Standalone installation in Virtual Machine `_ + +You should have the ONAP Policy Framework running in Docker and started the Policy Framework with *docker-compose*. + + +Test that the ONAP Policy Framework is up and is empty +------------------------------------------------------ + +**Step 1:** Run the command below. + + .. code-block:: bash + + curl --silent --user @1b3rt:31nst31n -X GET http://localhost:9696/policy/pdp/engine/controllers/amsterdam | python -m json.tool + + You should get a response similar to the following: + + .. code-block:: bash + + { + "error": "amsterdam not found" + } + +Install the Amsterdam policy controller +--------------------------------------- + +**Step 1:** Log onto the Drools PDP. + + .. code-block:: bash + + docker exec -it drools bash + + You now have a shell open in the Drools PDP container running in docker + + +**Step 2:** Create a temporary directory for controller installation + + .. code-block:: bash + + mkdir /tmp/apps-controlloop + cd /tmp/apps-controlloop + +**Step 3:** Download the latest controller from Nexus (1.2.0 at the time of writing) + + .. code-block:: bash + + wget https://nexus.onap.org/content/repositories/releases/org/onap/policy/drools-applications/controlloop/packages/apps-controlloop/1.2.0/apps-controlloop-1.2.0.zip + +**Step 4:** Unzip the controller + + .. code-block:: bash + + unzip apps-controlloop-1.2.0.zip + +**Step 5:** Stop the policy engine + + .. code-block:: bash + + policy stop + +**Step 6:** Install the controller by running the controller installation script + + .. code-block:: bash + + ./apps-controlloop-installer + +**Step 7:** Install the controlloop-utils Drools PDP feature to allow standalone execution of control loop policies + + .. code-block:: bash + + features install controlloop-utils + features enable controlloop-utils + +**Step 8:** Start the policy engine + + .. code-block:: bash + + policy start + +**Step 9:** Check if the Amsterdam controller is loaded + .. code-block:: bash + + curl --silent --user @1b3rt:31nst31n -X GET http://localhost:9696/policy/pdp/engine/controllers/amsterdam | python -m json.tool + + You should get a response similar to the following: + + .. code-block:: bash + :caption: Amsterdam Controller JSON Response + :linenos: + + { + "alive": true, + "drools": { + "alive": false, + "artifactId": "NO-ARTIFACT-ID", + "brained": false, + "canonicalSessionNames": [], + "container": null, + "groupId": "NO-GROUP-ID", + "locked": false, + "recentSinkEvents": [], + "recentSourceEvents": [], + "sessionNames": [], + "version": "NO-VERSION" + }, + "locked": false, + "name": "amsterdam", + "topicSinks": [ + { + "alive": true, + "allowSelfSignedCerts": false, + "apiKey": "", + "apiSecret": "", + "locked": false, + "partitionKey": "ea44d32e-e2e6-4a77-862b-aa33437179ed", + "recentEvents": [], + "servers": [ + "vm1.mr.simpledemo.openecomp.org" + ], + "topic": "APPC-CL", + "topicCommInfrastructure": "UEB", + "useHttps": false + }, + { + "alive": true, + "allowSelfSignedCerts": false, + "apiKey": "", + "apiSecret": "", + "locked": false, + "partitionKey": "47769d22-03c8-4993-9f67-fe326a491b23", + "recentEvents": [], + "servers": [ + "vm1.mr.simpledemo.openecomp.org" + ], + "topic": "APPC-LCM-READ", + "topicCommInfrastructure": "UEB", + "useHttps": false + }, + { + "alive": true, + "allowSelfSignedCerts": false, + "apiKey": "", + "apiSecret": "", + "locked": false, + "partitionKey": "c33ca5ca-6ebd-47d7-a495-5a54f8a2a15a", + "recentEvents": [], + "servers": [ + "vm1.mr.simpledemo.openecomp.org" + ], + "topic": "POLICY-CL-MGT", + "topicCommInfrastructure": "UEB", + "useHttps": false + } + ], + "topicSources": [ + { + "alive": true, + "allowSelfSignedCerts": false, + "apiKey": "", + "apiSecret": "", + "consumerGroup": "6dcfdfb8-7c54-4dbd-9337-e4f1883083fb", + "consumerInstance": "drools", + "fetchLimit": 100, + "fetchTimeout": 15000, + "locked": false, + "recentEvents": [], + "servers": [ + "vm1.mr.simpledemo.openecomp.org" + ], + "topic": "unauthenticated.DCAE_CL_OUTPUT", + "topicCommInfrastructure": "UEB", + "useHttps": false + }, + { + "alive": true, + "allowSelfSignedCerts": false, + "apiKey": "", + "apiSecret": "", + "consumerGroup": "4f558331-3d32-494b-b7dc-4d5a509dda0d", + "consumerInstance": "drools", + "fetchLimit": 100, + "fetchTimeout": 15000, + "locked": false, + "recentEvents": [], + "servers": [ + "vm1.mr.simpledemo.openecomp.org" + ], + "topic": "APPC-CL", + "topicCommInfrastructure": "UEB", + "useHttps": false + }, + { + "alive": true, + "allowSelfSignedCerts": false, + "apiKey": "", + "apiSecret": "", + "consumerGroup": "1e3edc1f-afa6-4ae5-907f-a7118ad7a0d2", + "consumerInstance": "drools", + "fetchLimit": 100, + "fetchTimeout": 15000, + "locked": false, + "recentEvents": [], + "servers": [ + "vm1.mr.simpledemo.openecomp.org" + ], + "topic": "APPC-LCM-WRITE", + "topicCommInfrastructure": "UEB", + "useHttps": false + } + ] + } + + +Install the Amsterdam vCPE Policy +--------------------------------- + +We now install the Amsterdam policies for the vCPE, vFirewall, vDNS & VOLTE use cases. + +**Step 1:** Log onto (or remain logged onto) the Drools PDP. + + .. code-block:: bash + + docker exec -it drools bash + + You now have a shell open in the Drools PDP container running in docker + +**Step 2:** Check that the Amsterdam policies are not loaded by querying for Drools facts + + .. code-block:: bash + + curl --silent --user @1b3rt:31nst31n -X GET http://localhost:9696/policy/pdp/engine/controllers/amsterdam/drools/facts/amsterdam | python -m json.tool + + Expect the response {} indicating no policies are loaded. + +**Step 3:** Create a temporary directory for policy installation + + .. code-block:: bash + + mkdir /tmp/basex-controlloop + cd /tmp/basex-controlloop + +**Step 4:** Extract the policies from the control loop zip file previously downloaded from Nexus and expanded in steps 3 and 4 above. + + .. code-block:: bash + + tar zxvf /tmp/apps-controlloop/basex-controlloop-1.2.0.tar.gz + +**Step 5:** Install the Amsterdam policy rules, the script asks for a number of input parameters, accept the default for all parameters + + .. code-block:: bash + + bin/create-cl-amsterdam + + - Type Y when asked for confirmation of parameters + - Accept /tmp as the install directory + - Type Y to agree to creation of a Maven Artifact + + +**Step 6:** Maven artifact creation now proceeds. After some minutes, confirmation is requested for deployment of rules into Maven. + .. code-block:: bash + + - Type Y to deploy the rules. + + The rules are deployed into Maven. Expect the rule deployment process to take a number of minutes, perhaps 10 minutes. + + +**Step 7:** Copy the Amsterdam properties file into the Drools PDP configuration directory. This file configures the Drools PDP with the Amsterdam policies + + .. code-block:: bash + + cp /tmp/amsterdam/amsterdam-controller.properties /opt/app/policy/config + +**Step 8:** Stop and start the Drools PDP + + .. code-block:: bash + + policy stop + policy start + +**Step 9:** Now verify that the Amsterdam policies are loaded, there should be a fact in the Drools PDP + + .. code-block:: bash + + curl --silent --user @1b3rt:31nst31n -X GET http://localhost:9696/policy/pdp/engine/controllers/amsterdam/drools/facts/amsterdam | python -m json.tool + + Expect the response: + + .. code-block:: bash + + { + "org.onap.policy.controlloop.Params": 1 + } + + +Execute the vCPE Use Case Manually +---------------------------------- + +You can now run the vCPE Policy use case manually using the HowTos below: + * `Tutorial: Testing the vCPE use case in a standalone PDP-D `_ + +.. note:: + 1. You should check that the topic names you use match those in the Amsterdam configuration file */opt/app/policy/config/amsterdam-controller.properties*. + 2. You should ensure that you change to the directory */tmp/amsterdam* prior to running those HowTos + + + +.. Installation of Amsterdam Controller and vCPE Policy : https://wiki.onap.org/display/DW/ONAP+Policy+Framework%3A+Installation+of+Amsterdam+Controller+and+vCPE+Policy + + + +End of Document + diff --git a/docs/platform/installBeijingController.rst b/docs/platform/installBeijingController.rst new file mode 100644 index 000000000..deb2ebb35 --- /dev/null +++ b/docs/platform/installBeijingController.rst @@ -0,0 +1,384 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Installation of Beijing Controller and vCPE Policy +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. contents:: + :depth: 2 + +This article explains how to install the Beijing policy controller and the Beijing policies on a raw ONAP Policy Framework installation running in Docker. + +To build a raw Policy Framework installation, please follow either of the HowTo articles below prior to using this HowTo: + + * `Standalone Quick Start `_ + * `Standalone installation in Virtual Machine `_ + +You should have the ONAP Policy Framework running in Docker and started the Policy Framework with *docker-compose*. + + +Test that the ONAP Policy Framework is up and is empty +------------------------------------------------------ + +**Step 1:** Run the command below. + + .. code-block:: bash + + curl --silent --user @1b3rt:31nst31n -X GET http://localhost:9696/policy/pdp/engine/controllers/beijing | python -m json.tool + + You should get a response similar to the following: + + .. code-block:: bash + + { + "error": "beijing not found" + } + +Install the Beijing policy controller +--------------------------------------- + +**Step 1:** Log onto the Drools PDP. + + .. code-block:: bash + + docker exec -it drools bash + + You now have a shell open in the Drools PDP container running in docker + + +**Step 2:** Create a temporary directory for controller installation + + .. code-block:: bash + + mkdir /tmp/apps-controlloop + cd /tmp/apps-controlloop + +**Step 3:** Download the latest controller from Nexus (1.2.0 at the time of writing) + + .. code-block:: bash + + wget https://nexus.onap.org/content/repositories/releases/org/onap/policy/drools-applications/controlloop/packages/apps-controlloop/1.2.0/apps-controlloop-1.2.0.zip + + Alternatively, you can build the drools-applications component of the Policy Framework from source and install it from the following location on your build host + + .. code-block:: bash + + ~/.m2/repository/org/onap/policy/drools-applications/controlloop/packages/apps-controlloop/1.2.0/apps-controlloop-1.2.0.zip + + +**Step 4:** Unzip the controller + + .. code-block:: bash + + unzip apps-controlloop-1.2.0.zip + +**Step 5:** Update the installation script to install the Beijing controller + + .. code-block:: bash + + vi apps-controlloop-installer + + Change the line + "features enable controlloop-amsterdam" + to + "features enable controlloop-beijing" + + +**Step 6:** Stop the policy engine + + .. code-block:: bash + + policy stop + +**Step 7:** Install the controller by running the controller installation script + + .. code-block:: bash + + ./apps-controlloop-installer + +**Step 8:** Install the *controlloop-utils* Drools PDP feature to allow standalone execution of control loop policies + + .. code-block:: bash + + features install controlloop-utils + features enable controlloop-utils + +**Step 9:** Start the policy engine + + .. code-block:: bash + + policy start + + Monitor the CPU for a few minutes with the top command until it settles down after the policy start. + +**Step 10:** Check if the Beijing controller is loaded + .. code-block:: bash + + curl --silent --user @1b3rt:31nst31n -X GET http://localhost:9696/policy/pdp/engine/controllers/beijing | python -m json.tool + + You should get a response similar to the following: + + .. code-block:: bash + :caption: Beijing Controller JSON Response + :linenos: + + "alive": true, + "drools": { + "alive": true, + "artifactId": "controller-beijing", + "brained": true, + "groupId": "org.onap.policy.drools-applications.controlloop.common", + "locked": false, + "modelClassLoaderHash": 1562533966, + "recentSinkEvents": [], + "recentSourceEvents": [], + "sessionCoordinates": [ + "org.onap.policy.drools-applications.controlloop.common:controller-beijing:1.2.0:beijing" + ], + "sessions": [ + "beijing" + ], + "version": "1.2.0" + }, + "locked": false, + "name": "beijing", + "topicSinks": [ + { + "alive": true, + "allowSelfSignedCerts": false, + "apiKey": "", + "apiSecret": "", + "locked": false, + "partitionKey": "86d1234b-e431-4191-b7c6-56d2d2909a97", + "recentEvents": [], + "servers": [ + "vm1.mr.simpledemo.openecomp.org" + ], + "topic": "APPC-CL", + "topicCommInfrastructure": "UEB", + "useHttps": false + }, + { + "alive": true, + "allowSelfSignedCerts": false, + "apiKey": "", + "apiSecret": "", + "locked": false, + "partitionKey": "dea0f440-0232-4f63-b79e-6d51f3674d35", + "recentEvents": [], + "servers": [ + "vm1.mr.simpledemo.openecomp.org" + ], + "topic": "APPC-LCM-READ", + "topicCommInfrastructure": "UEB", + "useHttps": false + }, + { + "alive": true, + "allowSelfSignedCerts": false, + "apiKey": "", + "apiSecret": "", + "locked": false, + "partitionKey": "2918d779-870d-429b-b469-78677d027deb", + "recentEvents": [], + "servers": [ + "vm1.mr.simpledemo.openecomp.org" + ], + "topic": "POLICY-CL-MGT", + "topicCommInfrastructure": "UEB", + "useHttps": false + } + ], + "topicSources": [ + { + "alive": true, + "allowSelfSignedCerts": false, + "apiKey": "", + "apiSecret": "", + "consumerGroup": "31740f8e-f878-4347-849e-3b3352c28dff", + "consumerInstance": "drools", + "fetchLimit": 100, + "fetchTimeout": 15000, + "locked": false, + "recentEvents": [], + "servers": [ + "vm1.mr.simpledemo.openecomp.org" + ], + "topic": "PDPD-CONFIGURATION", + "topicCommInfrastructure": "UEB", + "useHttps": false + }, + { + "alive": true, + "allowSelfSignedCerts": false, + "apiKey": "", + "apiSecret": "", + "consumerGroup": "429aa858-633e-43dc-8619-7004e133d650", + "consumerInstance": "drools", + "fetchLimit": 100, + "fetchTimeout": 15000, + "locked": false, + "recentEvents": [], + "servers": [ + "vm1.mr.simpledemo.openecomp.org" + ], + "topic": "unauthenticated.DCAE_CL_OUTPUT", + "topicCommInfrastructure": "UEB", + "useHttps": false + }, + { + "alive": true, + "allowSelfSignedCerts": false, + "apiKey": "", + "apiSecret": "", + "consumerGroup": "1bf6854d-a0f1-4d03-baaf-084e6f365a86", + "consumerInstance": "drools", + "fetchLimit": 100, + "fetchTimeout": 15000, + "locked": false, + "recentEvents": [], + "servers": [ + "vm1.mr.simpledemo.openecomp.org" + ], + "topic": "APPC-CL", + "topicCommInfrastructure": "UEB", + "useHttps": false + }, + { + "alive": true, + "allowSelfSignedCerts": false, + "apiKey": "", + "apiSecret": "", + "consumerGroup": "3f0d7fdf-956d-4749-be54-1adb32ccfa4f", + "consumerInstance": "drools", + "fetchLimit": 100, + "fetchTimeout": 15000, + "locked": false, + "recentEvents": [], + "servers": [ + "vm1.mr.simpledemo.openecomp.org" + ], + "topic": "APPC-LCM-WRITE", + "topicCommInfrastructure": "UEB", + "useHttps": false + } + ] + } + + + +Install the Beijing vCPE Policy +--------------------------------- + +We now install the Beijing policies for the vCPE, vFirewall, vDNS & VOLTE use cases. + +**Step 1:** Log onto (or remain logged onto) the Drools PDP. + + .. code-block:: bash + + docker exec -it drools bash + + You now have a shell open in the Drools PDP container running in docker + +**Step 2:** Check that the Beijing policies are not loaded by querying for Drools facts + + .. code-block:: bash + + curl --silent --user @1b3rt:31nst31n -X GET http://localhost:9696/policy/pdp/engine/controllers/beijing/drools/facts/beijing | python -m json.tool + + Expect the response {} indicating no policies are loaded. + +**Step 3:** Create a temporary directory for policy installation + + .. code-block:: bash + + mkdir /tmp/basex-controlloop + cd /tmp/basex-controlloop + +**Step 4:** Extract the policies from the control loop zip file previously downloaded from Nexus and expanded in steps 3 and 4 above. + + .. code-block:: bash + + tar zxvf /tmp/apps-controlloop/basex-controlloop-1.2.0.tar.gz + +**Step 5:** Install the Beijing policy rules, the script asks for a number of input parameters, accept the default for all parameters + + .. code-block:: bash + + bin/create-cl-beijing + + - Type Y when asked for confirmation of parameters + - Accept /tmp as the install directory + - Type Y to agree to creation of a Maven Artifact + + +**Step 6:** Maven artifact creation now proceeds. After some minutes, confirmation is requested for deployment of rules into Maven. + .. code-block:: bash + + - Type Y to deploy the rules. + + The rules are deployed into Maven. Expect the rule deployment process to take a number of minutes, perhaps 10 minutes. + + +**Step 7:** Copy the Beijing properties file into the Drools PDP configuration directory. This file configures the Drools PDP with the Beijing policies + + .. code-block:: bash + + cp /tmp/beijing/beijing-controller.properties /opt/app/policy/config + +**Step 8:** Stop and start the Drools PDP + + .. code-block:: bash + + policy stop + policy start + + Again, monitor the processes with top and wait for the PDP to fully start. + +**Step 9:** Push the Beijing policy facts to the Drools PDP + + .. code-block:: bash + + bin/push-policies-beijing + + When the script prompts for the path to the properties file, enter the following: + /opt/app/policy/config/beijing-controller.properties + + +**Step 10:** Now verify that the Beijing policies are loaded, there should be four facts (one per use case) in the Drools PDP + + .. code-block:: bash + + curl --silent --user @1b3rt:31nst31n -X GET http://localhost:9696/policy/pdp/engine/controllers/beijing/drools/facts/beijing | python -m json.tool + + Expect the response: + + .. code-block:: bash + + { + "org.onap.policy.controlloop.params.ControlLoopParams": 4 + } + + +Execute the vCPE Use Case Manually +---------------------------------- + +You can now run the vCPE Policy use case manually using the HowTos below: + * `Tutorial: Testing the vCPE use case in a standalone PDP-D `_ + * `Tutorial: Testing the vDNS Use Case in a standalone PDP-D `_ + * `Tutorial: Testing the vFW flow in a standalone PDP-D `_ + * `Tutorial: Testing the VOLTE Use Case in a standalone PDP-D `_ + + +.. note:: + 1. You should check that the topic names you use match those in the Beijing configuration file */opt/app/policy/config/beijing-controller.properties*. + 2. You should ensure that you change to the directory */tmp/beijing* prior to running those HowTos + + + +.. Installation of Beijing Controller and Policies : https://wiki.onap.org/display/DW/ONAP+Policy+Framework%3A+Installation+of+Beijing+Controller+and+Policies + + + +End of Document + diff --git a/docs/platform/installation.rst b/docs/platform/installation.rst index d097b0a98..0f068ea8f 100644 --- a/docs/platform/installation.rst +++ b/docs/platform/installation.rst @@ -1,18 +1,15 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 -************ -Installation -************ +Standalone Quick Start Installation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. contents:: - :depth: 3 + :depth: 2 The installation of ONAP Policy is **automated** by design and can be done via Docker as a standalone system. Various tools, including healthcheck, logs, and Swagger can be used to ensure proper operation. -ONAP Policy Framework: Standalone Quick Start -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This article explains how to build the ONAP Policy Framework and get it running in Docker as a standalone system. This article assumes that: @@ -152,7 +149,7 @@ Execution of the script above results in the following directory hierarchy in yo Building ONAP ------------- -**Step 1.** Optionally, for a completely clean build, remove the ONAP built modules from your local repository. +**Step 1:** Optionally, for a completely clean build, remove the ONAP built modules from your local repository. .. code-block:: bash @@ -161,7 +158,7 @@ Building ONAP rm -fr ~/.m2/repisotory/com/att -**Step 2**. A pom such as the one below can be used to build the ONAP Policy Framework modules. Create the *pom.xml* file in the directory *~/git/onap/policy*. +**Step 2:** A pom such as the one below can be used to build the ONAP Policy Framework modules. Create the *pom.xml* file in the directory *~/git/onap/policy*. .. code-block:: xml :caption: Typical pom.xml to build the ONAP Policy Framework @@ -193,22 +190,12 @@ Building ONAP -**Step 3**. You can now build the ONAP framework +**Step 3:** You can now build the ONAP framework - * On *Ubuntu*, just build the Policy Framework tests and all - - .. code-block:: bash - - cd ~/git/onap - mvn clean install - - * On *macOS*, you must build build the ONAP framework with tests turned off first. Then rebuild the framework with tests turned on and all tests will pass. Note: The reason for this behaviour will be explored later. - - .. code-block:: bash + .. code-block:: bash - cd ~/git/onap - mvn clean install -DskipTests - mvn install + cd ~/git/onap + mvn clean install Building the ONAP Policy Framework Docker Images @@ -216,70 +203,69 @@ Building the ONAP Policy Framework Docker Images The instructions here are based on the instructions in the file *~/git/onap/policy/docker/README.md*. -**Step 1.** Build the policy engine docker image: +**Step 1:** Build the policy engine docker image: - .. code-block:: bash + .. code-block:: bash - cd ~/git/onap/policy/engine/packages/docker/target - docker build -t onap/policy-pe policy-pe + cd ~/git/onap/policy/engine/packages/docker/target + docker build -t onap/policy-pe policy-pe -**Step 2.** Build the Drools PDP docker image: +**Step 2:** Build the Drools PDP docker image: - .. code-block:: bash + .. code-block:: bash - cd ~/git/onap/policy/drools-pdp/packages/docker/target - docker build -t onap/policy-drools policy-drools + cd ~/git/onap/policy/drools-pdp/packages/docker/target + docker build -t onap/policy-drools policy-drools -**Step 3.** Build the Policy Nexus docker image: +Starting the ONAP Policy Framework Docker Images +------------------------------------------------ - .. code-block:: bash +In order to run the containers, you can use *docker-compose*. This uses the *docker-compose.yml* yaml file to bring up the ONAP Policy Framework. - cd ~/git/onap/policy/docker - docker build -t onap/policy-nexus policy-nexus +**Step 1:** Make the file config/drools/drools-tweaks.sh executable. + .. code-block:: bash -Starting the ONAP Policy Framework Docker Images ------------------------------------------------- + chmod +x config/drools/drools-tweaks.sh -In order to run the containers, you can use *docker-compose*. This uses the *docker-compose.yml* yaml file to bring up the ONAP Policy Framework. -**Step 1.** Make the file config/drools/drools-tweaks.sh executable. +**Step 2:** Set the IP address to use to be an IP address of a suitable interface on your machine. Save the IP address into the file *config/pe/ip_addr.txt*. - .. code-block:: bash - chmod +x config/drools/drools-tweaks.sh +**Step 3:** Set the environment variable *MTU* to be a suitable MTU size for the application. + .. code-block:: bash -**Step 2.** Set the IP address to use to be an IP address of a suitable interface on your machine. Save the IP address into the file *config/pe/ip_addr.txt*. + export MTU=9126 -**Step 3.** Set the environment variable *MTU* to be a suitable MTU size for the application. +**Step 4:** Determine if you want policies pre-loaded or not. By default, all the configuration and operational policies will be pre-loaded by the docker compose script. If you do not wish for that to happen, then export this variable: - .. code-block:: bash + .. code-block:: bash - export MTU=9126 + export PRELOAD_POLICIES=false -**Step 4.** Determine if you want policies pre-loaded or not. By default, all the configuration and operational policies will be pre-loaded by the docker compose script. If you do not wish for that to happen, then export this variable: +**Step 5:** Run the system using *docker-compose*. Note that on some systems you may have to run the *docker-compose* command as root or using *sudo*. Note that this command takes a number of minutes to execute on a laptop or desktop computer. - .. code-block:: bash + .. code-block:: bash - export PRELOAD_POLICIES=false + docker-compose up -**Step 5.** Run the system using *docker-compose*. Note that on some systems you may have to run the *docker-compose* command as root or using *sudo*. Note that this command takes a number of minutes to execute on a laptop or desktop computer. +**You now have a full standalone ONAP Policy framework up and running!** - .. code-block:: bash - docker-compose up +Installation of Controllers and Policies +---------------------------------------- +You may now install a controller and policies on the ONAP Policy Framework. Follow either of the HowTos below to install either the Amsterdam or Beijing controller and policies. -Installation Complete ---------------------- + * `Installation of Amsterdam Controller and vCPE Policy `_ + * `Installation of Beijing Controller and Policies `_ -**You now have a full standalone ONAP Policy framework up and running!** .. _Standalone Quick Start : https://wiki.onap.org/display/DW/ONAP+Policy+Framework%3A+Standalone+Quick+Start diff --git a/docs/platform/installationVM.rst b/docs/platform/installationVM.rst new file mode 100644 index 000000000..e690497aa --- /dev/null +++ b/docs/platform/installationVM.rst @@ -0,0 +1,269 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Standalone Installation in Virtual Machine +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. contents:: + :depth: 2 + +Overview +--------- + +This document explains the steps required to install ONAP policy framework in a standalone virtual machine. The following steps are explained in detail with required commands. + * Install policy framework on a Virtual Machine using the integration script. + * Install the Beijing controller. + * Install and Push Beijing policy for vCPE, vFirewall, vDNS & VOLTE use cases. + * Verify the use cases manually. + +.. note:: + * Either use sudo access to run the commands or login through root user. + * These steps have been verified for a VM with Ubuntu OS. + +**Follow the steps below to install policy framework in a virtual machine using the integration script.** + +Docker Installation +------------------- + +**Step 1:** Make the etc/hosts entries + + .. code-block:: bash + + echo $(hostname -I | cut -d\ -f1) $(hostname) | sudo tee -a /etc/hosts + +**Step 2:** Make the DNS entries + + .. code-block:: bash + + echo "nameserver " >> /etc/resolvconf/resolv.conf.d/head + echo "nameserver " >> /etc/resolvconf/resolv.conf.d/head + resolvconf -u + +**Step 3:** Update the ubuntu software installer + + .. code-block:: bash + + apt-get update + +**Step 4:** Check and Install Java + + .. code-block:: bash + + apt-get install -y openjdk-8-jdk + java -version + + Ensure that the Java version that is executing is *OpenJDK version 8* + +**Step 5:** Check and Install GIT + + .. code-block:: bash + + apt-get install git + git -version + +**Step 6:** Check and Install Maven + + .. code-block:: bash + + apt-get install maven + mvn -version + +**Step 7:** Check and Install docker and docker-compose + + .. code-block:: bash + + curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - + add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" + apt-get update + apt-cache policy docker-ce + apt-get install -y docker-ce + systemctl status docker + docker ps + apt install docker-compose + docker-compose + +**Step 8:** Check the MTU size of the eth0 interface on your VM, it is 9126 in the example below + + .. code-block:: bash + + ifconfig + eth0 Link encap:Ethernet HWaddr 02:42:ac:12:00:07 + inet addr:172.18.0.7 Bcast:0.0.0.0 Mask:255.255.0.0 + inet6 addr: fe80::42:acff:fe12:7/64 Scope:Link + UP BROADCAST RUNNING MULTICAST MTU:9126 Metric:1 + RX packets:44955 errors:0 dropped:0 overruns:0 frame:0 + TX packets:75017 errors:0 dropped:0 overruns:0 carrier:0 + collisions:0 txqueuelen:0 + RX bytes:8712526 (8.7 MB) TX bytes:7079733 (7.0 MB) + +**Step 9:** Configure the DNS settings in the Docker daemon configuration file /etc/docker/daemon.json + + * add or edit the first line below for your DNS settings ** and ** + * add or edit the second line below for your MTU size **, taken from the command in step 8 above + + .. code-block:: bash + + add "dns": ["", ""] + add "mtu": + +**Step 10:** Restart the docker service + + .. code-block:: bash + + service docker restart + +**Step 11:** Change the permissions of the Docker Daemon configuration file + + .. code-block:: bash + + chmod 565 /etc/docker/daemon.json + +**Step 12:** Configure the DNS settings in the Docker configuration file */etc/default/docker* + + * add or edit the line below for your DNS settings ** and ** + + .. code-block:: bash + + add DOCKER_OPTS="--dns --dns " + +**Step 13:** Change the permissions of the Docker socket file + + .. code-block:: bash + + chmod 565 /var/run/docker.sock + +**Step 14:** Check the status of the Docker service and ensure it is running correctly + + .. code-block:: bash + + service docker status + docker ps + +Install the ONAP Policy Framework +--------------------------------- + +**Step 1:** Clone the integration git repository + + .. code-block:: bash + + git clone https://gerrit.onap.org/r/integration + +**Step 2:** Change to the policy integration script location + + .. code-block:: bash + + cd integration/test/csit/scripts/policy/ + +**Step 3:** Edit the Policy integration script script1.sh + + .. code-block:: bash + + # - set the MTU value to the same value as read in step 8 above + # - set the value of PRELOAD_POLICIES to true + # - change the name of the docker compose Yaml file to remove the -integration part of the file name from + # "docker-compose -f docker-compose-integration.yml up -d" + # to + # "docker-compose -f docker-compose.yml up -d" + + export MTU= + export PRELOAD_POLICIES=true + docker-compose -f docker-compose.yml up -d + +**Step 4:** Run the integration script for automated installation + + .. code-block:: bash + + ./script1.sh | tee /tmp/log.txt + + Note: It may take up to 60 minutes for the installation to complete. You can view installation logs in /tmp/log.txt + + +**Step 5:** Verify the installation + + .. code-block:: bash + + echo $(hostname -I | cut -d\ -f1) $(hostname) | sudo tee -a /etc/hosts + docker ps + + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 2d04434c5354 onap/policy-drools "/bin/sh -c ./do-sta…" 2 days ago Up 2 days 0.0.0.0:6969->6969/tcp, 0.0.0.0:9696->9696/tcp drools + 52a910a3678b onap/policy-pe "bash ./do-start.sh …" 2 days ago Up 2 days 0.0.0.0:8081->8081/tcp pdp + aa9bb20efe59 onap/policy-pe "bash ./do-start.sh …" 2 days ago Up 2 days brmsgw + 7cdf4919044b onap/policy-pe "bash ./do-start.sh …" 2 days ago Up 2 days 0.0.0.0:8443->8443/tcp, 0.0.0.0:9091->9091/tcp pap + 394854eab2bc sonatype/nexus:2.14.8-01 "/bin/sh -c '${JAVA_…" 2 days ago Up 2 days 0.0.0.0:9081->8081/tcp nexus + fd48c851b6be mariadb:10.0.34 "docker-entrypoint.s…" 2 days ago Up 2 days 0.0.0.0:3306->3306/tcp mariadb + + +Installation of Controllers and Policies +---------------------------------------- + +You may now install a controller and policies on the ONAP Policy Framework. Follow either of the HowTos below to install either the Amsterdam or Beijing controller and policies. + + * `Installation of Amsterdam Controller and vCPE Policy `_ + * `Installation of Beijing Controller and Policies `_ + + +Useful Commands +--------------- + +The following command returns a JSON document containing the configuration information from the PDP. + +.. code-block:: bash + :caption: To return a JSON document containing the configuration information from the PDP + + curl -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'ClientAuth: cHl0aG9uOnRlc3Q=' -H 'Authorization: Basic dGVzdHBkcDphbHBoYTEyMw==' -H 'Environment: TEST' -X POST -d '{"policyName": ".*"}' http://localhost:8081/pdp/api/getConfig | python -m json.tool + + +Run following command to check PDP, PAP and PDP-D Health status + +.. code-block:: bash + :caption: To check PDP, PAP and PDP-D Health status + + http -a 'healthcheck:zb!XztG34' :6969/healthcheck + + HTTP/1.1 200 OK + Content-Length: 276 + Content-Type: application/json + Date: Tue, 17 Apr 2018 10:51:14 GMT + Server: Jetty(9.3.20.v20170531) + { + "details":[ + { + "code":200, + "healthy":true, + "message":"alive", + "name":"PDP-D", + "url":"self" + }, + { + "code":200, + "healthy":true, + "message":"", + "name":"PAP", + "url":"http://pap:9091/pap/test" + }, + { + "code":200, + "healthy":true, + "message":"", + "name":"PDP", + "url":"http://pdp:8081/pdp/test" + } + ], + "healthy":true + } + +Run following command to make sure all topics are created + +.. code-block:: bash + :caption: To check all topics are created + + curl --silent --user @1b3rt:31nst31n -X GET http://localhost:9696/policy/pdp/engine/topics/sources | python -m json.tool + + +.. _Standalone installation in Virtual Machine: https://wiki.onap.org/display/DW/ONAP+Policy+Framework%3A+Standalone+installation+in+Virtual+Machine + + + +End of Document + -- 2.16.6