← Back to branch summary

~jimbaker/pyjuju/ssh-known_hosts

« back to all changes in this revision

Viewing changes to docs/source/drafts/service-config.rst

  • Committer: Gustavo Niemeyer
  • Date: 2011-09-16 00:37:59 UTC
  • mfrom: (348.1.13 the-big-renaming)
  • Revision ID: gustavo@niemeyer.net-20110916003759-bx3vsznroj4gv7w7
Merging the-big-renaming branch! Say hello to juju!

This is a massive change renaming and fixing several things
on the way. Unfortunately my day is finishing and I didn't
manage to get 100% of the tests passing, but there's very
few things broken right now, and I don't want to keep such
a massive change flying around.

We'll sort any details out tomorrow.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/source/drafts/service-config.rst
6
6
Introduction
7
7
------------
8
8
 
9
 
A Formula_ often will require access to specific options or
10
 
configuration. Formulas allow for the manipulation of the various
11
 
configuration options which the formula author has chosen to
12
 
expose. Ensemble provides tools to help manage these options and
 
9
A Charm_ often will require access to specific options or
 
10
configuration. Charms allow for the manipulation of the various
 
11
configuration options which the charm author has chosen to
 
12
expose. juju provides tools to help manage these options and
13
13
respond to changes in these options over the lifetime of the `service`
14
14
deployment. These options apply to the entire service, as opposed to
15
15
only a specific unit or relation. Configuration is modified by an
21
21
implementing this service through the invocation of a hook on each of
22
22
them.
23
23
 
24
 
.. _Formula: ./formula.html
 
24
.. _Charm: ./charm.html
25
25
 
26
26
 
27
27
Using configuration options
28
28
---------------------------
29
29
 
30
30
Configuration options are manipulated using a command line
31
 
interface. Ensemble provide a `set` command to aid the administrator
 
31
interface. juju provide a `set` command to aid the administrator
32
32
in changing values.
33
33
 
34
34
::
35
 
  ensemble set <service name> option=value [option=value]
 
35
  juju set <service name> option=value [option=value]
36
36
 
37
37
This command allows changing options at runtime and takes one or more
38
38
name/value pairs which will be set into the service
46
46
command line its also convenient to pass multiple configuration
47
47
options via the --file argument which takes the name of a YAML
48
48
file. The contents of this file will be applied as though these
49
 
elements had been passed to `ensemble set`.
 
49
elements had been passed to `juju set`.
50
50
 
51
51
A configuration file may be provided at deployment time using the
52
52
--config option, as follows::
53
53
 
54
 
      ensemble deploy [--config local.yaml] wordpress myblog
 
54
      juju deploy [--config local.yaml] wordpress myblog
55
55
 
56
56
The service name is looked up inside the YAML file to allow for
57
57
related service configuration options to be collected into a single
58
58
file for the purposes of deployment and passed repeated to each
59
 
`ensemble deploy` invocation.
 
59
`juju deploy` invocation.
60
60
 
61
61
Below is an example local.yaml containing options
62
62
which would be used during deployment of a service named myblog.
69
69
     password: n0nsense
70
70
 
71
71
 
72
 
Creating formulas
73
 
-----------------
 
72
Creating charms
 
73
---------------
74
74
 
75
 
Formula authors create a `config.yaml` file which resides in the
76
 
formula's top-level directory. The configuration options supported by
77
 
a service are defined within its respective formula. Ensemble will
 
75
Charm authors create a `config.yaml` file which resides in the
 
76
charm's top-level directory. The configuration options supported by
 
77
a service are defined within its respective charm. juju will
78
78
only allow the manipulation of options which were explicitly defined
79
79
as supported.
80
80
 
81
81
The specification of possible configuration values is intentionally
82
 
minimal, but still evolving.  Currently the formula define a list of
 
82
minimal, but still evolving.  Currently the charm define a list of
83
83
names which they react. Information includes a human readable
84
84
description and an optional default value. Additionally `type` may be
85
85
specified. All options have a default type of 'str' which means its
89
89
specified at http://docs.python.org/lib/re.html
90
90
 
91
91
The following `config.yaml` would be included in the top level
92
 
directory of a formula and includes a list of option definitions::
 
92
directory of a charm and includes a list of option definitions::
93
93
 
94
94
    options:
95
95
        blog-roll:
119
119
implicitly know the service they are executing for and config-get
120
120
always gets values from the service of the hook.
121
121
 
122
 
Changes to options (see previous section) trigger the formula's
 
122
Changes to options (see previous section) trigger the charm's
123
123
`config-changed` hook. The `config-changed` hook is guaranteed to run
124
124
after any changes are made to the configuration, but it is possible
125
125
that multiple changes will be observed at once. Because its possible
129
129
 
130
130
The `config-changed` hook must be written in such a way as to deal
131
131
with changes to one or more options and deal gracefully with options
132
 
that are required by the formula but not yet set by an
133
 
administrator. Errors in the config-changed hook force ensemble to
 
132
that are required by the charm but not yet set by an
 
133
administrator. Errors in the config-changed hook force juju to
134
134
assume the service is no longer properly configured. If the service is
135
135
not already in a stopped state it will be stopped and taken out of
136
136
service. The status command will be extended in the future to report
137
137
on workflow and unit agent status which will help reveal error
138
138
conditions of this nature.
139
139
 
140
 
When options are passed using `ensemble deploy` their values will be
 
140
When options are passed using `juju deploy` their values will be
141
141
read in from a file and made available to the service prior to the
142
142
invocation of the its `install` hook. The `install` and `start` hooks
143
143
will have access to config-get and thus complete access to the