1
=== modified file 'docs/source/formula.rst'
2
--- docs/source/formula.rst	2011-04-08 17:37:35 +0000
3
+++ docs/source/formula.rst	2011-04-19 15:20:54 +0000
4
@@ -1,80 +1,86 @@
5
1
6
2
Formulas
1
Formulas
7
3
========
2
========
8
4
3
9
5
Introduction
4
Introduction
10
6
------------
5
------------
11
7
6
17
8
In Ensemble, formulas are the description of how services should
7
Formulas define how services integrate and how their service units
18
9
behave when deployed and run.  A single service definition may be run
8
react to events in the distributed environment, as orchestrated by
19
10
multiple times with the same formula and configuration, so we call a
9
Ensemble.
15
11
deployed and running service as a service unit.  Each of those units
16
12
will have an independent copy of the same formula guiding its behavior.
20
13
10
23
14
This specification describes how formulas are built and how they
11
This specification describes how formulas are defined, including their
24
15
react once integrated in an Ensemble environment.
12
metadata and hooks. It also describes the resources available to hooks
25
13
in working with the Ensemble environment.
26
16
14
27
17
15
28
18
The metadata file
16
The metadata file
29
19
-----------------
17
-----------------
30
20
18
35
21
The file named `metadata.yaml`, at the root of the formula, contains
19
The `metadata.yaml` file, at the root of the formula directory,
36
22
details about the formula.
20
describes the formula. The following fields are supported:
33
23
34
24
The following fields are supported:
37
25
21
38
26
  * **name:** - The formula name itself.
22
  * **name:** - The formula name itself.
39
27
23
60
28
  * **revision:** - A monothonically increasing integer which defines the
24
  * **revision:** - A monotonically increasing integer which defines
61
29
    formula version.
25
    the formula version. This number is used to determine if the
62
30
26
    formula needs to be updated in the Ensemble environment. It is
63
31
  * **summary:** - A one line description of the formula
27
    also displayed as output for the ``ensemble status`` command, so
64
32
28
    you can ensure you have the right formula deployed.
65
33
  * **description:** - Long explanation about the formula features
29
66
34
30
  * **summary:** - A one-line description of the formula.
67
35
  * **provides:** - The deployed service unit must have the given relations
31
68
36
    established with another service unit whose formula requires them for
32
  * **description:** - Long explanation of the formula and its
69
37
    the service to work properly. See below for how to define a relation.
33
    features.
70
38
34
71
39
  * **requires:** - The deployed service unit must have the given relations
35
  * **provides:** - The deployed service unit must have the given
72
40
    established with another service unit whose formula provides them for
36
    relations established with another service unit whose formula
73
41
    the service to work properly. See below for how to define a relation.
37
    requires them for the service to work properly. See below for how
74
42
38
    to define a relation.
75
43
  * **peers:** - Relations which are established not in a provides/requires
39
76
44
    (or client/server) style, but with P2P semantics.  When the formula
40
  * **requires:** - The deployed service unit must have the given
77
45
    is deployed as a service unit, all the units from the given service
41
    relations established with another service unit whose formula
78
46
    will automatically be made part of the relation.  See below for how to
42
    provides them for the service to work properly. See below for how
79
47
    define a relation.
43
    to define a relation.
80
44
81
45
  * **peers:** - Relations that are established with P2P semantics
82
46
    instead of a provides/requires (or client/server) style.  When the
83
47
    formula is deployed as a service unit, all the units from the
84
48
    given service will automatically be made part of the relation.
85
49
    See below for how to define a relation.
86
48
50
87
49
51
88
50
Relations available in `provides`, `requires`, and `peers` are defined
52
Relations available in `provides`, `requires`, and `peers` are defined
90
51
the following way:
53
as follows:
91
52
54
92
53
  * **provides|requires|peers:**
55
  * **provides|requires|peers:**
93
54
56
97
55
    * **<relation name>:** - This is a user-provided value which identifies
57
    * **<relation name>:** - This name is a user-provided value which
98
56
      this relation uniquely within the given formula.  Examples might be
58
      identifies the relation uniquely within the given formula.
99
57
      "database", or "cache", or "proxy", or "appserver".
59
      Examples include "database", "cache", "proxy", and "appserver".
100
58
60
101
59
      Each relation may have the following fields defined:
61
      Each relation may have the following fields defined:
102
60
62
107
61
      * **interface:** - This defines the type of this relation.  This
63
      * **interface:** - This field defines the type of the
108
62
        relation will only be established with service units which
64
        relation. The relation will only be established with service
109
63
        define a compatible relation with the same interface. Examples
65
        units that define a compatible relation with the same
110
64
        here might be "http", or "mysql", or "backup-schedule".
66
        interface. Examples include "http", "mysql", and
111
67
        "backup-schedule".
112
65
68
117
66
      * **limit:** - The maximum number of relations of this kind which
69
      * **limit:** - The maximum number of relations of this kind
118
67
        may be established to other service units.  Defaults to 1 for
70
        which may be established to other service units.  Defaults to
119
68
        `requires` relations, and to "none" (no limit) for `provides`
71
        1 for `requires` relations, and to "none" (no limit) for
120
69
        and `peers` relations (note: that's not yet supported).
72
        `provides` and `peers` relations. While you may define it,
121
73
        this field is not yet enforced by Ensemble.
122
70
74
123
71
      * **optional:** - Whether this relation is required for the
75
      * **optional:** - Whether this relation is required for the
126
72
        service unit to function or not.  Defaults to `false`, meaning
76
        service unit to function or not.  Defaults to `false`, which
127
73
        that the relation is required (note: that's not yet supported).
77
        means the relation is required. While you may define it, this
128
78
        field is not yet enforced by Ensemble.
129
74
79
130
75
      As a shortcut, if these properties are not defined, and instead
80
      As a shortcut, if these properties are not defined, and instead
133
76
      a single string value is provided next to the relation name,
81
      a single string value is provided next to the relation name, the
134
77
      the string is taken as the interface value.  For example::
82
      string is taken as the interface value, as seen in this
135
83
      example::
136
78
84
137
79
          requires:
85
          requires:
138
80
            db: mysql
86
            db: mysql
139
@@ -86,88 +92,129 @@
140
86
Hooks
92
Hooks
141
87
-----
93
-----
142
88
94
182
89
Hooks are the mechanism through which service units are notified of
95
Ensemble uses hooks to notify a service unit about changes happening
183
90
events happening around them.  Each hook is an executable within the
96
in its lifecycle or the larger distributed environment. A hook running
184
91
`hooks/` directory of the formula bundle or directory.
97
for a service unit can query this environment, make any desired local
185
92
98
changes on its underlying machine, and change the relation
186
93
Hooks are able to modify the relation settings via command line tools
99
settings.
187
94
offered by Ensemble.  These changes are only perceived by its peers
100
188
95
when the hook has finished running successfully.  If a hook exits with
101
Each hook for a formula is implemented by placing an executable with
189
96
a non-zero error code state changes are not committed.
102
the desired hook name under the ``hooks/`` directory of the formula
190
97
103
directory.  Ensemble will execute the hook based on its file name when
191
98
Some hooks are named after the formula relation which they want to be
104
the corresponding event occurs.
192
99
notified about.
105
193
100
106
All hooks are optional. Not including a corresponding executable in
194
101
The following hooks are currently defined:
107
the formula is treated by Ensemble as if the hook executed and then
195
102
108
exited with an exit code of 0.
196
103
  * **install** - Run just once during the life time of a service unit.
109
197
104
110
The following hooks are with respect to the lifecycle of a service unit:
198
105
  * **start** - Run when the formula is started.  This happens before
111
199
106
    any relation hooks are called. The purpose of this hook is to get
112
  * **install** - Runs just once during the life time of a service
200
107
    the service ready for relations to be established.
113
    unit. Currently this hook is the right place to ensure any package
201
108
114
    dependencies are met. However, in the future Ensemble will use the
202
109
  * **stop** - Run when the formula is stopped.  This will run after any
115
    formula metadata to perform this role instead.
203
110
    established relations are broken.
116
204
111
117
  * **start** - Runs when the service unit is started. This happens
205
112
  * **<relation name>-relation-established** - This hook is run when a
118
    before any relation hooks are called. The purpose of this hook is
206
113
    defined relation is established with one or more peers.  Any
119
    to get the service unit ready for relations to be established.
207
114
    actions related to this relation being established should be
120
208
115
    performed.
121
  * **stop** - Runs when the service unit is stopped. If relations
209
116
122
    exist, they will be broken and the respective hooks called before
210
117
    An example might be providing via `relation-set` the TCP port of
123
    this hook is called.
211
118
    an offered XML-RPC service, or perhaps notifying the started web
124
212
119
    application that the MySQL database is now available.
125
The following hooks are called on each service unit as the membership
213
120
126
of an established relation changes:
214
121
  * **<relation name>-relation-broken** - This hook is run when a
127
215
122
    relation which had at least one other relation hook run for it
128
  * **<relation name>-relation-joined** - Runs upon each time a remote
216
123
    (successfully or not) is now unavailable.  Its purpose is to
129
    service unit joins the relation.
217
124
    allow the formula to clean up established state.
130
218
125
131
  * **<relation name>-relation-changed** - Runs upon each time the
219
126
    An example might be cleaning up the configuration changes which
132
    following events occur:
220
127
    were performed when HAProxy was asked to load-balance for another
133
221
134
    1. A remote service unit joins the relation, right after the
222
135
       **<relation name>-relation-joined** hook was called.
223
136
224
137
    2. A remote service unit changes its relation settings.
225
138
226
139
    This hook enables the formula to modify the service unit state
227
140
    (configuration, running processes, or anything else) to adapt to
228
141
    the relation settings of remote units.
229
142
230
143
    An example usage is that HAProxy needs to be aware of web servers
231
144
    as they become available, including details like its IP
232
145
    address. Web server service units can publish their availability
233
146
    by making the appropriate relation settings in the hook that makes
234
147
    the most sense. Assume the HAProxy uses the relation name of
235
148
    ``server``. Then upon that happening, the HAProxy in its
236
149
    ``server-relation-changed hook`` can then change its own
237
150
    configuration as to what is available to be proxied.
238
151
239
152
  * **<relation name>-relation-departed** - Runs upon each time a
240
153
    remote service unit leaves a relation. This could happen because
241
154
    the service unit has been removed, its service has been destroyed,
242
155
    or the relation between this service and the remote service has
243
156
    been removed.
244
157
245
158
    An example usage is that HAProxy needs to be aware of web servers
246
159
    when they are no longer available. It can remove each web server
247
160
    its configuration as the corresponding service unit departs the
248
161
    relation.
249
162
250
163
This relation hook is with respect to the relation itself:
251
164
252
165
  * **<relation name>-relation-broken** - Runs when a relation which
253
166
    had at least one other relation hook run for it (successfully or
254
167
    not) is now unavailable.  Its purpose is to allow the formula to
255
168
    clean up established state
256
169
257
170
    The service unit can then clean up any established state.  An
258
171
    example might be cleaning up the configuration changes which were
259
172
    performed when HAProxy was asked to load-balance for another
260
128
    service unit.
173
    service unit.
261
129
174
270
130
  * **<name>-relation-changed** - This hook is called when:
175
Note that the coupling between formulas is defined by which settings
271
131
176
are required and made available to them through the relation hooks and
272
132
    1. A new remote service unit joins the relation.
177
how these settings are used. Those conventions then define what the
273
133
178
relation interface really is, and the **interface** name in the
274
134
    2. A remote service unit changes its relation settings.
179
`metadata.yaml` file is simply a way to refer to them and avoid the
275
135
180
attempting of incompatible conversations.  Keep that in mind when
276
136
    3. A remote service unit which was part of the relation has
181
designing your formulas and relations, since it is a good idea to
277
137
       had its relation broken.
182
allow the implementation of the formula to change and be replaced with
278
183
alternative versions without changing the relation conventions in a
279
184
backwards incompatible way.
280
138
185
281
139
186
282
140
Hook environment
187
Hook environment
283
141
----------------
188
----------------
284
142
189
285
143
Hooks can expect to be invoked with a standard environment and
190
Hooks can expect to be invoked with a standard environment and
287
144
context. The following be included:
191
context. The following environment variables are set:
288
145
192
291
146
    * `$ENSEMBLE_UNIT_NAME` - The name of the local unit executing,
193
  * **$ENSEMBLE_UNIT_NAME** - The name of the local unit executing,
292
147
      in the form `<service name>/<unit sequence>`. E.g. myblog/3.
194
    in the form ``<service name>/<unit sequence>``. E.g. ``myblog/3``.
293
148
195
294
149
Hooks called for relation changes will have the follow additional
196
Hooks called for relation changes will have the follow additional
303
150
environment variables available to them.
197
environment variables set:
304
151
198
305
152
    * `$ENSEMBLE_RELATION` - The relation name this hook is running
199
  * **$ENSEMBLE_RELATION** - The relation name this hook is running
306
153
      for.  It's redundant with the hook name, but is necessary for
200
    for.  It's redundant with the hook name, but is necessary for
307
154
      the command line tools to know the current context.
201
    the command line tools to know the current context.
308
155
202
309
156
    * `$ENSEMBLE_REMOTE_UNIT` - The unit name of the remote unit
203
  * **$ENSEMBLE_REMOTE_UNIT** - The unit name of the remote unit
310
157
      which has triggered the hook execution.
204
    which has triggered the hook execution.
311
158
205
312
159
206
313
160
Hook tools
207
Hook tools
314
161
----------
208
----------
315
162
209
320
163
To implement their functionality, hooks may leaverage a set of
210
In implementing their functionality, hooks can leverage a set of
321
164
utilities provided by Ensemble.  These utilities enable the hook to
211
command tools provided by Ensemble.  These utilities enable the hook
322
165
collaborate about configuration state, and to inquire about the peers
212
to collaborate on their relation settings, and to inquire about the
323
166
the service unit has relations with.
213
peers the service unit has relations with.
324
167
214
325
168
The following command line tools are made available:
215
The following command line tools are made available:
326
169
216
328
170
 * **relation-get** - Queries a setting from an established relation
217
  * **relation-get** - Queries a setting from an established relation
329
171
    with one or more service units.  This command will read some
218
    with one or more service units.  This command will read some
330
172
    context information from environment variables (e.g.
219
    context information from environment variables (e.g.
331
173
    $ENSEMBLE_RELATION_NAME).
220
    $ENSEMBLE_RELATION_NAME).
332
@@ -210,13 +257,19 @@
333
210
257
334
211
  * **relation-list** - List all service units participating in the
258
  * **relation-list** - List all service units participating in the
335
212
    established relation.  This list excludes the local service unit
259
    established relation.  This list excludes the local service unit
338
213
    which is executing the command. For provides and requires
260
    which is executing the command. For `provides` and `requires`
339
214
    relation, this will always return a single service unit.
261
    relations, this command will always return a single service unit.
340
215
262
341
216
    Example::
263
    Example::
342
217
264
343
218
        MEMBERS=$(relation-list)
265
        MEMBERS=$(relation-list)
344
219
266
345
267
Changes to relation settings are only committed if the hook exits with
346
268
a non-zero status code. Such changes will then trigger further hook
347
269
execution in the remote unit(s), through the **<relation
348
270
name>-relation-changed** hook. This mechanism enables a general
349
271
communication mechanism for service units to coordinate.
350
272
351
220
273
352
221
Sample metadata.yaml files
274
Sample metadata.yaml files
353
222
--------------------------
275
--------------------------
Status:	Merged
Approved by:	Gustavo Niemeyer on 2011-04-19
Approved revision:	203
Merged at revision:	200
Proposed branch:	lp:~jimbaker/pyjuju/new-hook-semantics-5-docs
Merge into:	lp:pyjuju
Diff against target:	353 lines (+166/-113) 1 file modified docs/source/formula.rst (+166/-113)
To merge this branch:	bzr merge lp:~jimbaker/pyjuju/new-hook-semantics-5-docs
Related bugs:	Link a bug report
Reviewer	Review Type	Date Requested	Status
Gustavo Niemeyer		2011-04-13	Approve on 2011-04-19
Review via email: mp+57536@code.launchpad.net