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