Statistics
| Branch: | Tag: | Revision:

root / docs / developers / config.rst @ 40ddc207

History | View | Annotate | Download (7.6 kB)

1
The Configuration module
2
========================
3

    
4
Kamaki CLI offers a configuration module named *config*. It features:
5

    
6
* The global dict *DEFAULTS* with all the configuration settings and default
7
    values for running a kamaki CLI
8

    
9
* The class *Config* is a ConfigParser extension adjusted to offer
10
    kamaki-specific functionalities (e.g., cloud management)
11

    
12
Instances of *kamaki.cli.config.Config* always store data at a local file,
13
the path of which, is usually given by user as a constructor parameter. If the
14
path of the configuration file is not specified explicitly, the value at
15
*kamaki.cli.config.CONFIG_PATH* is used instead.
16

    
17
Types of configuration options
18
------------------------------
19

    
20
There are at least two sections of configuration options i.e., the *global*
21
and the *cloud*. The *global* section is not special, but is used as the
22
default kamaki section by convention. The *Config* class is semantically
23
aware of the *cloud* types and handles them in a special way. Other
24
configuration types can also be created and managed in the same fashion as the
25
*global* ones.
26

    
27
Kamaki preset global options, as they appear in the configuration file::
28

    
29
    [global]
30
        default_cloud=
31
        colors=off
32
        log_file=${HOME}/.kamaki.log
33
        log_token=off
34
        log_data=off
35
        log_pid=off
36
        max_threads=7
37
        history_file=${HOME}/.kamaki.history
38
        user_cli=astakos
39
        file_cli=pithos
40
        server_cli=cyclades
41
        flavor_cli=cyclades
42
        network_cli=cyclades
43
        ip_cli=cyclades
44
        image_cli=image
45
        config_cli=config
46
        history_cli=history
47

    
48
A cloud configuration is required to make kamaki run. The
49
`setup guide <../setup.html>`_ can help when setting one or more cloud
50
configurations.
51

    
52
Suppose that a cloud service is available with *https://main.example.com* as
53
the authentication URL and *s0m3-t0k3n* as the user token. In this example, the
54
user has already configured kamaki to refer to the service by the name "main"::
55

    
56
    [cloud "main"]
57
        url=https://main.example.com
58
        token=s0m3-t0k3n
59

    
60
Suppose that a different cloud service is also available with
61
*https://alternative.example.com* as the authentication URL and
62
*s0m3-0th3r-t0k3n* as the user token. Again, the user configured kamaki to
63
refer to this service as "alternative"::
64

    
65
    [cloud "alternative"]
66
        url=https://alternative.example.com
67
        token=s0m3-0th3r-t0k3n
68

    
69
If the user picks one of these clouds to be the default, the configuration file
70
will contain the following::
71

    
72

    
73
    [global]
74
        default_cloud=main
75
        ... <omitted for clarity>
76

    
77
    [cloud "main"]
78
        url=https://main.example.com
79
        token=s0m3-t0k3n
80

    
81
    [cloud "alternative"]
82
        url=https://alternative.example.com
83
        token=s0m3-0th3r-t0k3n
84

    
85
The Config class
86
----------------
87

    
88
The *kamaki.cli.config.Config* class (extends *RawConfigParser* which extends
89
`ConfigParser <http://docs.python.org/release/2.7/library/configparser.html>`_
90
) offers the methods of the RawConfigParser class (e.g., *get*, *set*), as well
91
as some default settings for kamaki and some additional functionality for
92
managing cloud configurations.
93

    
94
.. code-block:: python
95

    
96
    # Initialize two Config instances. Only the first will contain kamaki
97
    # default values
98

    
99
    from kamaki.cli.config import Config
100

    
101
    my_config = Config('/some/local/file.cnf')
102
    config_without_default_values = Config(with_defaults=False)
103

    
104
.. note:: If no file path is given, the Config instance is initialized
105
.. note:: The *with_defaults* flag can be used to omit all default settings
106
    from a kamaki Config instance e.g., in case of an external application that
107
    does not need any of the kamaki globals.
108

    
109
Here are the general purpose accessors offered by Config:
110

    
111
* get(section, option): get the *value* of an *option* in the specified
112
    *section* e.g.,
113

    
114
    .. code-block:: python
115

    
116
        # Example: get the default cloud (global.default_cloud option)
117

    
118
        thread_limit = my_config.get('global', 'default_cloud')
119

    
120
* set(section, option, value): set the *value* for an *option* in the specified
121
    *section* e.g.,
122

    
123
    .. code-block:: python
124

    
125
        # Example: set the default_cloud to "main"
126

    
127
        my_config.set('global', 'default_cloud', 'main')
128

    
129
* remove_option(section, option): remove an option from a section e.g.,
130

    
131
    .. code-block:: python
132

    
133
        # Example: remove the default_cloud option - Config will resort to the
134
        # default value for this option
135

    
136
        my_config.remove_option('global', 'default_cloud')
137

    
138
Global options
139
--------------
140

    
141
The global options are used to specify the kamaki CLI and client behavior. A
142
detailed catalog can be found at the
143
`setup section <../setup.html#available-options>`_ .
144

    
145
In the Config context, the global options are just the options under the
146
*global* section.
147

    
148
Cloud options
149
-------------
150

    
151
Cloud options are used to configure one or more cloud services.
152

    
153
The following methods are cloud-specific:
154

    
155
* get_cloud(cloud, option): Get the value of a cloud option e.g.,
156

    
157
    .. code-block:: python
158

    
159
        # Get the Auth URL and token for the cloud "main"
160
        auth_url = my_config.get_cloud('main', 'url')
161
        auth_token = my_config.get_cloud('main', 'token')
162

    
163
* set_cloud(cloud, option, value): Set the value of a cloud option e.g.,
164

    
165
    .. code-block:: python
166

    
167
        # Example: set a new authenticate URL and token for cloud "main"
168
        my_config.set_cloud('main', 'url', 'https://new.example.com')
169
        my_config.set_cloud('main', 'token', 'n3e-t0k3n-f0r-m41n')
170

    
171
* remove_from_cloud(cloud, option): Remove an option from the specified cloud
172
    e.g.,
173

    
174
    .. code-block:: python
175

    
176
        # Example: remove the token of the main cloud, for safety reasons
177
        my_config.remove_from_cloud('main', 'url')
178

    
179
.. warning:: A get/set/remove_option with a "cloud" section is not valid. There
180
    is a way of using the general purpose accessors for cloud configuration,
181
    and it is presented bellow, but programmers are discouraged from using it::
182

    
183
        my_config.get('cloud.main', 'url')
184
        my_config.set('cloud.main', 'url', 'https://new.example.com')
185
        my_config.remove_option('cloud.main', 'url')
186

    
187
Examples
188
--------
189

    
190
Get the default cloud values from a configuration file
191
""""""""""""""""""""""""""""""""""""""""""""""""""""""
192

    
193
.. code-block:: python
194

    
195
    from kamaki.cli.config import Config
196

    
197
    CONFIG_FILE_PATH = '/home/user/my.cnf'
198

    
199
    cnf = Config(CONFIG_FILE_PATH)
200
    try:
201
        CLOUD_NAME = cnf.get('global', 'default_cloud')
202
        AUTH_URL = cnf.get_cloud(CLOUD_NAME, 'url')
203
        AUTH_TOKEN = cnf.get_cloud(CLOUD_NAME, 'token')
204
    except KeyError:
205
        print 'Error: no valid configuration of a default cloud'
206

    
207
Set a new cloud, name it "new_cloud" and set it as default
208
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
209

    
210
.. code-block:: python
211

    
212
    from kamaki.cli.config import Config
213

    
214
    CONFIG_FILE_PATH = '/home/user/my.cnf'
215
    CLOUD_NAME = 'new_cloud'
216
    AUTH_URL = 'https://new.cloud.example.com'
217
    AUTH_TOKEN = 'n3w-cl0ud-t0k3n'
218

    
219
    cnf = Config(CONFIG_FILE_PATH)
220
    cnf.set_cloud(CLOUD_NAME, 'url', AUTH_URL)
221
    cnf.set_cloud(CLOUD_NAME, 'token', AUTH_TOKEN)
222
    cnf.set('global', 'default_cloud', CLOUD_NAME)
223

    
224
    # Push the changes to the configuration file
225
    cnf.write()
226

    
227
List all clouds with their URLs, let the user pick one
228
""""""""""""""""""""""""""""""""""""""""""""""""""""""
229

    
230
.. code-block:: python
231

    
232
    from kamaki.cli.config import Config
233

    
234
    cnf = Config()
235
    for name, cloud in cnf.items('cloud'):
236
        print 'Cloud', name, cloud['url']
237

    
238
    choice = raw_input('Type your cloud name, pls: ')
239
    if choice in cnf.keys('cloud'):
240
        cnf.set('global', 'default_cloud', choice)
241
    else:
242
        print 'No such cloud configured'