docs/pla_users_guide.md

   1 <!--
   2 Copyright 2020 Arctos Labs Scandinavia AB
   3
   4 Licensed under the Apache License, Version 2.0 (the "License");
   5 you may not use this file except in compliance with the License.
   6 You may obtain a copy of the License at
   7
   8    http://www.apache.org/licenses/LICENSE-2.0
   9
  10 Unless required by applicable law or agreed to in writing, software
  11 distributed under the License is distributed on an "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
  13 implied.
  14 See the License for the specific language governing permissions and
  15 limitations under the License
  16 -->
  17
  18 # Placement module (PLA) User's Guide
  19
  20 ## Introduction
  21 To use the placement functionality of OSM several steps needs to be taken to configure and enable the function.
  22 1.      OSM needs to be installed with the PLA module included
  23 2.      Create the price lists for compute and transport links
  24 3.      Create the inventory of PoP interconnecting links
  25 4.      Update the PLA container with price list and inventory file
  26 5.      Usage - Instantiate the service using the placement engine
  27
  28 ## Install OSM including PLA
  29 PLA is an optional module in OSM. It is installed together with OSM by adding ``--pla`` to the install script.
  30
  31 `$ ./install_osm.sh --pla`
  32
  33 ## Create the price lists
  34 The price list for compute determines the price for each VNF at each VIM (or Point of Presence - PoP). The file (vnf_price_list.yaml) is written in Yaml and is exemplified below.
  35
  36 ```
  37 - vnfd: testVnfOne
  38   prices:
  39     - vim_url: http://10.234.12.47:5000/v3
  40       vim_name: OpenStack1
  41       price: 10
  42     - vim_url: http://10.234.12.44:5000/v3
  43       vim_name: OpenStack2
  44       price: 9
  45     - vim_url: http://10.234.12.46:5000/v3
  46       vim_name: OpenStack3
  47       price: 8
  48     - vim_url: http://10.234.12.43:5000/v3
  49       vim_name: OpenStack4
  50       price: 7
  51 - vnfd: hackfest_multivdu-vnf
  52   prices:
  53     - vim_url: http://10.234.12.47:5000/v3
  54       vim_name: OpenStack1
  55       price: 17
  56     - vim_url: http://10.234.12.44:5000/v3
  57       vim_name: OpenStack2
  58       price: 18
  59     - vim_url: http://10.234.12.46:5000/v3
  60       vim_name: OpenStack3
  61       price: 19
  62     - vim_url: http://10.234.12.43:5000/v3
  63       vim_name: OpenStack4
  64       price: 20
  65 ```
  66
  67 The price list for transport links between VIMs (PoP Interconnecting Link – PiL). In current release the price is given per link without any consideration to BW or other QoS parameter. The file (pil_price_list.yaml) is written in Yaml and is exemplified below. Note: In current OSM release the link characteristics are hard coded into this file, in future releases this data should be retrieved from the infrastructure by monitoring mechanisms.
  68
  69 ```
  70 pil:
  71   - pil_description: Link between OpenStack1 and OpenStack2
  72     pil_price: 12
  73     pil_latency: 120
  74     pil_jitter: 12
  75     pil_endpoints:
  76       - http://10.234.12.47:5000/v3
  77       - http://10.234.12.44:5000/v3
  78   - pil_description: Link between OpenStack1 and OpenStack3
  79     pil_price: 13
  80     pil_latency: 130
  81     pil_jitter: 13
  82     pil_endpoints:
  83       - http://10.234.12.47:5000/v3
  84       - http://10.234.12.46:5000/v3
  85   - pil_description: Link between OpenStack1 and OpenStack4
  86     pil_price: 14
  87     pil_latency: 140
  88     pil_jitter: 14
  89     pil_endpoints:
  90       - http://10.234.12.47:5000/v3
  91       - http://10.234.12.43:5000/v3
  92   - pil_description: Link between OpenStack2 and OpenStack3
  93     pil_price: 23
  94     pil_latency: 230
  95     pil_jitter: 23
  96     pil_endpoints:
  97       - http://10.234.12.44:5000/v3
  98       - http://10.234.12.46:5000/v3
  99   - pil_description: Link between OpenStack2 and OpenStack4
 100     pil_price: 24
 101     pil_latency: 240
 102     pil_jitter: 24
 103     pil_endpoints:
 104       - http://10.234.12.44:5000/v3
 105       - http://10.234.12.43:5000/v3
 106   - pil_description: Link between OpenStack3 and OpenStack4
 107     pil_price: 34
 108     pil_latency: 340
 109     pil_jitter: 34
 110     pil_endpoints:
 111       - http://10.234.12.46:5000/v3
 112       - http://10.234.12.43:5000/v3
 113
 114 ```
 115
 116 ## Create the inventory file
 117 The VIMs configured in OSM are assumed to be connected to each other with transport links - PiLs. In current release the inventory file describes the available PiLs with latency and jitter. If there is no PiL in the inventory file for any pair of PoPs the placement engine will not be able to use that relation for a VL.
 118
 119 ## Update the PLA container
 120 Copy the price lists and inventory files to the PLA container using the following commands:
 121
 122 `$ docker cp vnf_price_list.yaml $(docker ps -qf name=osm_pla):/placement/.`
 123
 124 `$ docker cp pil_price_list.yaml $(docker ps -qf name=osm_pla):/placement/.`
 125
 126 ## Instantiate the service
 127 When creating a NS instance, it is possible to pass instantiation parameters to OSM using the `--config` option of the client or the `config` parameter of the UI. To invoke the placement engine following directives are used.
 128
 129 `
 130 --config '{placement-engine: PLA}'
 131 `
 132
 133 ### Usage examples
 134
 135 #### Basic usage
 136 `$ osm ns-create --ns_name ThreeVNFTest --nsd_name three_vnf_constrained_nsd --vim_account OpenStack1 --config '{placement-engine: PLA}'
 137 `
 138
 139 Using PLA support from the GUI network service create form:
 140
 141 ![Instantiate with PLA support](img/osm_gui_ns_create.png)
 142
 143 ### With pinning of member-vnf-index: "3" to vim_account: OpenStack3
 144 To enable automatic placement with one (or multiple) VNFs at a pre-determined place (e.g. near CPE), PLA has the ability do placement with one or multiple VNFs pinned to datacenter(s). The pinning is done in the same way as explained in section [Multi-site deployments](https://osm.etsi.org/wikipub/index.php/OSM_instantiation_parameters#Multi-site_deployments_.28specifying_different_VIM_accounts_for_different_VNFs.29) in the OSM wiki.
 145
 146 Example NS instantiation using CLI command (pinning one of three VNFs in the used NSD):
 147 `$ osm ns-create --ns_name ThreeVnfTest2 --nsd_name three_vnf_constrained_nsd --vim_account OpenStack1 --config '{placement-engine: PLA, vnf: [{member-vnf-index: “3", vim_account: OpenStack3}]}'`
 148
 149
 150 ### With constraints as instantiation parameters
 151 It is also possible to provide constraints as instantiation parameters. Such constraints are included in a dictionary belonging to the `constraints` key as follows:
 152
 153 `config: {placement-engine: PLA, constraints: {<constraints specifications>}}`
 154
 155 #### vld constraints as instantiation parameters
 156 Currently the supported type of constraints is placed on the vlds, and is identified with the `vld-constraints` key in the constraints specifications. Each vld that is given constraints have the form `{id: <id from nsd>, link-constraints: {latency: <max allowed latency>, jitter: <max allowed jitter>}`. It is not necessary to place constraints on all links, it is also possible to freely mix the supported constraint types `latency` and `jitter` as desired.
 157
 158 Example NS instantiation using CLI command with constraints put on `vld_1` and `vld_2`
 159
 160 `$ osm ns-create --ns_name ThreeVnfTest2 --nsd_name three_vnf_constrained_nsd --vim_account OpenStack1 --config '{placement-engine: PLA, vnf: [{member-vnf-index: “3", vim_account: OpenStack3}], constraints: {vld-constraints: [{id:vld_1, link-constraints: {latency: 120, jitter: 20}}, {id:vld_2, link-constraints: {latency: 120, jitter: 20 }}]}}'`