src/emuvim/api/sonata/README.md

   1 <!--
   2 # Copyright (c) 2017 SONATA-NFV and Paderborn University
   3 # ALL RIGHTS RESERVED.
   4 #
   5 # Licensed under the Apache License, Version 2.0 (the "License");
   6 # you may not use this file except in compliance with the License.
   7 # You may obtain a copy of the License at
   8 #
   9 #    http://www.apache.org/licenses/LICENSE-2.0
  10 #
  11 # Unless required by applicable law or agreed to in writing, software
  12 # distributed under the License is distributed on an "AS IS" BASIS,
  13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 # See the License for the specific language governing permissions and
  15 # limitations under the License.
  16 #
  17 # Neither the name of the SONATA-NFV, Paderborn University
  18 # nor the names of its contributors may be used to endorse or promote
  19 # products derived from this software without specific prior written
  20 # permission.
  21 #
  22 # This work has been performed in the framework of the SONATA project,
  23 # funded by the European Commission under Grant number 671517 through
  24 # the Horizon 2020 and 5G-PPP programmes. The authors would like to
  25 # acknowledge the contributions of their colleagues of the SONATA
  26 # partner consortium (www.sonata-nfv.eu).
  27 -->
  28
  29 # SONATA dummy gatekeeper API:
  30
  31 ## Requirements
  32
  33 * uuid
  34 * hashlib
  35 * zipfile
  36 * yaml
  37 * docker-py
  38 * flask
  39 * flask_restful
  40
  41 ## Run REST API in standalone mode (without emulator):
  42 * `python src/emuvim/api/sonata/dummygatekeeper.py`
  43
  44 ## Run emulator example with active SONATA dummy gatekeeper:
  45 The example starts a small network with two data centers.
  46
  47 * `sudo python src/emuvim/examples/sonata_y1_demo_topology_1.py`
  48
  49 ## Upload a package (*.son) file:
  50
  51 To upload the file `sonata-demo-docker.son` (can be found in `son-emu/misc/`) do:
  52
  53 * `curl -i -X POST -F package=@sonata-demo-docker.son http://127.0.0.1:5000/packages`
  54
  55 To list all uploaded packages do:
  56
  57 * `curl http://127.0.0.1:5000/packages`
  58
  59 To instantiate (start) a service do:
  60
  61 * Specific service: `curl -X POST http://127.0.0.1:5000/instantiations -d "{\"service_uuid\":\"59446b64-f941-40a8-b511-effb0512c21b\"}"`
  62 * Last uploaded service (makes manual tests easier): `curl -X POST http://127.0.0.1:5000/instantiations -d "{}"`
  63
  64 To list all running services do:
  65
  66 * `curl http://127.0.0.1:5000/instantiations`
  67
  68 ## VNF Requirements
  69
  70 A VNF container that is used with the dummy gatekeeper should specify a emulator specific entrypoint script in its Dockerfile:
  71
  72 * `ENV SON_EMU_CMD ./start.sh`
  73
  74 This script is called by the dummy gatekeeper after a VNF was started and the chaining was done. The script can then be used to trigger the execution of individual VNF software.
  75
  76 ATTENTION: The specified script must not block!
  77
  78 ## API definition
  79
  80 This page describes the dummy gatekeeper API. This gatekeeper fakes the original platform gatekeeper during development SDK tools like son-push.
  81
  82 It is also able to deploy our example service package (not any arbitrary service package!) in the emulator for the Y1 demo.
  83
  84 _Note: This API should converge to the API of the original GK as much as possible!_
  85
  86 ## REST API:
  87 <table>
  88 <tr>
  89 <th>Endpoint:</th>
  90 <th>Method:</th>
  91 <th>Header:</th>
  92 <th>Body:</th>
  93 <th>Response:</th>
  94 </tr>
  95 <tr>
  96 <td>/packages</td>
  97 <td>POST</td>
  98 <td>-</td>
  99 <td>{file-content} as "content-type": "multipart/form-data"</td>
 100 <td>{"service_uuid": "c880aaab-f3b9-43ac-ac6b-3d27b46146b7", size=456, sha1=49ee6468dfa4ecbad440d669b249d523a38651be, error: null}</td>
 101 </tr>
 102 <tr>
 103 <td>/packages</td>
 104 <td>GET</td>
 105 <td>-</td>
 106 <td></td>
 107 <td>{service_uuid_list: ["c880aaab-f3b9-43ac-ac6b-3d27b46146b7", "c880aaab-f3b9-43ac-ac6b-3d27b46146b8", "c880aaab-f3b9-43ac-ac6b-3d27b46146b9"]}</td>
 108 </tr>
 109 <tr>
 110 <td>/instantiations</td>
 111 <td>POST</td>
 112 <td>-</td>
 113 <td>{service_uuid: "c880aaab-f3b9-43ac-ac6b-3d27b46146b7"}</td>
 114 <td>{service_instance_uuid: "de4567-f3b9-43ac-ac6b-3d27b461123"}</td>
 115 </tr>
 116 <tr>
 117 <td>/instantiations</td>
 118 <td>GET</td>
 119 <td>-</td>
 120 <td></td>
 121 <td>
 122 {
 123     "service_instance_list": [
 124         [
 125             "9da044b3-1f7a-40e6-a9b3-9e83a9834249",
 126             "9371df14-a595-436a-92b5-fc243b74a9d7"
 127         ]
 128     ]
 129 }
 130 </td>
 131 </tr>
 132 </table>
 133
 134
 135
 136
 137
 138 ## Cleanup
 139 The dummy GK will store some files in your tmp folder in order to fake "catalogues" and "repositories" etc.
 140
 141 * ` sudo rm -r /tmp/son-dummy-gk/`