config.rst 7.64 KB
Newer Older
1
2
3
4
5
The Configuration module
========================

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

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

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

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

17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
Types of configuration options
------------------------------

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

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

    [global]
        default_cloud=
        colors=off
        log_file=${HOME}/.kamaki.log
        log_token=off
        log_data=off
        log_pid=off
        max_threads=7
        history_file=${HOME}/.kamaki.history
        user_cli=astakos
        file_cli=pithos
        server_cli=cyclades
        flavor_cli=cyclades
        network_cli=cyclades
        ip_cli=cyclades
        image_cli=image
        config_cli=config
        history_cli=history

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

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

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

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

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

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


    [global]
        default_cloud=main
        ... <omitted for clarity>

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

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

The Config class
----------------

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

.. code-block:: python

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

    from kamaki.cli.config import Config

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

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

Here are the general purpose accessors offered by Config:

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

114
    .. code-block:: python__
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242

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

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

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

    .. code-block:: python

        # Example: set the default_cloud to "main"

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

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

    .. code-block:: python

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

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

Global options
--------------

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

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

Cloud options
-------------

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

The following methods are cloud-specific:

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

    .. code-block:: python

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

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

    .. code-block:: python

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

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

    .. code-block:: python

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

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

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

Examples
--------

Get the default cloud values from a configuration file
""""""""""""""""""""""""""""""""""""""""""""""""""""""

.. code-block:: python

    from kamaki.cli.config import Config

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

    cnf = Config(CONFIG_FILE_PATH)
    try:
        CLOUD_NAME = cnf.get('global', 'default_cloud')
        AUTH_URL = cnf.get_cloud(CLOUD_NAME, 'url')
        AUTH_TOKEN = cnf.get_cloud(CLOUD_NAME, 'token')
    except KeyError:
        print 'Error: no valid configuration of a default cloud'

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

.. code-block:: python

    from kamaki.cli.config import Config

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

    cnf = Config(CONFIG_FILE_PATH)
    cnf.set_cloud(CLOUD_NAME, 'url', AUTH_URL)
    cnf.set_cloud(CLOUD_NAME, 'token', AUTH_TOKEN)
    cnf.set('global', 'default_cloud', CLOUD_NAME)

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

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

.. code-block:: python

    from kamaki.cli.config import Config

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

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