charms/layers/pingpong/README.md

   1 # Overview
   2
   3 This repository contains the [Juju] layer that represents a working example of a proxy charm.
   4
   5 # What is a proxy charm?
   6
   7 A proxy charm is a limited type of charm that does not interact with software running on the same host, such as controlling and configuring a remote device (a static VM image, a router/switch, etc.). It cannot take advantage of some of Juju's key features, such as [scaling], [relations], and [leadership].
   8
   9 Proxy charms are primarily a stop-gap, intended to prototype quickly, with the end goal being to develop it into a full-featured charm, which installs and executes code on the same machine as the charm is running.
  10
  11 # Usage
  12
  13 ```bash
  14 # Clone this repository
  15 git clone https://osm.etsi.org/gerrit/osm/juju-charms
  16 cd juju-charms
  17
  18 # Setup environment variables
  19 source juju-env.sh
  20
  21 cd layers/pingpong
  22 charm build
  23
  24 # Examine the built charm
  25 cd ../../builds/pingpong
  26 ls
  27 actions       config.yaml  icon.svg    metadata.yaml     tests
  28 actions.yaml  copyright    layer.yaml  reactive          tox.ini
  29 bin           deps         lib         README.md         wheelhouse
  30 builds        hooks        Makefile    requirements.txt
  31
  32 ```
  33
  34 You can view a screencast of this: https://asciinema.org/a/96738
  35
  36 The `charm build` process combines this pingpong layer with each layer that it
  37 has included in the `metadata.yaml` file, along with their various dependencies.
  38
  39 This built charm is what will then be used by the SO to communicate with the
  40 VNF.
  41
  42 # Configuration
  43
  44 The pingpong charm has several configuration properties that can be set via
  45 the SO:
  46
  47 - ssh-hostname
  48 - ssh-username
  49 - ssh-password
  50 - ssh-private-key
  51 - mode
  52
  53 The ssh-* keys are included by the `sshproxy` layer, and enable the charm to
  54 connect to the VNF image.
  55
  56 The mode key must be one of two values: `ping` or `pong`. This informs the
  57 charm as to which function it is serving.
  58
  59 # Contact Information
  60 For support, please send an email to the [OSM Tech] list.
  61
  62
  63 [OSM Tech]: mailto:OSM_TECH@list.etsi.org
  64 [Juju]: https://jujucharms.com/about
  65 [configure]: https://jujucharms.com/docs/2.0/charms-config
  66 [scaling]: https://jujucharms.com/docs/2.0/charms-scaling
  67 [relations]: https://jujucharms.com/docs/2.0/charms-relations
  68 [leadership]: https://jujucharms.com/docs/2.0/developer-leadership
  69 [created your charm]: https://jujucharms.com/docs/2.0/developer-getting-started
  70
  71
  72
  73
  74
  75 -----
  76
  77
  78 # Integration
  79
  80 After you've [created your charm], open `interfaces.yaml` and add
  81 `layer:sshproxy` to the includes stanza, as shown below:
  82 ```
  83 includes: ['layer:basic', 'layer:sshproxy']
  84 ```
  85
  86 ## Reactive states
  87
  88 This layer will set the following states:
  89
  90 - `sshproxy.configured` This state is set when SSH credentials have been supplied to the charm.
  91
  92
  93 ## Example
  94 In `reactive/mycharm.py`, you can add logic to execute commands over SSH. This
  95 example is run via a `start` action, and starts a service running on a remote
  96 host.
  97 ```
  98 ...
  99 import charms.sshproxy
 100
 101
 102 @when('sshproxy.configured')
 103 @when('actions.start')
 104 def start():
 105     """ Execute's the command, via the start action` using the
 106     configured SSH credentials
 107     """
 108     sshproxy.ssh("service myservice start")
 109
 110 ```
 111
 112 ## Actions
 113 This layer includes a built-in `run` action useful for debugging or running arbitrary commands:
 114
 115 ```
 116 $ juju run-action mycharm/0 run command=hostname
 117 Action queued with id: 014b72f3-bc02-4ecb-8d38-72bce03bbb63
 118
 119 $ juju show-action-output 014b72f3-bc02-4ecb-8d38-72bce03bbb63
 120 results:
 121   output: juju-66a5f3-11
 122 status: completed
 123 timing:
 124   completed: 2016-10-27 19:53:49 +0000 UTC
 125   enqueued: 2016-10-27 19:53:44 +0000 UTC
 126   started: 2016-10-27 19:53:48 +0000 UTC
 127
 128 ```
 129 ## Known Limitations and Issues
 130
 131 ### Security issues
 132
 133 - Password and key-based authentications are supported, with the caveat that
 134 both (password and private key) are stored plaintext within the Juju controller.
 135
 136 # Configuration and Usage
 137
 138 This layer adds the following configuration options:
 139 - ssh-hostname
 140 - ssh-username
 141 - ssh-password
 142 - ssh-private-key
 143
 144 Once  [configure] those values at any time. Once they are set, the `sshproxy.configured` state flag will be toggled:
 145
 146 ```
 147 juju deploy mycharm ssh-hostname=10.10.10.10 ssh-username=ubuntu ssh-password=yourpassword
 148 ```
 149 or
 150 ```
 151 juju deploy mycharm ssh-hostname=10.10.10.10 ssh-username=ubuntu ssh-private-key="cat `~/.ssh/id_rsa`"
 152 ```
 153
 154
 155 # Contact Information
 156 Homepage: https://github.com/AdamIsrael/layer-sshproxy
 157
 158 [Juju]: https://jujucharms.com/about
 159 [configure]: https://jujucharms.com/docs/2.0/charms-config
 160 [scaling]: https://jujucharms.com/docs/2.0/charms-scaling
 161 [relations]: https://jujucharms.com/docs/2.0/charms-relations
 162 [leadership]: https://jujucharms.com/docs/2.0/developer-leadership
 163 [created your charm]: https://jujucharms.com/docs/2.0/developer-getting-started