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).
  35 The file (vnf_price_list.yaml) is written in Yaml. There are two different structures possible for the price list file.
  36 In the first alternative prices for a specific VIM are directly associated with a vnfd.
  37 In the second alternative prices for a specific VIM are also associated with a OSM project id.
  38 The latter alternative makes it possible for different OMS users to have different price models depending on their
  39 associated OMS project.
  40
  41 ###vnf_price_lists.yaml - Alternative one
  42
  43 ```
  44 - vnfd: testVnfOne
  45   prices:
  46     - vim_url: http://10.234.12.47:5000/v3
  47       vim_name: OpenStack1
  48       price: 10
  49     - vim_url: http://10.234.12.44:5000/v3
  50       vim_name: OpenStack2
  51       price: 9
  52 - vnfd: hackfest_multivdu-vnf
  53   prices:
  54     - vim_url: http://10.234.12.47:5000/v3
  55       vim_name: OpenStack1
  56       price: 17
  57     - vim_url: http://10.234.12.44:5000/v3
  58       vim_name: OpenStack2
  59       price: 18
  60 ```
  61 ###vnf_price_list.yaml - Alternative two
  62 ```
  63 - vnfd: testVnfOne
  64     project_alfa:
  65       prices:
  66         - vim_url: http://10.234.12.47:5000/v3
  67           vim_name: OpenStack1
  68           price: 10
  69         - vim_url: http://10.234.12.44:5000/v3
  70           vim_name: OpenStack2
  71           price: 9
  72     project_beta:
  73       prices:
  74         - vim_url: http://10.234.12.47:5000/v3
  75           vim_name: OpenStack1
  76           price: 9
  77         - vim_url: http://10.234.12.44:5000/v3
  78           vim_name: OpenStack2
  79           price: 10
  80 - vnfd: hackfest_multivdu-vnf
  81     project_alfa:
  82       prices:
  83         - vim_url: http://10.234.12.47:5000/v3
  84           vim_name: OpenStack1
  85           price: 17
  86         - vim_url: http://10.234.12.44:5000/v3
  87           vim_name: OpenStack2
  88           price: 18
  89     project_beta:
  90       prices:
  91         - vim_url: http://10.234.12.47:5000/v3
  92           vim_name: OpenStack1
  93           price: 7
  94         - vim_url: http://10.234.12.44:5000/v3
  95           vim_name: OpenStack2
  96           price: 8
  97 ```
  98
  99 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.
 100
 101 ```
 102 pil:
 103   - pil_description: Link between OpenStack1 and OpenStack2
 104     pil_price: 12
 105     pil_latency: 120
 106     pil_jitter: 12
 107     pil_endpoints:
 108       - OpenStack1
 109       - OpenStack2
 110   - pil_description: Link between OpenStack1 and OpenStack3
 111     pil_price: 13
 112     pil_latency: 130
 113     pil_jitter: 13
 114     pil_endpoints:
 115       - OpenStack1
 116       - OpenStack3
 117   - pil_description: Link between OpenStack1 and OpenStack4
 118     pil_price: 14
 119     pil_latency: 140
 120     pil_jitter: 14
 121     pil_endpoints:
 122       - OpenStack1
 123       - OpenStack4
 124   - pil_description: Link between OpenStack2 and OpenStack3
 125     pil_price: 23
 126     pil_latency: 230
 127     pil_jitter: 23
 128     pil_endpoints:
 129       - OpenStack2
 130       - OpenStack3
 131   - pil_description: Link between OpenStack2 and OpenStack4
 132     pil_price: 24
 133     pil_latency: 240
 134     pil_jitter: 24
 135     pil_endpoints:
 136       - OpenStack2
 137       - OpenStack4
 138   - pil_description: Link between OpenStack3 and OpenStack4
 139     pil_price: 34
 140     pil_latency: 340
 141     pil_jitter: 34
 142     pil_endpoints:
 143       - OpenStack3
 144       - OpenStack4
 145
 146 ```
 147
 148 ## Create the inventory file
 149 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.
 150
 151 ## Update the PLA container
 152 Copy the price lists and inventory files to the PLA container using the following commands:
 153
 154 `$ docker cp vnf_price_list.yaml $(docker ps -qf name=osm_pla):/placement/.`
 155
 156 `$ docker cp pil_price_list.yaml $(docker ps -qf name=osm_pla):/placement/.`
 157
 158 ## Instantiate the service
 159 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.
 160
 161 `
 162 --config '{placement-engine: PLA}'
 163 `
 164
 165 ### Usage examples
 166
 167 #### Basic usage
 168 `$ osm ns-create --ns_name ThreeVNFTest --nsd_name three_vnf_constrained_nsd --vim_account OpenStack1 --config '{placement-engine: PLA}'
 169 `
 170
 171 Using PLA support from the GUI network service create form:
 172
 173 ![Instantiate with PLA support](img/osm_gui_ns_create.png)
 174
 175 ### With pinning of member-vnf-index: "3" to vim_account: OpenStack3
 176 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.
 177
 178 Example NS instantiation using CLI command (pinning one of three VNFs in the used NSD):
 179 `$ 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}]}'`
 180
 181
 182 ### With constraints as instantiation parameters
 183 It is also possible to provide constraints as instantiation parameters. Such constraints are included in a dictionary belonging to the `constraints` key as follows:
 184
 185 `config: {placement-engine: PLA, constraints: {<constraints specifications>}}`
 186
 187 #### vld constraints as instantiation parameters
 188 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.
 189
 190 Example NS instantiation using CLI command with constraints put on `vld_1` and `vld_2`
 191
 192 `$ 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 }}]}}'`