Fix bug 1754: update keystone dockerfile to ubuntu 20.04
[osm/devops.git] / 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