charms/layers/vnfproxy/README.md

   1 # vnfproxy
   2
   3 ## Overview
   4
   5 This charm layer is intended for use by vendors who wish to integrate with
   6 OSM. The current release of OSM only supports a lightweight version of Juju
   7 charms, which we will refer to as "proxy charms". Consider the diagram below:
   8
   9 ```
  10 +---------------------+    +---------------------+
  11 |                     <----+                     |
  12 |  Resource           |    |  Service            |
  13 |  Orchestrator (RO)  +---->  Orchestrator (SO)  |
  14 |                     |    |                     |
  15 +------------------+--+    +-------+----^--------+
  16                    |               |    |
  17                    |               |    |
  18                    |               |    |
  19              +-----v-----+       +-v----+--+
  20              |           <-------+         |
  21              |  Virtual  |       |  Proxy  |
  22              |  Machine  |       |  Charm  |
  23              |           +------->         |
  24              +-----------+       +---------+
  25 ```
  26
  27 The Virtual Machine (VM) is created by the Resource Orchestrator (RO), at the
  28 request of the Service Orchestrator (SO). Once the VM has been created, a
  29 "proxy charm" is deployed in order to facilitate operations between the SO and
  30 your service running within the VM.
  31
  32 As such, a proxy charm will expose a number of "actions" that are run via the
  33 SO. By default, the following actions are exposed:
  34
  35 ```bash
  36 actions
  37 ├── reboot
  38 ├── restart
  39 ├── run
  40 ├── start
  41 └── stop
  42 ```
  43
  44 Some actions, such as `run` and `reboot`, do not require any additional configuration. `start`, `stop` and `restart`, however, will require you to
  45 implement the command(s) required to interact with your service.
  46
  47 ## Usage
  48
  49 Create the framework for your proxy charm:
  50
  51 ```bash
  52 $ charm create pingpong
  53 $ cd pingpong
  54 ```
  55
  56 Modify `layer.yaml` to the following:
  57 ```yaml
  58 includes:
  59     - layer:basic
  60     - layer:vnfproxy
  61 ```
  62
  63 The `metadata.yaml` describes your service. It should look similar to the following:
  64
  65 ```yaml
  66 name: vnfproxy
  67 summary: A layer for developing OSM "proxy" charms.
  68 maintainer: Adam Israel <adam.israel@canonical.com>
  69 description: |
  70   VNF "proxy" charms are a lightweight version of a charm that, rather than
  71   installing software on the same machine, execute commands over an ssh channel.
  72 series:
  73   - trusty
  74   - xenial
  75 tags:
  76   - osm
  77   - vnf
  78 subordinate: false
  79 ```
  80
  81 Implement the default action(s) you wish to support by adding the following code to reactive/pingpong.py and fill in the cmd to be run:
  82
  83 ```python
  84 @when('actions.start')
  85 def start():
  86     err = ''
  87     try:
  88         cmd = ""
  89         result, err = charms.sshproxy._run(cmd)
  90     except:
  91         action_fail('command failed:' + err)
  92     else:
  93         action_set({'outout': result})
  94     finally:
  95         remove_flag('actions.start')
  96
  97
  98 @when('actions.stop')
  99 def stop():
 100     err = ''
 101     try:
 102         # Enter the command to stop your service(s)
 103         cmd = "service myname stop"
 104         result, err = charms.sshproxy._run(cmd)
 105     except:
 106         action_fail('command failed:' + err)
 107     else:
 108         action_set({'outout': result})
 109     finally:
 110         remove_flag('actions.stop')
 111
 112
 113 @when('actions.restart')
 114 def restart():
 115     err = ''
 116     try:
 117         # Enter the command to restart your service(s)
 118         cmd = "service myname restart"
 119         result, err = charms.sshproxy._run(cmd)
 120     except:
 121         action_fail('command failed:' + err)
 122     else:
 123         action_set({'outout': result})
 124     finally:
 125         remove_flag('actions.restart')
 126 ```
 127
 128 Rename `README.ex` to `README.md` and describe your application and its usage.
 129
 130 -- fix this. there are cases where the config is useful -- Delete `config.yaml`, since the charm's configuration will be driven by the SO.
 131
 132 Create the `actions.yaml` file; this will describe the additional operations you would like to perform on or against your service.
 133
 134 ```yaml
 135 set-server:
 136     description: "Set the target IP address and port"
 137     params:
 138         server-ip:
 139             description: "IP on which the target service is listening."
 140             type: string
 141             default: ""
 142         server-port:
 143             description: "Port on which the target service is listening."
 144             type: integer
 145             default: 5555
 146     required:
 147         - server-ip
 148 set-rate:
 149     description: "Set the rate of packet generation."
 150     params:
 151         rate:
 152             description: "Packet rate."
 153             type: integer
 154             default: 5
 155 get-stats:
 156     description: "Get the stats."
 157 get-state:
 158     description: "Get the admin state of the target service."
 159 get-rate:
 160     description: "Get the rate set on the target service."
 161 get-server:
 162     description: "Get the target server and IP set"
 163 ```
 164
 165
 166 Once you've implemented your actions, you need to compile the various charm layers:
 167 ```bash
 168 $ charm build
 169
 170 ```
 171
 172 ## Contact