1
.. _"Service Configuration":
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
respond to changes in these options over the lifetime of the `service`
14
deployment. These options apply to the entire service, as opposed to
15
only a specific unit or relation. Configuration is modified by an
16
administrator at deployment time or over the lifetime of the services.
18
As an example a wordpress service may expose a 'blog-title'
19
option. This option would control the title of the blog being
20
published. Changes to this option would be applied to all units
21
implementing this service through the invocation of a hook on each of
24
.. _Charm: ./charm.html
27
Using configuration options
28
---------------------------
30
Configuration options are manipulated using a command line
31
interface. juju provide a `set` command to aid the administrator
35
juju set <service name> option=value [option=value]
37
This command allows changing options at runtime and takes one or more
38
name/value pairs which will be set into the service
39
options. Configuration options which are set together are delivered to
40
the services for handling together. E.g. if you are changing a
41
username and a password, changing them individually may yield bad
42
results since the username will temporarily be set with an incorrect
45
While its possible to set multiple configuration options on the
46
command line its also convenient to pass multiple configuration
47
options via the --file argument which takes the name of a YAML
48
file. The contents of this file will be applied as though these
49
elements had been passed to `juju set`.
51
A configuration file may be provided at deployment time using the
52
--config option, as follows::
54
juju deploy [--config local.yaml] wordpress myblog
56
The service name is looked up inside the YAML file to allow for
57
related service configuration options to be collected into a single
58
file for the purposes of deployment and passed repeated to each
59
`juju deploy` invocation.
61
Below is an example local.yaml containing options
62
which would be used during deployment of a service named myblog.
67
blog-roll: ['http://foobar.com', 'http://testing.com']
68
blog-title: Awesome Sauce
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
only allow the manipulation of options which were explicitly defined
81
The specification of possible configuration values is intentionally
82
minimal, but still evolving. Currently the charm define a list of
83
names which they react. Information includes a human readable
84
description and an optional default value. Additionally `type` may be
85
specified. All options have a default type of 'str' which means its
86
value will only be treated as a text string. Other valid options are
87
'int', 'float' and 'regex'. When 'regex' is used an addtional element
88
must be provided, 'validator'. This must be a valid Python regex as
89
specified at http://docs.python.org/lib/re.html
91
The following `config.yaml` would be included in the top level
92
directory of a charm and includes a list of option definitions::
97
description: List of URLs which will be included as the blog roll
100
description: The title of the blog.
103
description: Password to be used for the account specified by 'username'
108
description: The name of the initial account (given admin permissions).
111
To access these configuration options from a hook we provide the following::
113
config-get [option name]
115
`config-get` returns all the configuration options for a service as
116
JSON data when no option name is specified. If an option name is
117
specified the value of that option is output according to the normal
118
rules and obeying the `--output` and `--format` arguments. Hooks
119
implicitly know the service they are executing for and config-get
120
always gets values from the service of the hook.
122
Changes to options (see previous section) trigger the charm's
123
`config-changed` hook. The `config-changed` hook is guaranteed to run
124
after any changes are made to the configuration, but it is possible
125
that multiple changes will be observed at once. Because its possible
126
to set many configuration options on a single command line invocation
127
it is easily possible to ensure related options are available to the
128
service at the same time.
130
The `config-changed` hook must be written in such a way as to deal
131
with changes to one or more options and deal gracefully with options
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
assume the service is no longer properly configured. If the service is
135
not already in a stopped state it will be stopped and taken out of
136
service. The status command will be extended in the future to report
137
on workflow and unit agent status which will help reveal error
138
conditions of this nature.
140
When options are passed using `juju deploy` their values will be
141
read in from a file and made available to the service prior to the
142
invocation of the its `install` hook. The `install` and `start` hooks
143
will have access to config-get and thus complete access to the
144
configuration options during their execution. If the `install` or
145
`start` hooks don't directly need to deal with options they can simply
146
invoke the `config-changed` hook.
154
This section explains details useful to the implementation but not of
155
interest to the casual reader.
157
Hooks normally attempt to provide a consistent view of the shared
158
state of the system and the handling of config options within hooks
159
(config-changed and the relation hooks) is no different. The first
160
access to the configuration data of a service will retain a cached
161
copy of the service options. Cached data will be used for the
162
duration of the hook invocation.
added
removed
source/drafts/service-config.rst
