root / docs / developers / config.rst @ 1c366ac9
History | View | Annotate | Download (7.9 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 |
project_cli = astakos |
31 |
default_cloud = my_cloud |
32 |
quota_cli = astakos |
33 |
file_cli = pithos |
34 |
subnet_cli = network |
35 |
history_cli = history |
36 |
group_cli = pithos |
37 |
server_cli = cyclades |
38 |
container_cli = pithos |
39 |
imagecompute_cli = image |
40 |
user_cli = astakos |
41 |
network_cli = network |
42 |
resource_cli = astakos |
43 |
config_cli = config |
44 |
flavor_cli = cyclades |
45 |
sharer_cli = pithos |
46 |
image_cli = image |
47 |
port_cli = network |
48 |
ip_cli = network |
49 |
history_file = /home/someuser/.kamaki.history |
50 |
colors = off |
51 |
log_pid = off |
52 |
log_token = off |
53 |
log_data = off |
54 |
log_file = /home/someuser/.kamaki.log |
55 |
|
56 |
A cloud configuration is required to make kamaki run. The |
57 |
`setup guide <../setup.html>`_ can help when setting one or more cloud |
58 |
configurations. |
59 |
|
60 |
Suppose that a cloud service is available with *https://main.example.com* as |
61 |
the authentication URL and *s0m3-t0k3n* as the user token. In this example, the |
62 |
user has already configured kamaki to refer to the service by the name "main":: |
63 |
|
64 |
[cloud "main"] |
65 |
url=https://main.example.com |
66 |
token=s0m3-t0k3n |
67 |
|
68 |
Suppose that a different cloud service is also available with |
69 |
*https://alternative.example.com* as the authentication URL and |
70 |
*s0m3-0th3r-t0k3n* as the user token. Again, the user configured kamaki to |
71 |
refer to this service as "alternative":: |
72 |
|
73 |
[cloud "alternative"] |
74 |
url=https://alternative.example.com |
75 |
token=s0m3-0th3r-t0k3n |
76 |
|
77 |
If the user picks one of these clouds to be the default, the configuration file |
78 |
will contain the following:: |
79 |
|
80 |
|
81 |
[global] |
82 |
default_cloud=main |
83 |
... <omitted for clarity> |
84 |
|
85 |
[cloud "main"] |
86 |
url=https://main.example.com |
87 |
token=s0m3-t0k3n |
88 |
|
89 |
[cloud "alternative"] |
90 |
url=https://alternative.example.com |
91 |
token=s0m3-0th3r-t0k3n |
92 |
|
93 |
The Config class |
94 |
---------------- |
95 |
|
96 |
The *kamaki.cli.config.Config* class (extends *RawConfigParser* which extends |
97 |
`ConfigParser <http://docs.python.org/release/2.7/library/configparser.html>`_ |
98 |
) offers the methods of the RawConfigParser class (e.g., *get*, *set*), as well |
99 |
as some default settings for kamaki and some additional functionality for |
100 |
managing cloud configurations. |
101 |
|
102 |
.. code-block:: python |
103 |
|
104 |
# Initialize two Config instances. Only the first will contain kamaki |
105 |
# default values |
106 |
|
107 |
from kamaki.cli.config import Config |
108 |
|
109 |
my_config = Config('/some/local/file.cnf') |
110 |
config_without_default_values = Config(with_defaults=False) |
111 |
|
112 |
.. note:: If no file path is given, the Config instance is initialized |
113 |
.. note:: The *with_defaults* flag can be used to omit all default settings |
114 |
from a kamaki Config instance e.g., in case of an external application that |
115 |
does not need any of the kamaki globals. |
116 |
|
117 |
Here are the general purpose accessors offered by Config: |
118 |
|
119 |
* get(section, option): get the *value* of an *option* in the specified |
120 |
*section* e.g., |
121 |
|
122 |
.. code-block:: python |
123 |
|
124 |
# Example: get the default cloud (global.default_cloud option) |
125 |
|
126 |
thread_limit = my_config.get('global', 'default_cloud') |
127 |
|
128 |
* set(section, option, value): set the *value* for an *option* in the specified |
129 |
*section* e.g., |
130 |
|
131 |
.. code-block:: python |
132 |
|
133 |
# Example: set the default_cloud to "main" |
134 |
|
135 |
my_config.set('global', 'default_cloud', 'main') |
136 |
|
137 |
* remove_option(section, option): remove an option from a section e.g., |
138 |
|
139 |
.. code-block:: python |
140 |
|
141 |
# Example: remove the default_cloud option - Config will resort to the |
142 |
# default value for this option |
143 |
|
144 |
my_config.remove_option('global', 'default_cloud') |
145 |
|
146 |
Global options |
147 |
-------------- |
148 |
|
149 |
The global options are used to specify the kamaki CLI and client behavior. A |
150 |
detailed catalog can be found at the |
151 |
`setup section <../setup.html#available-options>`_ . |
152 |
|
153 |
In the Config context, the global options are just the options under the |
154 |
*global* section. |
155 |
|
156 |
Cloud options |
157 |
------------- |
158 |
|
159 |
Cloud options are used to configure one or more cloud services. |
160 |
|
161 |
The following methods are cloud-specific: |
162 |
|
163 |
* get_cloud(cloud, option): Get the value of a cloud option e.g., |
164 |
|
165 |
.. code-block:: python |
166 |
|
167 |
# Get the Auth URL and token for the cloud "main" |
168 |
auth_url = my_config.get_cloud('main', 'url') |
169 |
auth_token = my_config.get_cloud('main', 'token') |
170 |
|
171 |
* set_cloud(cloud, option, value): Set the value of a cloud option e.g., |
172 |
|
173 |
.. code-block:: python |
174 |
|
175 |
# Example: set a new authenticate URL and token for cloud "main" |
176 |
my_config.set_cloud('main', 'url', 'https://new.example.com') |
177 |
my_config.set_cloud('main', 'token', 'n3e-t0k3n-f0r-m41n') |
178 |
|
179 |
* remove_from_cloud(cloud, option): Remove an option from the specified cloud |
180 |
e.g., |
181 |
|
182 |
.. code-block:: python |
183 |
|
184 |
# Example: remove the token of the main cloud, for safety reasons |
185 |
my_config.remove_from_cloud('main', 'url') |
186 |
|
187 |
.. warning:: A get/set/remove_option with a "cloud" section is not valid. There |
188 |
is a way of using the general purpose accessors for cloud configuration, |
189 |
and it is presented bellow, but programmers are discouraged from using it:: |
190 |
|
191 |
my_config.get('cloud.main', 'url') |
192 |
my_config.set('cloud.main', 'url', 'https://new.example.com') |
193 |
my_config.remove_option('cloud.main', 'url') |
194 |
|
195 |
Examples |
196 |
-------- |
197 |
|
198 |
Get the default cloud values from a configuration file |
199 |
"""""""""""""""""""""""""""""""""""""""""""""""""""""" |
200 |
|
201 |
.. code-block:: python |
202 |
|
203 |
from kamaki.cli.config import Config |
204 |
|
205 |
CONFIG_FILE_PATH = '/home/user/my.cnf' |
206 |
|
207 |
cnf = Config(CONFIG_FILE_PATH) |
208 |
try: |
209 |
CLOUD_NAME = cnf.get('global', 'default_cloud') |
210 |
AUTH_URL = cnf.get_cloud(CLOUD_NAME, 'url') |
211 |
AUTH_TOKEN = cnf.get_cloud(CLOUD_NAME, 'token') |
212 |
except KeyError: |
213 |
print 'Error: no valid configuration of a default cloud' |
214 |
|
215 |
Set a new cloud, name it "new_cloud" and set it as default |
216 |
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
217 |
|
218 |
.. code-block:: python |
219 |
|
220 |
from kamaki.cli.config import Config |
221 |
|
222 |
CONFIG_FILE_PATH = '/home/user/my.cnf' |
223 |
CLOUD_NAME = 'new_cloud' |
224 |
AUTH_URL = 'https://new.cloud.example.com' |
225 |
AUTH_TOKEN = 'n3w-cl0ud-t0k3n' |
226 |
|
227 |
cnf = Config(CONFIG_FILE_PATH) |
228 |
cnf.set_cloud(CLOUD_NAME, 'url', AUTH_URL) |
229 |
cnf.set_cloud(CLOUD_NAME, 'token', AUTH_TOKEN) |
230 |
cnf.set('global', 'default_cloud', CLOUD_NAME) |
231 |
|
232 |
# Push the changes to the configuration file |
233 |
cnf.write() |
234 |
|
235 |
List all clouds with their URLs, let the user pick one |
236 |
"""""""""""""""""""""""""""""""""""""""""""""""""""""" |
237 |
|
238 |
.. code-block:: python |
239 |
|
240 |
from kamaki.cli.config import Config |
241 |
|
242 |
cnf = Config() |
243 |
for name, cloud in cnf.items('cloud'): |
244 |
print 'Cloud', name, cloud['url'] |
245 |
|
246 |
choice = raw_input('Type your cloud name, pls: ') |
247 |
if choice in cnf.keys('cloud'): |
248 |
cnf.set('global', 'default_cloud', choice) |
249 |
else: |
250 |
print 'No such cloud configured' |