diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/docs_scaleout.rst | 204 | ||||
| -rw-r--r-- | docs/docs_vcpe_tosca.rst | 136 | ||||
| -rw-r--r-- | docs/docs_vfw.rst | 80 | ||||
| -rw-r--r-- | docs/docs_vlb.rst | 103 | ||||
| -rw-r--r-- | docs/index.rst | 2 | ||||
| -rw-r--r-- | docs/onap-oom-heat.rst | 148 |
6 files changed, 672 insertions, 1 deletions
diff --git a/docs/docs_scaleout.rst b/docs/docs_scaleout.rst new file mode 100644 index 000000000..184bee29d --- /dev/null +++ b/docs/docs_scaleout.rst @@ -0,0 +1,204 @@ +VF Module Scale Out Use Case +---------------------------- + +Source files +~~~~~~~~~~~~ + +- Base VNF template file: https://git.onap.org/demo/plain/heat/vLBMS/base_vlb.yaml +- Base VNF environment file: https://git.onap.org/demo/plain/heat/vLBMS/base_vlb.env + +- VF module scaling template file: https://git.onap.org/demo/plain/heat/vLBMS/dnsscaling.yaml +- VF module scaling environment file: https://git.onap.org/demo/plain/heat/vLBMS/dnsscaling.env + +Description +~~~~~~~~~~~ +The Scale Out use case shows how users/network operators can add Virtual Network Function Components (VNFCs) as part of a VF Module that has been instantiated in the Service model to an existing VNF, in order to increase capacity of the network. ONAP Casablanca release supports scale out with manual trigger from VID and closed-loop enabled automation from Policy. This is demonstrated against the vLB/vDNS VNFs developed for ONAP. For Casablanca, both APPC and SDNC controllers are used to demonstrate accepting request from SO to execute the Scale Out operation. APPC is the main controller used for this use case and it can be used to scale different VNF types. SDNC is experimental for now and it can scale only the vDNS VNF developed for ONAP. + +The Casablanca Scaling Use Case Wiki Page can be found here: https://wiki.onap.org/display/DW/Scaling+Use+Case+Extension + +How to Use +~~~~~~~~~~ +Scaling VF modules manually requires the user/network operator to trigger the scale out operation from the VID portal. VID translates the operation into a call to SO. Scaling VF modules in an automated manner instead requires the user/network operator to design and deploy a closed loop for scale out that includes policies (e.g. threshold-crossing conditions), guard policies that determine when it's safe to scale out, and microservices that analyze events coming from the network in order to discover situations. + +Both manual and automated scale out activate the scale out workflow in the Service Orchestrator (SO). The workflow runs as follows: + +- SO sends a request to APPC to run health check against the VNF; +- If the VNF is healthy, SO instantiates a new VF module and sends a request to APPC to reconfigure the VNF; +- APPC reconfigures the VNF, without interrupting the service; +- SO sends a request to APPC to run health check against the VNF again, to validate that the scale out operation didn't impact the running VNF. + +The vLB has a Northbound API that allows an upstream system (e.g. ONAP) to change the internal configuration by updating the list of active vDNS instances (i.e. VNF reconfiguration). The Northbound API framework has been built using FD.io-based Honeycomb 1707, and supports both RESTconf and NETCONF protocols. Below is an example of vDNS instances contained in the vLB, in JSON format: +:: + + { + "vlb-business-vnf-onap-plugin": { + "vdns-instances": { + "vdns-instance": [ + { + "ip-addr": "192.168.10.211", + "oam-ip-addr": "10.0.150.2", + "enabled": true + } + ] + } + } + } + +The parameters required for VNF reconfiguration (i.e. "ip-addr", "oam-ip-addr", and "enabled" in case of vLB/vDNS) can be specified in the VID GUI when triggering the workflow manually or in CLAMP when designing a closed loop for the automated case. In both cases, the format used for specifying the parameters and their values is a JSON path. SO will use the provided paths to access parameters' name and value in the VF module preload received from SDNC before instantiating a new VF module. + +VID accepts a JSON array in the "Configuration Parameter" box (see later), for example: +:: + +[{"ip-addr":"$.vf-module-topology.vf-module-parameters.param[10].value","oam-ip-addr":"$.vf-module-topology.vf-module-parameters.param[15].value","enabled":"$.vf-module-topology.vf-module-parameters.param[22].value"}] + +CLAMP, instead, accepts a YAML file in the "Payload" box in the Policy Creation form, for example: +:: + + requestParameters: '{"usePreload":true,"userParams":[]}' + configurationParameters: '[{"ip-addr":"$.vf-module-topology.vf-module-parameters.param[10].value","oam-ip-addr":"$.vf-module-topology.vf-module-parameters.param[15].value","enabled":"$.vf-module-topology.vf-module-parameters.param[22].value"}]' + +Note that Policy requires an additional object, called "requestParameters" in which "usePreload" should be set to true and the "userParams" array should be left empty. + +The JSON path to the parameters used for VNF reconfiguration, including array locations, should be set as described above. Finally, although the VNF supports to update multiple vDNS records in the same call, for Casablanca release APPC updates a single vDNS instance at a time. + +When using APPC, before running scale out, the user needs to create a VNF template using the Controller Design Tool (CDT), a design-time tool that allows users to create and on-board VNF templates into the APPC. The template describes which control operation can be executed against the VNF (e.g. scale out, health check, modify configuration, etc.), the protocols that the VNF supports, port numbers, VNF APIs, and credentials for authentication. Being VNF agnostic, APPC uses these templates to "learn" about specific VNFs and the supported operations. +CDT requires two input: + +1) the list of parameters that APPC will receive (ip-addr, oam-ip-addr, enabled in the example above); + +2) the VNF API that APPC will use to reconfigure the VNF. + +Below is an example of the parameters file (yaml format), which we call parameters.yaml: +:: + + version: V1 + vnf-parameter-list: + - name: ip-addr + type: null + description: null + required: "true" + default: null + source: Manual + rule-type: null + request-keys: null + response-keys: null + - name: oam-ip-addr + type: null + description: null + required: "true" + default: null + source: Manual + rule-type: null + request-keys: null + response-keys: null + - name: enabled + type: null + description: null + required: "true" + default: null + source: Manual + rule-type: null + request-keys: null + response-keys: null + +Here is an example of API for the vLB VNF used for this use case. We name the file after the vnf-type contained in SDNC (i.e. Vloadbalancerms..dnsscaling..module-1): +:: + + <vlb-business-vnf-onap-plugin xmlns="urn:opendaylight:params:xml:ns:yang:vlb-business-vnf-onap-plugin"> + <vdns-instances> + <vdns-instance> + <ip-addr>${ip-addr}</ip-addr> + <oam-ip-addr>${oam-ip-addr}</oam-ip-addr> + <enabled>${enabled}</enabled> + </vdns-instance> + </vdns-instances> + </vlb-business-vnf-onap-plugin> + +To create the VNF template in CDT, the following steps are required: + +- Connect to the CDT GUI: http://APPC-IP:8080 (in Heat-based ONAP deployments) or http://ANY-K8S-IP:30289 (in OOM/K8S-based ONAP deployments) +- Click "My VNF" Tab. Create your user ID, if necessary +- Click "Create new VNF" entering the VNF type as reported in VID or AAI, e.g. vLoadBalancerMS/vLoadBalancerMS 0 +- Select "ConfigScaleOut" action +- Create a new template identifier using the vnf-type name in SDNC as template name, e.g. Vloadbalancerms..dnsscaling..module-1 +- Select protocol (Netconf-XML), VNF username (admin), and VNF port number (2831 for NETCONF) +- Click "Parameter Definition" Tab and upload the parameters (.yaml) file +- Click "Template Tab" and upload API template (.yaml) file +- Click "Reference Data" Tab +- Click "Save All to APPC" + +For health check operation, we just need to specify the protocol, the port number and username of the VNF (REST, 8183, and "admin" respectively, in the case of vLB/vDNS) and the API. For the vLB/vDNS, the API is: +:: + + restconf/operational/health-vnf-onap-plugin:health-vnf-onap-plugin-state/health-check + +Note that we don't need to create a VNF template for health check, so the "Template" flag can be set to "N". Again, the user has to click "Save All to APPC" to update the APPC database. +At this time, CDT doesn't allow users to provide VNF password from the GUI. To update the VNF password we need to log into the APPC Maria DB container and change the password manually: +:: + + mysql -u sdnctl -p (type "gamma" when password is prompted) + use sdnctl; + UPDATE DEVICE_AUTHENTICATION SET PASSWORD='admin' WHERE + VNF_TYPE='vLoadBalancerMS/vLoadBalancerMS 0'; (use your VNF type) + +To trigger the scale out workflow manually, the user/network operator can log into VID from the ONAP Portal (demo/demo123456! as username/password), select "VNF Changes" and then the "New (+)" button. The user/network operator needs to fill in the "VNF Change Form" by selecting Subscriber, Service Type, NF Role, Model Version, VNF, Scale Out from the Workflow dropdown window, and insert the JSON path array described above in the "Configuration Parameter" box. After clicking "Next", in the following window the user/network operator has to select the VF Module to scale by clicking on the VNF and then on the appropriate VF Module checkbox. Finally, by clicking on the "Schedule" button, the scale out use case will run as described above. + +Automated scale out requires the user to onboard a DCAE blueprint in SDC when creating the service. To design a closed loop for scale out, the user needs to access the CLAMP GUI (https://clamp.api.simpledemo.onap.org:30258/designer/index.html) and execute the following operations: + +- Click the "Closed loop" dropdown window and select "Open CL" +- Select the closed loop model and click "OK" +- In the next screen, click the "Policy" box to create a policy for closed loop, including guard policies +- After creating the policies, click "TCA" and review the blueprint uploaded during service creation and distributed by SDC to CLAMP +- Click the "Manage" dropdown and then "Submit" to push the policies to the Policy Engine +- From the same "Manage" dropdown, click "Deploy" to deploy the TCA blueprint to DCAE + +The vLB/vDNS VNF generates traffic and reports metrics to the VES collector in the DCAE platform. The number of incoming packets to the vLB is used to evaluate the policy defined for closed loop. If the provided threshold is crossed, DCAE generates an event that reaches the Policy Engine, which in turn activates the scale out closed loop described above. + +For more information about scale out, videos, and material used for running the use case, please look at the wiki page: https://wiki.onap.org/display/DW/Running+Scale+Out+Use+Case+for+Casablanca + +Test Status and Plans +~~~~~~~~~~~~~~~~~~~~~ +Casablanca Scale Out completed all tests as found here: https://wiki.onap.org/pages/viewpage.action?pageId=36964241#UseCaseTracking(CasablancaScaling)-Testing + +Known Issues and Resolutions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +1) When running closed loop-enabled scale out, the closed loop designed in CLAMP conflicts with the default closed loop defined for the old vLB/vDNS use case + +Resolution: Change TCA configuration for the old vLB/vDNS use case + +- Connect to Consul: http://<ANY K8S VM IP ADDRESS>:30270 and click on "Key/Value" → "dcae-tca-analytics" +- Change "eventName" in the vLB default policy to something different, for example "vLB" instead of the default value "vLoadBalancer" +- Change "subscriberConsumerGroup" in the TCA configuration to something different, for example "OpenDCAE-c13" instead of the default value "OpenDCAE-c12" +- Click "UPDATE" to upload the new TCA configuration + +2) When running closed loop-enabled scale out, the permitAll guard policy conflicts with the scale out guard policy + +Resolution: Undeploy the permitAll guard policy + +- Connect to the Policy GUI, either through the ONAP Portal (https://portal.api.simpledemo.onap.org:30225/ONAPPORTAL/login.htm) or directly (https://policy.api.simpledemo.onap.org:30219/onap/login.htm) +- If using the ONAP Portal, use demo/demo123456! as credentials, otherwise, if accessing Policy GUI directly, use demo/demo +- Click "Policy" → "Push" on the left panel +- Click the pencil symbol next to "default" in the PDP Groups table +- Select "Decision_AllPermitGuard" +- Click "Remove" + +3) When using SDNC, the JSON template for DMaaP messages has a wrong "input" field + +Resolution: Replace the "input" field in the JSON template with "output" + +- Connect to the SDNC container from the Rancher VM in the Kubernetes cluster, for example + +:: + + kubectl exec -it -n onap dev-sdnc-sdnc-0 bash + +- Install your favorite text editor, for example + +:: + + apt-get update; apt-get install vim -y + +- Open /opt/onap/sdnc/restapi/templates/lcm-dmaap-publish-template.json and replace "input" with "output" in the JSON object body +- Save the changes +- If SDNC is deployed in cluster mode (3 SDNC replicas, dev-sdnc-sdnc-0, dev-sdnc-sdnc-1, dev-sdnc-sdnc-2), apply the same change to all the replicas in the cluster. + diff --git a/docs/docs_vcpe_tosca.rst b/docs/docs_vcpe_tosca.rst new file mode 100644 index 000000000..faa4e7590 --- /dev/null +++ b/docs/docs_vcpe_tosca.rst @@ -0,0 +1,136 @@ +vCPE of Tosca Use Case +---------------------- + +Source files +~~~~~~~~~~~ + +vCPE tosca file url: https://git.onap.org/demo/tree/tosca/vCPE + +5 VNFs are here for the ONAP vCPE use case. This VNFD is transformed manually from vCPE heat template. +Please run "./generate_csar.sh" to create the CSAR package files for these 5 VNFS. CSAR package file is just a zip formatted file. If you want to use SRIOV SRIOV-NIC", please run "./generate_csar.sh sriov" to create the CSAR package files for SRIOV. + + +Description +~~~~~~~~~~ + +The use case is composed of five virtual functions (VFs): Infrastructure including vDNS, vDHCP, vAAA(Authorization, Authentication, Accounting) and +vWEB, vBNG(Virtual Broadband Network Gateway), vGMUX(Virtual Gateway Multiplexer), vBRGEMU(Bridged Residential Gateway) and vGW(Virtual Gateway). +Infrastructure VF run in one VM. the other VFs run in separate four VMs. We will send much data from vBRGEMU to vGW. we need to accelarate it using SRIOV-NIC. + + +Test Plan: +~~~~~~~~~~~~~~~~~~ + +The test plan 3 in https://wiki.onap.org/pages/viewpage.action?pageId=41421112. +Test Plan 3: VF-C HPA testing +This test plan covers the tests related to testing +Support for the vCPE use case in VF-C + +Use vCPE (Infra, vGW, vBNG, vBRGEMU and vGMUX) + +Infra part of policy asking for: +:: + + 2 vcpus + >= 2Gbytes of memory + > 40Gbytes of disk + +vGW part of policy asking for: +:: + + 2 vcpus + >=4Gbytes of memory + >= 40Gbytes of disk + Numa page size: 2Mbytes and pages 1024 + with one SRIOV-NIC + +vBNG part of policy asking for: +:: + + 2 vcpus + >= 2Gbytes of memory + > 40Gbytes of disk + Numa page size: 2Mbytes and pages 1024 + with one SRIOV-NIC + +vBGREMU part of policy asking for: +:: + + 2 vcpus + >= 2Gbytes of memory + >= 40Gbytes of disk + Numa page size: 2Mbytes and pages 1024 + with one SRIOV-NIC + +vGMUX part of policy asking for: +:: + + 2 vcpus + >= 2Gbytes of memory + > 40Gbytes of disk + Numa page size: 2Mbytes and pages 1024 + with one SRIOV-NIC + +Instantiate the VNF +Check for results: +It would have selected flavor13 for vGW, vBNG, vBRGEMU and vGMUX VMs. It would have selected flavor13 and flavor12 for Infrastructure. + +Test Steps: +~~~~~~~~~~ + +VIM Configuration: +^^^^^^^^^^^^^^^^^^ + +If you want to use SRIOV-NIC, you need first config SRIOV NIC to refer to [1]. +[1] https://docs.openstack.org/ocata/networking-guide/config-sriov.html + +ONAP managing 1 cloud-region which have three flavors. +Flavor 11: +2 vcpus, 1 Gbytes of memory, 20Gb disk +Numa page size: 2Mbytes and number pages 512 +:: + + openstack flavor create onap.hpa.flavor11 -id auto --ram 1024 --disk 20 --vcpus 2 + +Flavor 12: +2 vcpus, 2 Gbytes of memory, 20Gb disk +Numa page size: 2Mbytes and number pages 1024 +:: + + openstack flavor create onap.hpa.flavor12 -id auto --ram 2048 --disk 20 --vcpus 2 + +Flavor 13: +2 vcpus, 4 Gbytes of memory, 20Gb disk +Huge page size: 2Mbytes and number pages 2048 +1 SRIOV-NIC VF +:: + + openstack flavor create onap.hpa.flavor13 -id auto --ram 4096 --disk 20 -vcpus 2 + openstack flavor set onap.hpa.flavor11 --property aggregate_instance_extra_specs:sriov_nic=sriov-nic-intel-1234-5678-physnet1:1 + openstack aggregate create --property sriov_nic=sriov-nic-intel-1234-5678-physnet1:1 hpa_aggr11 + +comments: you must change 1234 and 5678 to real vendor id and product id. you also need change physnet1 to the provider network. + +Policy Configuration: +^^^^^^^^^^^^^^^^^^^^^ + +After the patch https://gerrit.onap.org/r/#/c/73502/ is merged. With the generated policy and do some manually update as follows, the service could be distributed successfully and the Policy/VFC/OOF could work as excepted. + +- Need manually modify policy item because the “vendor id” and “PCI device id” and “architecture” must be changed in different VIMs since we have different PCI devices in different VIMs +- The value of mandatory in CSAR is “true”, OOF is case intensive, it needs to use “True”. Have to update it. suggest OOF to use ignoreCase in R4. +- The attribute key in CSAR is pciNumDevices, but the responding one in OOF/Mutlicloud is pciCount. Suggest keeping alignment in R4. +- The policy scope has to add a value “us” into it which is a configuration issue in OOF side. Policy side also need do improvement to deal with policy scope automatically append instead of replacement so such policy could be used by several services at the same time. + + +Running the Use Case +~~~~~~~~~~~~~~~~~~~ + +We design vCPE in SDC and distribute it to VFC and Policy and UUI. We can click onboarding VNF and onboarding NS. we can instance it. + +Known issues and resolution +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Some SDC NS data model is not aligned to VFC NS data model, VFC NS also according to ETSI SOL0001. we also can refer to https://jira.onap.org/browse/SDC-1897. we have a workaround for this issue, we put the service as artifact file and distribute to VFC. +- NFV Tosca parser bug https://jira.opnfv.org/browse/PARSER-187. we also filed a bug in VFC https://jira.onap.org/browse/VFC-1196. +- 'artifacts' definition is missing in the exported csar's VDU node, we also can refer to https://jira.onap.org/browse/SDC-1900. It’s a very hacky workaround in VFC’s GVFNM. Because currently the only use case will use GVFNM is vCPE, which only uses the ubuntu16.04 image, so GVFNM just makes the ubuntu16.04 image as the default if the "sw_image" artifact is missing in the SDC’s exported CSAR. +- OOF patch https://gerrit.onap.org/r/#/c/73332/ is not accepted by 1.2.4 image.It will be accepted by 1.2.5 image. but 1.2.5 image is not release. If you want to use it, you can use 1.2.5-SNAPSHOT-latest. If you use 1.2.4 image, you also need to modify code according to the patch. diff --git a/docs/docs_vfw.rst b/docs/docs_vfw.rst new file mode 100644 index 000000000..af47c464b --- /dev/null +++ b/docs/docs_vfw.rst @@ -0,0 +1,80 @@ +vFirewall Use Case +------------------ + +Source files +~~~~~~~~~~~~ + +- vFirewall/vSink template file: https://git.onap.org/demo/plain/heat/vFWCL/vFWSNK/base_vfw.yaml +- vFirewall/vSink environment file: https://git.onap.org/demo/plain/heat/vFWCL/vFWSNK/base_vfw.env + +- vPacketGenerator template file: https://git.onap.org/demo/plain/heat/vFWCL/vPKG/base_vpkg.yaml +- vPacketGenerator environment file: https://git.onap.org/demo/plain/heat/vFWCL/vPKG/base_vpkg.env + + +Description +~~~~~~~~~~~ + +The use case is composed of three virtual functions (VFs): packet generator, firewall, and traffic sink. +These VFs run in three separate VMs. The packet generator sends packets to the packet sink through the firewall. +The firewall reports the volume of traffic passing though to the ONAP DCAE collector. To check the traffic volume +that lands at the sink VM, you can access the link http://sink_ip_address:667 through your browser and enable +automatic page refresh by clicking the "Off" button. You can see the traffic volume in the charts. + +The packet generator includes a script that periodically generates different volumes of traffic. The closed-loop +policy has been configured to re-adjust the traffic volume when high-water or low-water marks are crossed. + + +Closed-Loop for vFirewall Use Case +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Through the ONAP Portal's Policy Portal, we can find the configuration and operation policies that are currently +enabled for the vFirewall use case: + +- The configuration policy sets the thresholds for generating an onset event from DCAE to the Policy engine. Currently, the high-water mark is set to 700 packets while the low-water mark is set to 300 packets. The measurement interval is set to 10 seconds. +- When a threshold is crossed (i.e. the number of received packets is below 300 packets or above 700 packets per 10 seconds), the Policy engine executes the operational policy to request APPC to adjust the traffic volume to 500 packets per 10 seconds. +- APPC sends a request to the packet generator to adjust the traffic volume. +- Changes to the traffic volume can be observed through the link http://sink_ip_address:667. + + +Adjust packet generator +~~~~~~~~~~~~~~~~~~~~~~~ + +The packet generator contains 10 streams: fw_udp1, fw_udp2, fw_udp3, ..., fw_udp10. Each stream generates 100 packets +per 10 seconds. A script in /opt/run_traffic_fw_demo.sh on the packet generator VM starts automatically and alternates high +traffic (i.e. 10 active streams at the same time) and low traffic (1 active stream) every 5 minutes. + +To enable a stream, include + +:: + + {"id":"fw_udp1", "is-enabled":"true"} in the pg-stream bracket + +To adjust the traffic volume produced by the packet generator, run the following command in a shell, replacing PacketGen_IP in +the HTTP argument with localhost (if you run it in the packet generator VM) or the packet generator IP address: + +:: + + curl -X PUT -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"pg-streams":{"pg-stream": [{"id":"fw_udp1", "is-enabled":"true"},{"id":"fw_udp2", "is-enabled":"true"},{"id":"fw_udp3", "is-enabled":"true"},{"id":"fw_udp4", "is-enabled":"true"},{"id":"fw_udp5", "is-enabled":"true"}]}}' "http://PacketGen_IP:8183/restconf/config/sample-plugin:sample-plugin/pg-streams" + +The command above enables 5 streams. + + +Running the Use Case +~~~~~~~~~~~~~~~~~~~~ +Users can run the use case using the automated Robot Framework or manually. For using the Robot Framework in an ONAP instance installed with OOM, users have to connect to the Rancher VM and run the following command: + +:: + + bash oom/kubernetes/robot/demo-k8s.sh <namespace> vfwclosedloop <pgn-ip-address> + +The script sets the packet generator to high and low rates, and checks whether the policy kicks in to modulate the rates back to medium. + +For documentation about running the use case manually for previous releases, please look at the videos and the material available at this `wiki page`__. + +__ https://wiki.onap.org/display/DW/Running+the+ONAP+Demos + +Although videos are still valid, users are encouraged to use the Heat templates linked at the top of this page rather than the old Heat templates in that wiki page. + +Known issues and resolution +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The packet generator may become unresponsive to external inputs like changing the number of active streams. To solve the problem, reboot the packet generator VM.
\ No newline at end of file diff --git a/docs/docs_vlb.rst b/docs/docs_vlb.rst new file mode 100644 index 000000000..07671cd75 --- /dev/null +++ b/docs/docs_vlb.rst @@ -0,0 +1,103 @@ +vLoadBalancer Use Case +---------------------- + +Source files +~~~~~~~~~~~~ + +- Base VNF template file: https://git.onap.org/demo/plain/heat/vLB/base_vlb.yaml +- Base VNF environment file: https://git.onap.org/demo/plain/heat/vLB/base_vlb.env + +- VF module scaling template file: https://git.onap.org/demo/plain/heat/vLB/dnsscaling.yaml +- VF module scaling environment file: https://git.onap.org/demo/plain/heat/vLB/dnsscaling.env + + +Description +~~~~~~~~~~~ +The use case is composed of three VFs: packet generator, load balancer, and DNS server. These VFs run in three separate VMs. The packet generator issues DNS lookup queries that reach the DNS server via the load balancer. DNS replies reach the packet generator via the load balancer as well. The load balancer reports the average amount of traffic per DNS over a time interval to the DCAE collector. When the average amount of traffic per DNS server crosses a predefined threshold, the closed-loop is triggered and a new DNS server is instantiated. + +To test the application, make sure that the security group in OpenStack has ingress/egress entries for protocol 47 (GRE). The user can run a DNS query from the packet generator VM: + +:: + + dig @vLoadBalancer_IP host1.dnsdemo.onap.org + +The output below means that the load balancer has been set up correctly, has forwarded the DNS queries to one DNS instance, and the packet generator has received the DNS reply message. + +:: + + ; <<>> DiG 9.10.3-P4-Ubuntu <<>> @192.168.9.111 host1.dnsdemo.onap.org + ; (1 server found) + ;; global options: +cmd + ;; Got answer: + ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 31892 + ;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 1, ADDITIONAL: 2 + ;; WARNING: recursion requested but not available + + ;; OPT PSEUDOSECTION: + ; EDNS: version: 0, flags:; udp: 4096 + ;; QUESTION SECTION: + ;host1.dnsdemo.onap.org. IN A + + ;; ANSWER SECTION: + host1.dnsdemo.onap.org. 604800 IN A 10.0.100.101 + + ;; AUTHORITY SECTION: + dnsdemo.onap.org. 604800 IN NS dnsdemo.onap.org. + + ;; ADDITIONAL SECTION: + dnsdemo.onap.org. 604800 IN A 10.0.100.100 + + ;; Query time: 0 msec + ;; SERVER: 192.168.9.111#53(192.168.9.111) + ;; WHEN: Fri Nov 10 17:39:12 UTC 2017 + ;; MSG SIZE rcvd: 97 + + +Closedloop for vLoadBalancer/vDNS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Through the Policy Portal (accessible via the ONAP Portal), we can find the configuration and operation policies that are enabled by default for the vLoadBalancer/vDNS application: + +- The configuration policy sets the thresholds for generating an onset event from DCAE to the Policy engine. Currently, the threshold is set to 200 packets, while the measurement interval is set to 10 seconds; +- Once the threshold is crossed (e.g. the number of received packets is above 200 packets per 10 seconds), the Policy Engine executes the operational policy. The Policy engine queries A&AI to fetch the VNF UUID and sends a request to the Service Orchestrator (SO) to spin up a new DNS instance for the VNF identified by that UUID; +- SO spins up a new DNS instance. + + +To change the volume of queries generated by the packet generator, run the following command in a shell, replacing PacketGen_IP in the HTTP argument with localhost (if you run it in the packet generator VM) or the packet generator IP address: + +:: + + + curl -X PUT -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"pg-streams":{"pg-stream": [{"id":"dns1", "is-enabled":"true"}]}}' "http://PacketGen_IP:8183/restconf/config/sample-plugin:sample-plugin/pg-streams" + +- {"id":"dns1", "is-enabled":"true"} shows the stream "dns1" is enabled. The packet generator sends requests in the rate of 100 packets per 10 seconds; +- To increase the amount of traffic, you can enable more streams. The packet generator has 10 streams, "dns1", "dns2", "dns3" to "dns10". Each of them generates 100 packets per 10 seconds. To enable the streams, please add {"id":"dnsX", "is-enabled":"true"} to the pg-stream bracket of the curl command, where X is the stream ID. + +For example, if you want to enable 3 streams, the curl command will be: + +:: + + curl -X PUT -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"pg-streams":{"pg-stream": [{"id":"dns1", "is-enabled":"true"}, {"id":"dns2", "is-enabled":"true"},{"id":"dns3", "is-enabled":"true"}]}}' "http://PacketGen_IP:8183/restconf/config/sample-plugin:sample-plugin/pg-streams" + +When the VNF starts, the packet generator is automatically configured to run 5 streams. + + +Running the Use Case +~~~~~~~~~~~~~~~~~~~~ +Automated closed loop via Robot Framework is not supported at this time. For documentation about running the use case manually for previous releases, please look at the videos and the material available at this `wiki page`__. + +__ https://wiki.onap.org/display/DW/Running+the+ONAP+Demos + +Although videos are still valid, users are encouraged to use the Heat templates linked at the top of this page rather than the old Heat templates in that wiki page. + +Known issues and resolution +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +1) The packet generator may become unresponsive and stop generating traffic. To solve the problem, reboot the packet generator. + +2) The base and scaling VF module names need to follow a specific naming convention: + + a) The base VF module name must be "Vfmodule\_xyz" + + b) The SDNC preload for the scaling VF module must set the VF module name to "vDNS\_xyz", where "xyz" is the same as the base module. This is required because during closed loop Policy looks for "Vfmodule\_" and replaces it with "vDNS\_" + +3) Only one scaling operation is supported.
\ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index f018fc6ce..05befb182 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,4 +8,4 @@ The Integration project provides the followning artifacts: - Test suites to check the various ONAP components based on Robot Framework - Artifacts for the use-case deployments -.. include:: heat.rst +.. include:: onap-oom-heat.rst diff --git a/docs/onap-oom-heat.rst b/docs/onap-oom-heat.rst new file mode 100644 index 000000000..cc9ceb7ba --- /dev/null +++ b/docs/onap-oom-heat.rst @@ -0,0 +1,148 @@ +.. _onap-oom-heat: + +ONAP OOM HEAT Template +---------------------- + + +Source files +~~~~~~~~~~~~ + +- HEAT template files: https://git.onap.org/integration/tree/deployment/heat/onap-oom?h=casablanca +- Sample OpenStack RC file: https://git.onap.org/integration/tree/deployment/heat/onap-oom/env/windriver/Integration-SB-00-openrc?h=casablanca +- Sample environment file: https://git.onap.org/integration/tree/deployment/heat/onap-oom/env/windriver/onap-oom.env?h=casablanca +- Deployment script: https://git.onap.org/integration/tree/deployment/heat/onap-oom/scripts/deploy.sh?h=casablanca + + +Description +~~~~~~~~~~~ + +The ONAP Integration Project provides a sample HEAT template that +fully automates the deployment of ONAP using OOM as described in +:ref:`ONAP Operations Manager (OOM) over Kubernetes<installing-onap>`. + +The ONAP OOM HEAT template deploys the entire ONAP platform. It spins +up an HA-enabled Kubernetes cluster, and deploys ONAP using OOM onto +this cluster. +- 1 Rancher VM that also serves as a shared NFS server +- 3 etcd VMs for the Kubernetes HA etcd plane +- 2 orch VMs for the Kubernetes HA orchestration plane +- 12 k8s VMs for the Kubernetes HA compute hosts + + +Quick Start +~~~~~~~~~~~ + +Using the Wind River lab configuration as an example, here is what +you need to do to deploy ONAP: + +:: + + git clone https://git.onap.org/integration + cd integration/deployment/heat/onap-oom/ + source ./env/windriver/Integration-SB-00-openrc + ./scripts/deploy.sh ./env/windriver/onap-oom.env + + +Environment and RC files +~~~~~~~~~~~~~~~~~~~~~~~~ + +Before deploying ONAP to your own environment, it is necessary to +customize the environment and RC files. You should make a copy of the +sample RC and environment files shown above and customize the values +for your specific OpenStack environments. + +The environment file contains a block called +integration_override_yaml. The content of this block will be created +as the file integration_override.yaml in the deployed Rancher VM, and +used as the helm override files during the OOM deployment. Be sure to +customize the necessary values within this block to match your +OpenStack environment as well. + +**Notes on select parameters** + +:: + + apt_proxy: 10.12.5.2:8000 + docker_proxy: 10.12.5.2:5000 + + rancher_vm_flavor: m1.large + k8s_vm_flavor: m1.xlarge + etcd_vm_flavor: m1.medium + orch_vm_flavor: m1.medium + + key_name: onap_key + + helm_deploy_delay: 2.5m + +It is recommended that you set up an apt proxy and a docker proxy +local to your lab. If you do not wish to use such proxies, you can +set the apt_proxy and docker_proxy parameters to the empty string "". + +rancher_vm_flavor needs to have 8 GB of RAM. +k8s_vm_flavor needs to have 16 GB of RAM. +etcd_vm_flavor needs to have 4 GB of RAM. +orch_vm_flavor needs to have 4 GB of RAM. + +By default the template assumes that you have already imported a +keypair named "onap_key" into your OpenStack environment. If the +desired keypair has a different name, change the key_name parameter. + +The helm_deploy_delay parameter introduces a delay in-between the +deployments of each ONAP helm subchart to help alleviate system load or +contention issues caused by trying to spin up too many pods +simultaneously. The value of this parameter is passed to the Linux +"sleep" command. Adjust this parameter based on the performance and +load characteristics of your OpenStack environment. + + +Exploring the Rancher VM +~~~~~~~~~~~~~~~~~~~~~~~~ + +The Rancher VM that is spun up by this HEAT template serves the +following key roles: +- Installaion of the Rancher server +- Hosts the /dockerdata-nfs/ NFS export shared by all the k8s VMs for persistent volumes +- git clones the oom repo into /root/oom +- git clones the integration repo into /root/integration +- Creates the helm override file at /root/integration-override.yaml +- Deploys ONAP using helm and OOM + + + +.. _deploy-updated-manifest: + +Deploying an Updated Docker Manifest +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some late changes in the ONAP docker images did not make it in time +for the Casablanca release. Depending on the Use Case you are trying +deploy, you may need to update the docker image manifest with certain +newer docker image versions than what was shipped with ONAP Casablanca +release. + +The ONAP integration repo contains a script that will apply the docker +versions specified in a given manifest into the OOM helm chart +definitions. + +To apply an updated manifest (on the Rancher VM): + +:: + + cd /root/integration/version-manifest/src/main/resources + cp docker-manifest.csv docker-manifest-custom.csv + + # customize docker-manifest-custom.csv per your requirements + + ../scripts/update-oom-image-versions.sh ./docker-manifest-custom.csv /root/oom/ + + cd /root/oom/kubernetes/ + git diff # verify that the desired docker image changes are applied successfully + make all # recompile the helm charts + +After that you can update or redeploy ONAP OOM as described here: + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + ../../../../submodules/oom.git/docs/oom_quickstart_guide.rst |