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