docs/pla_design_spec.md

   1 <!--
   2 Copyright 2020 ArctosLabs 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) design description
  19 ## Overview
  20 The PLA module provides computation of optimal placement of VNFs over VIMs by matching NS specific requirements to infrastructure availability and run-time metrics, while considering cost of compute/network.
  21
  22 This document supplement the Placement Module (PLA) Users's Guide by providing details on the SW design.
  23
  24 PLA is a separate module in the OSM architecture. As other OSM modules it runs in a Docker container.
  25 PLA interacts with LCM over the Kafka message bus and handles the following message:
  26 * topic: pla - command: get_placement
  27
  28 When LCM receives a ns instantiation command with config parameter `placement-engine: PLA` it shall request placement computation from PLA.
  29 See PLA User's Guide for details and capabilities for different types of instantiation commands and necessary configuration of PLA.
  30
  31 The placement computation is done by Minizinc (www.minizinc.org) on a constraints model that is created according to the content of the ns instantiation command.
  32
  33 The minizinc models are created on demand within PLA using the Jinja2 templating language.
  34
  35 ## SW components overview
  36 The diagram below illustrates the important classes, data structures and libraries within PLA.
  37
  38 ![PLA SW Architecture](img/PLA_SW_Arch.png)
  39
  40 **PLA Server**
  41
  42 This is the PLA server (server.py).
  43 Capability: Produce placement suggestions based on a placement request from LCM OSM module. The get_placement() method extract information based on the referred instantiation operation id and calculates possible deployments for the NS by matching the NS specific requirements to infrastructure, - availability and, -run-time metrics,  while considering cost of compute/network.
  44 Collaborates with: MznPlacementConductor, NsPlacementDataFactory
  45
  46 **MznPlacementConductor**
  47
  48 Capability: Manages minizinc model creation, execution and processing of minizinc output. Use the NsPlacementData provided from the PLA Server and collaborates with MznModelGenerator for model creation and uses PyMzn for execution of the created minizinc model.
  49 Collaborates with: PLA Server, MznModelGenerator
  50
  51 **MznModelGenerator**
  52
  53 Capability: Create instance of MznModel using the information kept in NsPlacementData combined with Jinja2 templating language/templating engine.
  54 Collaborates with: MznPlacementConductor
  55
  56 **NsPlacementDataFactory**
  57
  58 Capability: Knows how to create a NsPlacementData instance. Receives placement request data and collects additional information on; NSD/VNFD, Infrastructure topology, link delays and possibly more things (e.g. resource utilization, after rel.7).
  59 Collaborates with: PLA Server
  60
  61 **NsPlacementData**
  62
  63 Dictionary keeping relevant data for a placement request so that a corresponding minizinc model can be created. Content includes e.g. vim account information, price lists, network topology, link characteristics and network service characteristics.
  64
  65 **PlacementResult**
  66
  67 Carries processed result of the optimal placement solution as computed by minizinc
  68
  69 **MznModel**
  70
  71 String representation of a mzn model
  72
  73 **PyMzn**
  74
  75 PyMzn is a Python library providing bindings to minizinc.
  76
  77 **Jinja2**
  78
  79 Jinja2 is a template engine used in PLA when creating the minizinc model for a placement request.
  80
  81
  82 ## Unit tests
  83 ### Unit testing dependencies
  84 Some of the unit test modules have dependencies to Minizinc, e.g. test_mznmodels.py and test_mznPlacementConductor.py.
  85 If these tests are to be performed outside a PLA container context, like .e.g. from CLI or from within an IDE, setup the environment as follows (linux example):
  86 1. install minizinc as a snap from snapcraft.io/minizinc
  87 2. create a softlink from /minizinc/bin/minizinc to /snap/bin/minizinc to mimic the container structure in the development host
  88
  89 ```
  90 $ sudo snap install minizinc --classic
  91 $ sudo mkdir -p /minizinc/bin
  92 $ sudo ln -s /snap/bin/minizinc /minizinc/bin/minizinc
  93 ```