charms/layers/sshproxy/README.md

   1 # Overview
   2
   3 This is a [Juju] layer intended to ease the development of charms that need
   4 to execute commands over SSH, such as proxy charms.
   5
   6 # What is a proxy charm?
   7
   8 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].
   9
  10 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.
  11
  12 # Integration
  13
  14 After you've [created your charm], open `interfaces.yaml` and add
  15 `layer:sshproxy` to the includes stanza, as shown below:
  16 ```
  17 includes: ['layer:basic', 'layer:sshproxy']
  18 ```
  19
  20 ## Reactive states
  21
  22 This layer will set the following states:
  23
  24 - `sshproxy.configured` This state is set when SSH credentials have been supplied to the charm.
  25
  26
  27 ## Example
  28 In `reactive/mycharm.py`, you can add logic to execute commands over SSH. This
  29 example is run via a `start` action, and starts a service running on a remote
  30 host.
  31 ```
  32 ...
  33 import charms.sshproxy
  34
  35
  36 @when('sshproxy.configured')
  37 @when('actions.start')
  38 def start():
  39     """ Execute's the command, via the start action` using the
  40     configured SSH credentials
  41     """
  42     sshproxy.ssh("service myservice start")
  43
  44 ```
  45
  46 ## Actions
  47 This layer includes a built-in `run` action useful for debugging or running arbitrary commands:
  48
  49 ```
  50 $ juju run-action mycharm/0 run command=hostname
  51 Action queued with id: 014b72f3-bc02-4ecb-8d38-72bce03bbb63
  52
  53 $ juju show-action-output 014b72f3-bc02-4ecb-8d38-72bce03bbb63
  54 results:
  55   output: juju-66a5f3-11
  56 status: completed
  57 timing:
  58   completed: 2016-10-27 19:53:49 +0000 UTC
  59   enqueued: 2016-10-27 19:53:44 +0000 UTC
  60   started: 2016-10-27 19:53:48 +0000 UTC
  61
  62 ```
  63 ## Known Limitations and Issues
  64
  65 ### Security issues
  66
  67 - Password and key-based authentications are supported, with the caveat that
  68 both (password and private key) are stored plaintext within the Juju controller.
  69
  70 # Configuration and Usage
  71
  72 This layer adds the following configuration options:
  73 - ssh-hostname
  74 - ssh-username
  75 - ssh-password
  76 - ssh-private-key
  77
  78 Once  [configure] those values at any time. Once they are set, the `sshproxy.configured` state flag will be toggled:
  79
  80 ```
  81 juju deploy mycharm ssh-hostname=10.10.10.10 ssh-username=ubuntu ssh-password=yourpassword
  82 ```
  83 or
  84 ```
  85 juju deploy mycharm ssh-hostname=10.10.10.10 ssh-username=ubuntu ssh-private-key="`cat ~/.ssh/id_rsa`"
  86 ```
  87
  88
  89 # Contact Information
  90 Homepage: https://github.com/AdamIsrael/layer-sshproxy
  91
  92 [Juju]: https://jujucharms.com/about
  93 [configure]: https://jujucharms.com/docs/2.0/charms-config
  94 [scaling]: https://jujucharms.com/docs/2.0/charms-scaling
  95 [relations]: https://jujucharms.com/docs/2.0/charms-relations
  96 [leadership]: https://jujucharms.com/docs/2.0/developer-leadership
  97 [created your charm]: https://jujucharms.com/docs/2.0/developer-getting-started