README.md

   1 Content
   2 ---
   3
   4 The Demo repository contains the HEAT templates and scripts for the instantiation of the ONAP platform and use cases. The repository includes:
   5
   6  - README.md: this file.
   7
   8  - LICENSE.TXT: the license text.
   9
  10  - pom.xml: POM file used to build the software hosted in this repository.
  11
  12  - version.properties: current version number of the Demo repository. Format: MAJOR.MINOR.PATCH (e.g. 1.3.0)
  13
  14  - The "boot" and "heat/ONAP/cloud-config" directories contain the scripts that install and configure ONAP. This separation is due to size limits imposed by importing files into a VM for cloud-init. The two directories contain:
  15     - install.sh: sets up the host VM for specific components. This script runs only once, soon after the VM is created.
  16     - vm\_init.sh: contains component-specific configuration, downloads and runs docker containers. For some components, this script may either call a component-specific script (cloned from Gerrit repository) or call docker-compose.
  17     - serv.sh: it is installed in /etc/init.d, calls vm\_init.sh at each VM (re)boot.
  18     - configuration files for the Bind DNS Server installed with ONAP. Currently, both simpledemo.openecomp.org and simpledemo.onap.org domains are supported.
  19     - sdc\_ext\_volume_partitions.txt: file that contains external volume partitions for SDC.
  20
  21  - The "boot" directory also contains a "robot" sub-directory that includes scripts to run Robot from the VM.
  22
  23  - The "docker\_update\_scripts" directory contains scripts that update all the docker containers of an ONAP instance (NOT UPDATED SINCE AMSTERDAM RELEASE).
  24
  25  - The "heat" directory contains the following sub-directories:
  26
  27     - OAM-Network: contains the Heat files for creating the ONAP private management network. This is required only if that network is needed out of the Heat stack.
  28
  29         - ONAP: contains the HEAT files for the installation of the ONAP platform.
  30
  31         - vCPE: contains sub-directories with HEAT templates for the installation of vCPE Infrastructure (Radius Server, DHCP, DNS, Web Server), vBNG, vBRG Emulator, vGMUX, and vGW.
  32
  33         - vFW: contains the HEAT template for the instantiation of the vFirewall VNF (base\_vfw.yaml) and the environment file (base\_vfw.env). This template is used for testing and demonstrating VNF instantiation only (no closed-loop).
  34
  35         - vFWCL: contains two sub-directories, one that hosts the HEAT template for the vFirewall and vSink (vFWSNK/base\_vfw.yaml), and one that hosts the HEAT template for the vPacketGenerator (vPKG/base\_vpkg.yaml). These templates are used for testing and demonstrating VNF instantiation and closed-loop.
  36
  37         - vLB: contains the HEAT template for the instantiation of the vPacketGenerator/vLoadBalancer/vDNS VNF (base\_vlb.yaml) and the environment file (base\_vlb.env). The directory also contains the HEAT template for the DNS scaling-up scenario (dnsscaling.yaml) with its environment file (dnsscaling.env).
  38
  39         - vVG: contains the HEAT template for the instantiation of a volume group (base\_vvg.yaml and base\_vvg.env).
  40
  41  - The "scripts" directory contains the deploy.sh script that uploads software artifacts to the Nexus repository during the build process.
  42
  43  - The "tosca" directory contains an example of the TOSCA model of the vCPE infrastructure.
  44
  45  - The "tutorials" directory contains tutorials for Clearwater\_IMS and for creating a Netconf mount point in APPC. The "VoLTE" sub-directory is currently not used.
  46
  47  - The "vagrant" directory contains the scripts that install ONAP using Vagrant (NOT UPDATED SINCE AMSTERDAM RELEASE).
  48
  49  - The "vnfs" directory: contains the following directories:
  50
  51         - honeycomb_plugin: Honeycomb plugin that allows ONAP to change VNF configuration via RESTCONF or NETCONF protocols.
  52
  53         - vCPE: contains sub-directories with the scripts that install all the components of the vCPE use case.
  54
  55         - VES: source code of the ONAP Vendor Event Listener (VES) Library. The VES library used here has been cloned from the GitHub repository at https://github.com/att/evel-library on February 1, 2017. (DEPRECATED SINCE AMSTERDAM RELEASE)
  56
  57         - VESreporting_vFW: VES client for vFirewall demo application. (DEPRECATED SINCE AMSTERDAM RELEASE)
  58
  59         - VESreporting_vLB: VES client for vLoadBalancer/vDNS demo application. (DEPRECATED SINCE AMSTERDAM RELEASE)
  60
  61         - VES5.0: source code of the ONAP Vendor Event Listener (VES) Library, version 5.0. (CURRENTLY SUPPORTED)
  62
  63         - VESreporting_vFW5.0: VES v5.0 client for vFirewall demo application. (CURRENTLY SUPPORTED)
  64
  65         - VESreporting_vLB5.0: VES v5.0 client for vLoadBalancer/vDNS demo application. (CURRENTLY SUPPORTED)
  66
  67         - vFW: scripts that download, install and run packages for the vFirewall use case.
  68
  69         - vLB: scripts that download, install and run packages for the vLoadBalancer/vDNS use case.
  70
  71         - vLBMS: scripts that download, install and run packages for the vLoadBalancer/vDNS used for the Scale Out use case.
  72
  73
  74 ONAP Installation in OpenStack Clouds via HEAT Template
  75 ---
  76
  77 The ONAP HEAT template spins up the entire ONAP platform in OpenStack-based clouds. The template, onap\_openstack.yaml, comes with an environment file, onap\_openstack.env, in which all the default values are defined.
  78
  79 The HEAT template is composed of two sections: (i) parameters, and (ii) resources.
  80
  81  - The "parameters" section contains the declarations and descriptions of the parameters that will be used to spin up ONAP, such as public network identifier, URLs of code and artifacts repositories, etc. The default values of these parameters can be found in the environment file.
  82
  83  - The "resources" section contains the definitions of:
  84    - ONAP Private Management Network, which is used by ONAP components to communicate with each other and with VNFs
  85    - ONAP Virtual Machines (VMs)
  86    - Public/private key pair used to access ONAP VMs
  87    - Virtual interfaces towards the ONAP Private Management Network
  88    - Disk volumes.
  89
  90 Each VM specification includes Operating System image name, VM size (i.e. flavor), VM name, etc. Each VM has a virtual network interface with a private IP address in the ONAP Private Management network and a floating IP that OpenStack assigns based on availability.
  91 Furthermore, each VM runs an install.sh script that downloads and installs software dependencies (e.g. Java JDK, gcc, make, Python, ...). install.sh finally calls vm_init.sh that downloads docker containers from remote repositories and runs them.
  92
  93 When the HEAT template is executed, the OpenStack HEAT engine creates the resources defined in the HEAT template, based on the parameter values defined in the environment file.
  94
  95 Before running HEAT, it is necessary to customize the environment file. Indeed, some parameters, namely public\_net\_id, pub\_key, openstack\_tenant\_id, openstack\_username, and openstack\_api\_key, need to be set depending on the user's environment:
  96
  97         public_net_id:       PUT YOUR NETWORK ID/NAME HERE
  98         pub_key:             PUT YOUR PUBLIC KEY HERE
  99         openstack_tenant_id: PUT YOUR OPENSTACK PROJECT ID HERE
 100         openstack_username:  PUT YOUR OPENSTACK USERNAME HERE
 101         openstack_api_key:   PUT YOUR OPENSTACK PASSWORD HERE
 102         horizon_url:         PUT THE HORIZON URL HERE
 103         keystone_url:        PUT THE KEYSTONE URL HERE (do not include version number)
 104
 105
 106 openstack\_region parameter is set to RegionOne (OpenStack default). If your OpenStack is using another Region, please modify this parameter.
 107
 108 public\_net\_id is the unique identifier (UUID) or name of the public network of the cloud provider. To get the public\_net\_id, use the following OpenStack CLI command (ext is the name of the external network, change it with the name of the external network of your installation)
 109
 110         openstack network list | grep ext | awk '{print $2}'
 111
 112 pub\_key is the string value of the public key that will be installed in each ONAP VM. To create a public/private key pair in Linux, please execute the following instruction:
 113
 114         user@ubuntu:~$ ssh-keygen -t rsa
 115
 116 The following operations to create the public/private key pair occur:
 117
 118         Generating public/private rsa key pair.
 119         Enter file in which to save the key (/home/user/.ssh/id_rsa):
 120         Created directory '/home/user/.ssh'.
 121         Enter passphrase (empty for no passphrase):
 122         Enter same passphrase again:
 123         Your identification has been saved in /home/user/.ssh/id_rsa.
 124         Your public key has been saved in /home/user/.ssh/id_rsa.pub.
 125
 126 openstack\_username, openstack\_tenant\_id (password), and openstack\_api\_key are the user's credentials to access the OpenStack-based cloud.
 127
 128 Some global parameters used for all components are also required:
 129
 130         ubuntu_1404_image: PUT THE UBUNTU 14.04 IMAGE NAME HERE
 131         ubuntu_1604_image: PUT THE UBUNTU 16.04 IMAGE NAME HERE
 132         flavor_small: PUT THE SMALL FLAVOR NAME HERE
 133         flavor_medium: PUT THE MEDIUM FLAVOR NAME HERE
 134         flavor_large: PUT THE LARGE FLAVOR NAME HERE
 135         flavor_xlarge: PUT THE XLARGE FLAVOR NAME HERE
 136
 137 To get the images in your OpenStack environment, use the following OpenStack CLI command:
 138
 139         openstack image list | grep 'ubuntu'
 140
 141 To get the flavor names used in your OpenStack environment, use the following OpenStack CLI command:
 142
 143         openstack flavor list
 144
 145 Some network parameters must be configured:
 146
 147         dns_list: PUT THE ADDRESS OF THE EXTERNAL DNS HERE (e.g. a comma-separated list of IP addresses in your /etc/resolv.conf in UNIX-based Operating Systems).
 148         external_dns: PUT THE FIRST ADDRESS OF THE EXTERNAL DNS LIST HERE (THIS WILL BE DEPRECATED SOON)
 149         dns_forwarder: PUT THE IP OF DNS FORWARDER FOR ONAP DEPLOYMENT'S OWN DNS SERVER
 150         oam_network_cidr: 10.0.0.0/16
 151
 152 ONAP installs a DNS server used to resolve IP addresses in the ONAP OAM private network. Originally, dns\_list and external\_dns were both used to circumvent some limitations of older OpenStack versions.
 153
 154 DCAE requires a parameter called dcae\_deployment\_profile. It accepts one of the following values:
 155  - R3MVP: Installs only the basic DCAE functionalities that will support the vFW/vDNS, vCPE and vVoLTE use cases;
 156  - R3: Full DCAE installation;
 157  - R3PLUS: This profile deploys the DCAE R3 stretch goal service components.
 158
 159 The recommended DCAE profile for Casablanca Release is R3. For more information about DCAE deployment with HEAT, please refer to the ONAP documentation: https://onap.readthedocs.io/en/latest/submodules/dcaegen2.git/docs/sections/installation_heat.html
 160
 161 The ONAP platform can be instantiated via Horizon (OpenStack dashboard) or Command Line.
 162
 163 Instantiation via Horizon:
 164
 165  - Login to Horizon URL with your personal credentials
 166  - Click "Stacks" from the "Orchestration" menu
 167  - Click "Launch Stack"
 168  - Paste or manually upload the HEAT template file (onap\_openstack.yaml) in the "Template Source" form
 169  - Paste or manually upload the HEAT environment file (onap\_openstack.env) in the "Environment Source" form
 170  - Click "Next"
 171  - Specify a name in the "Stack Name" form
 172  - Provide the password in the "Password" form
 173  - Click "Launch"
 174
 175 Instantiation via Command Line:
 176
 177  - Install the HEAT client on your machine, e.g. in Ubuntu (ref. http://docs.openstack.org/user-guide/common/cli-install-openstack-command-line-clients.html):
 178
 179         apt-get install python-dev python-pip
 180         pip install python-heatclient        # Install heat client
 181         pip install python-openstackclient   # Install the Openstack client to support multiple services
 182
 183  - Create a file (named i.e. ~/openstack/openrc) that sets all the environmental variables required to access the OpenStack platform:
 184
 185         export OS_AUTH_URL=INSERT THE AUTH URL HERE
 186         export OS_USERNAME=INSERT YOUR USERNAME HERE
 187         export OS_TENANT_ID=INSERT YOUR TENANT ID HERE
 188         export OS_REGION_NAME=INSERT THE REGION HERE
 189         export OS_PASSWORD=INSERT YOUR PASSWORD HERE
 190
 191    Alternatively, you can download the OpenStack RC file from the dashboard: Compute -> Access & Security -> API Access -> Download RC File
 192
 193  - Source the script or RC file from command line:
 194
 195         source ~/openstack/openrc
 196
 197  - In order to install the ONAP platform, type:
 198
 199         openstack stack create -t PATH_TO_HEAT_TEMPLATE(YAML FILE) -e PATH_TO_ENV_FILE STACK_NAME  # New Openstack client, OR
 200         heat stack-create STACK_NAME -f PATH_TO_HEAT_TEMPLATE(YAML FILE) -e PATH_TO_ENV_FILE       # Old HEAT client
 201
 202
 203 vFirewall Use Case
 204 ---
 205
 206 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.
 207
 208 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.
 209
 210 __Closed-Loop for vFirewall demo:__
 211
 212 Through the ONAP Portal's Policy Portal, we can find the configuration and operation policies that are currently enabled for the vFirewall use case.
 213
 214 - 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.
 215 - 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.
 216 - APPC sends a request to the packet generator to adjust the traffic volume.
 217 - Changes to the traffic volume can be observed through the link http://sink\_ip\_address:667.
 218
 219 __Adjust packet generator:__
 220
 221 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.
 222
 223 To enable a stream, include *{"id":"fw_udp1", "is-enabled":"true"}* in the *pg-stream* bracket.
 224
 225 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:
 226
 227
 228     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"
 229
 230 The command above enables 5 streams.
 231
 232
 233 vLoadBalancer/vDNS Use Case (old scale out use case)
 234 ---
 235
 236 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.
 237
 238 To test the application, you can run a DNS query from the packet generator VM:
 239
 240     dig @vLoadBalancer_IP host1.dnsdemo.onap.org
 241
 242 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.
 243
 244     ; <<>> DiG 9.10.3-P4-Ubuntu <<>> @192.168.9.111 host1.dnsdemo.onap.org
 245     ; (1 server found)
 246     ;; global options: +cmd
 247     ;; Got answer:
 248     ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 31892
 249     ;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 1, ADDITIONAL: 2
 250     ;; WARNING: recursion requested but not available
 251
 252     ;; OPT PSEUDOSECTION:
 253     ; EDNS: version: 0, flags:; udp: 4096
 254     ;; QUESTION SECTION:
 255     ;host1.dnsdemo.onap.org.            IN      A
 256
 257     ;; ANSWER SECTION:
 258     host1.dnsdemo.onap.org.     604800  IN      A       10.0.100.101
 259
 260     ;; AUTHORITY SECTION:
 261     dnsdemo.onap.org.   604800  IN      NS      dnsdemo.onap.org.
 262
 263     ;; ADDITIONAL SECTION:
 264     dnsdemo.onap.org.   604800  IN      A       10.0.100.100
 265
 266     ;; Query time: 0 msec
 267     ;; SERVER: 192.168.9.111#53(192.168.9.111)
 268     ;; WHEN: Fri Nov 10 17:39:12 UTC 2017
 269     ;; MSG SIZE  rcvd: 97
 270
 271
 272 __Closedloop for vLoadBalancer/vDNS:__
 273
 274 Through the Policy Portal (accessible via the ONAP Portal), we can find the configuration and operation policies that are currently enabled for the vLoadBalancer/vDNS application.
 275 + 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.
 276 + 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 SO to spin up a new DNS instance for the VNF identified by that UUID.
 277 + SO spins up a new DNS instance.
 278
 279
 280 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:
 281
 282     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"
 283
 284 + *{"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.
 285
 286 + 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.
 287
 288 For example, if you want to enable 3 streams, the curl command will be:
 289
 290     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"
 291
 292 When the VNF starts, the packet generator is automatically configured to run 5 streams.
 293
 294 vVolumeGroup Use Case
 295 ---
 296
 297 The vVG directory contains the HEAT template (base\_vvg.yaml) and environment file (base\_vvg.env) used to spin up a volume group in OpenStack and attach it to an existing ONAP instance.
 298
 299 The HEAT environment file contains two parameters:
 300
 301     volume_size: 100
 302     nova_instance: 1234456
 303
 304 volume\_size is the size (in gigabytes) of the volume group. nova\_instance is the name or UUID of the VM to which the volume group will be attached. This parameter should be changed appropriately.
 305
 306
 307 VF Module Scale Out Use Case
 308 ---
 309
 310 The Scale Out use case shows how users/network operators can add capacity to an existing VNF. 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. For Casablanca, both APPC and SDNC controllers are supported. APPC is the official controller used for this use case and it can be used to scale multiple VNF types. SDNC is experimental for now and it can scale only the vDNS VNF developed for ONAP.
 311
 312 This repository hosts the source code and scripts that implement the vLB/vDNS VNFs. The remainder of this section describes the use case at high level, using APPC as VNF controller.
 313
 314 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:
 315
 316  - SO sends a request to APPC to run health check against the VNF;
 317  - If the VNF is healthy, SO instantiates a new VF module and sends a request to APPC to reconfigure the VNF;
 318  - APPC reconfigures the VNF, without interrupting the service;
 319  - 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.
 320
 321 For this use case, we created a new version of the vLB/vDNS, contained in vnfs/VLBMS. Unlike the vLB/vDNS VNF described before, in this modified version the vLB and the vDNS do not run any automated discovery service. Instead, 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:
 322
 323                 {
 324         "vlb-business-vnf-onap-plugin": {
 325                 "vdns-instances": {
 326                         "vdns-instance": [
 327                         {
 328                         "ip-addr": "192.168.10.211",
 329                         "oam-ip-addr": "10.0.150.2",
 330                         "enabled": true
 331                         },
 332                         {
 333                         "ip-addr": "192.168.10.212",
 334                         "oam-ip-addr": "10.0.150.4",
 335                         "enabled": true
 336                         }]
 337                 }
 338         }
 339     }
 340
 341 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.
 342
 343 VID accepts a JSON array in the "Configuration Parameter" box (see later), for example:
 344
 345     [{"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"}]
 346
 347 CLAMP, instead, accepts a YAML file in the "Payload" box in the Policy Creation form, for example:
 348
 349     requestParameters: '{"usePreload":true,"userParams":[]}'
 350     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"}]'
 351
 352 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.
 353
 354 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.
 355
 356 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.
 357
 358 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.
 359
 360 Below is an example of the parameters file (yaml format), which we call parameters.yaml:
 361
 362                 version: V1
 363                 vnf-parameter-list:
 364                 - name: ip-addr
 365                   type: null
 366                   description: null
 367                   required: "true"
 368                   default: null
 369                   source: Manual
 370                   rule-type: null
 371                   request-keys: null
 372                   response-keys: null
 373                 - name: oam-ip-addr
 374                   type: null
 375                   description: null
 376                   required: "true"
 377                   default: null
 378                   source: Manual
 379                   rule-type: null
 380                   request-keys: null
 381                   response-keys: null
 382                 - name: enabled
 383                   type: null
 384                   description: null
 385                   required: "true"
 386                   default: null
 387                   source: Manual
 388                   rule-type: null
 389                   request-keys: null
 390                   response-keys: null
 391
 392 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):
 393
 394                 <vlb-business-vnf-onap-plugin xmlns="urn:opendaylight:params:xml:ns:yang:vlb-business-vnf-onap-plugin">
 395                 <vdns-instances>
 396                         <vdns-instance>
 397                         <ip-addr>${ip-addr}</ip-addr>
 398                         <oam-ip-addr>${oam-ip-addr}</oam-ip-addr>
 399                         <enabled>${enabled}</enabled>
 400                         </vdns-instance>
 401                 </vdns-instances>
 402                 </vlb-business-vnf-onap-plugin>
 403
 404 To create the VNF template in CDT, the following steps are required:
 405  - 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)
 406  - Click "My VNF" Tab. Create your user ID, if necessary
 407  - Click "Create new VNF" entering the VNF type as reported in VID or AAI, e.g. vLoadBalancerMS/vLoadBalancerMS 0
 408  - Select "ConfigScaleOut" action
 409  - Create a new template identifier using the vnf-type name in SDNC as template name, e.g. Vloadbalancerms..dnsscaling..module-1
 410  - Select protocol (Netconf-XML), VNF username (admin), and VNF port number (2831 for NETCONF)
 411  - Click "Parameter Definition" Tab and upload the parameters (.yaml) file
 412  - Click "Template Tab" and upload API template (.yaml) file
 413  - Click "Reference Data" Tab
 414  - Click "Save All to APPC"
 415
 416 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:
 417
 418     restconf/operational/health-vnf-onap-plugin:health-vnf-onap-plugin-state/health-check
 419
 420 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.
 421
 422 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:
 423
 424     mysql -u sdnctl -p (type "gamma" when password is prompted)
 425     use sdnctl;
 426     UPDATE DEVICE_AUTHENTICATION SET PASSWORD='admin' WHERE VNF_TYPE='vLoadBalancerMS/vLoadBalancerMS 0'; (use your VNF type)
 427
 428 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.
 429
 430 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:
 431 - Click the "Closed loop" dropdown window and select "Open CL"
 432 - Select the closed loop model and click "OK"
 433 - In the next screen, click the "Policy" box to create a policy for closed loop, including guard policies
 434 - After creating the policies, click "TCA" and review the blueprint uploaded during service creation and distributed by SDC to CLAMP
 435 - Click the "Manage" dropdown and then "Submit" to push the policies to the Policy Engine
 436 - From the same "Manage" dropdown, click "Deploy" to deploy the TCA blueprint to DCAE
 437
 438 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.
 439
 440 For more information about scale out, known issues and resolution, 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
 441
 442
 443 ONAP Use Cases HEAT Templates
 444 ---
 445
 446 USE CASE VNFs SHOULD BE INSTANTIATED VIA ONAP. THE USER IS NOT SUPPOSED TO DOWNLOAD THE HEAT TEMPLATES AND RUN THEM MANUALLY.
 447
 448 The vFWCL directory contains two HEAT templates, one for creating a packet generator (vPKG/base\_vpkg.yaml) and one for creating a firewall and a packet sink (vFWSNK/base\_vfw.yaml). This use case supports VNF onboarding, instantiation, and closed-loop. The vFW directory, instead, contains a single HEAT template (base\_vfw) that spins up the three VFs. This use case supports VNF onboarding and instantiation only (no support for closed-loop). For Amsterdam Release, the HEAT templates in vFWCL are recommended, so that users can test and demonstrate the entire ONAP end-to-end flow.
 449
 450 The vLB directory contains a base HEAT template (base\_vlb.yaml) that install a packet generator, a load balancer, and a DNS instance, plus another HEAT template (dnsscaling.yaml) for the DNS scaling scenario, in which another DNS server is instantiated.
 451
 452 Before onboarding the VNFs in SDC, the user should set the following values in the HEAT environment files:
 453
 454     image_name: PUT THE VM IMAGE NAME HERE
 455     flavor_name: PUT THE VM FLAVOR NAME HERE
 456     public_net_id: PUT THE PUBLIC NETWORK ID HERE
 457     dcae_collector_ip: PUT THE ADDRESS OF THE DCAE COLLECTOR HERE (NOTE: this is not required for vFWCL/vPKG/base\_vpkg.env)
 458     pub_key: PUT YOUR KEY HERE
 459     cloud_env: PUT openstack OR rackspace HERE
 460
 461 image\_name, flavor\_name, \public\_net\_id, and pub\_key can be obtained as described in the ONAP Section. For deployment in OpenStack, cloud\_env must be openstack.
 462
 463 The DNS scaling HEAT environment file for the vLoadBalancer use case also requires you to specify the private IP of the load balancer, so that the DNS can connect to the vLB:
 464
 465     vlb_private_ip_1: PUT THE PRIVATE ADDRESS OF THE VLB IN THE ONAP NETWORK SPACE HERE
 466
 467 As an alternative, it is possible to set the HEAT environment variables after the VNF is onboarded via SDC by appropriately preloading data into SDNC. That data will be fetched and used by SO to overwrite the default parameters in the HEAT environment file before the VNF is instantiated. For further information about SDNC data preload, please visit the wiki page: https://wiki.onap.org/display/DW/Tutorial_vIMS+%3A+SDNC+Updates
 468
 469 Each VNF has a MANIFEST.json file associated with the HEAT templates. During VNF onboarding, SDC reads the MANIFEST.json file to understand the role of each HEAT template that is part of the VNF (e.g. base template vs. non-base template). VNF onboarding requires users to create a zip file that contains all the HEAT templates and the MANIFEST file. To create the zip file, you can run the following command from shell:
 470
 471     cd VNF_FOLDER  (this is the folder that contains the HEAT templates and the MANIFEST file)
 472     zip ZIP_FILE_NAME.zip *
 473
 474 For information about VNF onboarding via the SDC portal, please refer to the wiki page: https://wiki.onap.org/display/DW/Design
 475
 476 NF Change Management use case
 477 ---
 478
 479 For the Beijing release, we focused on in-place software upgrades, with vendor-specific details encapsulated in Ansible scripts provided by NF vendors. In-place software upgrades use direct communication between the controller (SDNC or APPC) and the NF instance to trigger the software upgrade, with the upgrade executing on the instance without relinquishing any of the physical resources. Both L1 - L3 and L4+ NFs are supported in the ONAP release via SDN-C and APP-C respectively.
 480 The change management workflow is defined as a composition of building blocks that include locking and unlocking the NF instance, executing health checks, and executing the software upgrade.
 481
 482  - The CM workflow for the in-place software upgrade is defined and executed by the service orchestrator (SO).
 483  - A&AI is used to lock/unlock the NF instance
 484  - The pre/post health checks and software upgrade execution are implemented in APPC (L4+ NFs) and SDNC (L1-L3 NFs) by leveraging Ansible services to communicate with the NF instances.
 485  - The user (or, operator) interfaces with the CM workflow using ONAP's VID. SO communicates with A&AI using a REST API and with the controllers SDNC/APPC via DMaaP.
 486
 487 We setup the use case demonstration for the software upgrade on the virtual gateway (vGW) as part of the vCPE use case in ONAP's Beijing release.
 488 The main script for invoking SO in-place software upgrade workflow is in [demo.git]/vnfs/vCPE/scripts/inPlaceSoftwareUpgrade\_vGW.txt . The workflow can be tested without VID by using this script.
 489 To execute the script, the user/operator would login to the SO container and copy/paste the script. One would have to install vim to edit the script and curl to execute commands within the script:
 490
 491  - apt-get update
 492  - apt-get install vim
 493  - apt-get install curl
 494
 495 Check in VID for the available instances - service ID and instance ID - and replace those IDs in the script. Since the use case is for vGW, the controller type is SDNC.
 496
 497 Next, the user/operator would login to the SDNC container and appropriately configure the Ansible playbooks:
 498
 499  - Add the ssh key of the vGW on the Ansible server
 500  - Update VNF IP in DG config
 501  -- docker exec -it sdnc_controller_container bash
 502  - Change the following line in /opt/onap/sdnc/data/properties/lcm-dg.properties with IP of VNF:
 503  -- ansible.nodelist=['10.12.5.85']
 504  - Update VNF IP in Ansible Server
 505  -- docker exec -ti sdnc_ansible_container /bin/bash
 506  -- Add VNF IP in /opt/onap/sdnc/Playbooks/Ansible_inventory
 507  - Update the Playbooks /opt/onap/sdnc/Playbooks
 508  -- ansible_upgradesw@0.00.yml
 509  -- ansible_precheck@0.00.yml
 510  -- ansible_postcheck@0.00.yml