root / docs / setup.rst @ ef04bdeb
History | View | Annotate | Download (19.1 kB)
1 | 85e3803d | Stavros Sachtouris | Setup |
---|---|---|---|
2 | 85e3803d | Stavros Sachtouris | ===== |
3 | 0c24b26b | Stavros Sachtouris | |
4 | fa479dc3 | Stavros Sachtouris | Kamaki is easy to install from source or as a package. Some advanced or ui features |
5 | fa479dc3 | Stavros Sachtouris | are optional and can be installed separately. Kamaki behavior can be configured in |
6 | fa479dc3 | Stavros Sachtouris | the kamaki config file. |
7 | 0c24b26b | Stavros Sachtouris | |
8 | c52d1b08 | Stavros Sachtouris | Quick Setup |
9 | c52d1b08 | Stavros Sachtouris | ----------- |
10 | c52d1b08 | Stavros Sachtouris | |
11 | fa479dc3 | Stavros Sachtouris | Existing kamaki users should consult the |
12 | fa479dc3 | Stavros Sachtouris | `migration guide <#migrating-from-kamaki-0-8-x-to-0-9>`_ first. |
13 | c52d1b08 | Stavros Sachtouris | |
14 | fa382f9e | Stavros Sachtouris | Kamaki has to be configured for a specific Synnefo deployment, with an |
15 | fa382f9e | Stavros Sachtouris | authentication url and user token pair. Users should also pick an alias to name |
16 | fa382f9e | Stavros Sachtouris | the cloud configuration. This can be any single word, e.g. "default", "mycloud" |
17 | fa382f9e | Stavros Sachtouris | or whatever suits kamaki users. |
18 | fa479dc3 | Stavros Sachtouris | |
19 | fa479dc3 | Stavros Sachtouris | .. code-block:: console |
20 | fa479dc3 | Stavros Sachtouris | |
21 | fa382f9e | Stavros Sachtouris | $ kamaki config set cloud.<cloud alias>.url <cloud-authentication-URL> |
22 | fa382f9e | Stavros Sachtouris | $ kamaki config set cloud.<cloud alias>.token myt0k3n== |
23 | fa479dc3 | Stavros Sachtouris | |
24 | fa382f9e | Stavros Sachtouris | If only one cloud is configured, kamaki automatically picks it as the default. |
25 | fa382f9e | Stavros Sachtouris | Otherwise, a default cloud should be specified: |
26 | fa382f9e | Stavros Sachtouris | |
27 | fa382f9e | Stavros Sachtouris | .. code-block:: console |
28 | fa382f9e | Stavros Sachtouris | |
29 | fa382f9e | Stavros Sachtouris | $ kamaki config set default_cloud <cloud alias> |
30 | fa382f9e | Stavros Sachtouris | |
31 | fa382f9e | Stavros Sachtouris | Since Synnefo version 0.14, a synnefo cloud UI offers a single authentication |
32 | fa382f9e | Stavros Sachtouris | URL, which should be set as the cloud URL for kamaki. All service-specific URLs |
33 | fa382f9e | Stavros Sachtouris | are retrieved and handled automatically by kamaki, through this URL. Users of |
34 | fa382f9e | Stavros Sachtouris | synnefo clouds >=0.14 are advised against using any service-specific URLs. |
35 | 904091dd | Stavros Sachtouris | |
36 | fa479dc3 | Stavros Sachtouris | Migrating from kamaki 0.8.X to 0.9 |
37 | fa479dc3 | Stavros Sachtouris | ---------------------------------- |
38 | fa479dc3 | Stavros Sachtouris | |
39 | fa382f9e | Stavros Sachtouris | This section refers to running installations of kamaki version <= 0.8.X To |
40 | fa382f9e | Stavros Sachtouris | check the current kamaki version: |
41 | fa479dc3 | Stavros Sachtouris | |
42 | fa479dc3 | Stavros Sachtouris | .. code-block:: console |
43 | fa479dc3 | Stavros Sachtouris | |
44 | fa479dc3 | Stavros Sachtouris | $ kamaki -V |
45 | fa479dc3 | Stavros Sachtouris | |
46 | fa382f9e | Stavros Sachtouris | Existing kamaki users should convert their configuration files to v9. To do |
47 | fa382f9e | Stavros Sachtouris | that, kamaki 0.9 can inspect the configuration file and suggests a list of |
48 | fa382f9e | Stavros Sachtouris | config file transformations, which are performed automatically (after users' |
49 | fa382f9e | Stavros Sachtouris | permission). This mechanism is invoked when an API-related kamaki command is |
50 | fa382f9e | Stavros Sachtouris | fired. On example 2.1 we suggest using the `user authenticate` command to fire |
51 | fa382f9e | Stavros Sachtouris | the kamaki config file conversion mechanism. |
52 | fa479dc3 | Stavros Sachtouris | |
53 | fa479dc3 | Stavros Sachtouris | .. code-block:: console |
54 | fa479dc3 | Stavros Sachtouris | :emphasize-lines: 1 |
55 | fa479dc3 | Stavros Sachtouris | |
56 | 904091dd | Stavros Sachtouris | Example 2.1: Convert config file while authenticating user "exampleuser" |
57 | fa479dc3 | Stavros Sachtouris | |
58 | fa479dc3 | Stavros Sachtouris | $ kamaki user authenticate |
59 | fa382f9e | Stavros Sachtouris | Config file format version >= 9.0 is required |
60 | fa382f9e | Stavros Sachtouris | Configuration file: "/home/exampleuser/.kamakirc" |
61 | fa479dc3 | Stavros Sachtouris | but kamaki can fix this: |
62 | fa479dc3 | Stavros Sachtouris | Calculating changes while preserving information |
63 | fa382f9e | Stavros Sachtouris | ... rescue global.token => cloud.default.token |
64 | fa479dc3 | Stavros Sachtouris | ... rescue config.cli => global.config_cli |
65 | fa479dc3 | Stavros Sachtouris | ... rescue history.file => global.history_file |
66 | fa479dc3 | Stavros Sachtouris | ... DONE |
67 | fa479dc3 | Stavros Sachtouris | The following information will NOT be preserved: |
68 | fa479dc3 | Stavros Sachtouris | global.account = |
69 | fa479dc3 | Stavros Sachtouris | global.data_log = on |
70 | fa479dc3 | Stavros Sachtouris | user.account = exampleuser@example.com |
71 | fa479dc3 | Stavros Sachtouris | user.url = https://accounts.okeanos.grnet.gr |
72 | fa479dc3 | Stavros Sachtouris | compute.url = https://cyclades.okeanos.grnet.gr/api/v1.1 |
73 | fa479dc3 | Stavros Sachtouris | file.url = https://pithos.okeanos.grnet.gr/v1 |
74 | fa479dc3 | Stavros Sachtouris | image.url = https://cyclades.okeanos.grnet.gr/plankton |
75 | fa479dc3 | Stavros Sachtouris | |
76 | fa382f9e | Stavros Sachtouris | Kamaki is ready to convert the config file to version 9.0 |
77 | fa479dc3 | Stavros Sachtouris | Overwrite file /home/exampleuser/.kamakirc ? [Y, y] |
78 | fa479dc3 | Stavros Sachtouris | |
79 | fa479dc3 | Stavros Sachtouris | At this point, we should examine the kamaki output. Most options are renamed to |
80 | 904091dd | Stavros Sachtouris | be understood by the new kamaki. |
81 | fa479dc3 | Stavros Sachtouris | |
82 | fa479dc3 | Stavros Sachtouris | Let's take a look at the discarded options: |
83 | fa479dc3 | Stavros Sachtouris | |
84 | 904091dd | Stavros Sachtouris | * `global.account` and `user.account` are not used anymore. |
85 | 904091dd | Stavros Sachtouris | The same is true for the synonyms `store.account` and `pithos.account`. |
86 | 904091dd | Stavros Sachtouris | These options were used to explicitly set a user account or uuid to a |
87 | 904091dd | Stavros Sachtouris | pithos call. In the latest Synnefo version (>= 0.14), these features are |
88 | 904091dd | Stavros Sachtouris | meaningless and therefore omitted. |
89 | fa479dc3 | Stavros Sachtouris | |
90 | 904091dd | Stavros Sachtouris | * `global.data_log` option has never been a valid kamaki config option. |
91 | fa382f9e | Stavros Sachtouris | In this example, the user accidentally misspelled the term `log_data` |
92 | 904091dd | Stavros Sachtouris | (which is a valid kamaki config option) as `data_log`. To fix this, the |
93 | 904091dd | Stavros Sachtouris | user should set the correct option after the conversion is complete |
94 | 904091dd | Stavros Sachtouris | (Example 2.2). |
95 | fa479dc3 | Stavros Sachtouris | |
96 | fa479dc3 | Stavros Sachtouris | Users should press *y* when they are ready. Kamaki has now modified the default |
97 | fa479dc3 | Stavros Sachtouris | config file to conform with kamaki config file v3. Now users should rescue |
98 | fa479dc3 | Stavros Sachtouris | unrescued information (if any). |
99 | fa479dc3 | Stavros Sachtouris | |
100 | fa479dc3 | Stavros Sachtouris | .. code-block:: console |
101 | fa479dc3 | Stavros Sachtouris | :emphasize-lines: 1 |
102 | fa479dc3 | Stavros Sachtouris | |
103 | fa479dc3 | Stavros Sachtouris | Example 2.2: Rescue misspelled log_data option |
104 | fa479dc3 | Stavros Sachtouris | |
105 | fa479dc3 | Stavros Sachtouris | $ kamaki config set log_data on |
106 | fa479dc3 | Stavros Sachtouris | |
107 | 904091dd | Stavros Sachtouris | In order to convert more files, users may run kamaki with the -c option, which |
108 | 904091dd | Stavros Sachtouris | runs kamaki with a different configuration file (Example 2.3) and apply the |
109 | 904091dd | Stavros Sachtouris | steps described above. |
110 | d6737e18 | Stavros Sachtouris | |
111 | c52d1b08 | Stavros Sachtouris | .. code-block:: console |
112 | c52d1b08 | Stavros Sachtouris | :emphasize-lines: 1 |
113 | c52d1b08 | Stavros Sachtouris | |
114 | fa479dc3 | Stavros Sachtouris | Example 2.3: Use kamaki to update a configuration file called ".myfilerc" |
115 | c52d1b08 | Stavros Sachtouris | |
116 | fa479dc3 | Stavros Sachtouris | $ kamaki -c .myfilerc user authenticate |
117 | c52d1b08 | Stavros Sachtouris | |
118 | fa382f9e | Stavros Sachtouris | Multiple clouds |
119 | fa382f9e | Stavros Sachtouris | --------------- |
120 | 904091dd | Stavros Sachtouris | |
121 | 904091dd | Stavros Sachtouris | The following refers to users of multiple Synnefo and/or Open Stack |
122 | 904091dd | Stavros Sachtouris | deployments. In the following, a Synnefo or Open Stack cloud deployment will |
123 | fa382f9e | Stavros Sachtouris | frequently be called as a **cloud**. |
124 | 904091dd | Stavros Sachtouris | |
125 | fa382f9e | Stavros Sachtouris | Kamaki supports accessing multiple clouds from the same kamaki setup. Before |
126 | fa382f9e | Stavros Sachtouris | kamaki 0.9, this was possible only by using multiple config files. Since 0.9, |
127 | fa382f9e | Stavros Sachtouris | kamaki supports multiple clouds in the same configuration. |
128 | 904091dd | Stavros Sachtouris | |
129 | fa382f9e | Stavros Sachtouris | Each cloud corresponds to a Synnefo (or Open Stack) cloud deployment. |
130 | 904091dd | Stavros Sachtouris | Since Synnefo version 0.14, each deployment offers a single point of |
131 | 904091dd | Stavros Sachtouris | authentication, as an **authentication URL** and **token** pair. Users can |
132 | 904091dd | Stavros Sachtouris | retrieve this information through the cloud UI. |
133 | 904091dd | Stavros Sachtouris | |
134 | fa382f9e | Stavros Sachtouris | Once a user has retrieved one URL/token pair per cloud, it is time to assign a |
135 | fa382f9e | Stavros Sachtouris | name to each cloud and let kamaki know about them. |
136 | 904091dd | Stavros Sachtouris | |
137 | fa382f9e | Stavros Sachtouris | For example, let the user have access to two clouds with the following authentication information :: |
138 | 904091dd | Stavros Sachtouris | |
139 | 904091dd | Stavros Sachtouris | cloud alias: devel |
140 | 904091dd | Stavros Sachtouris | authentication URL: https://devel.example.com/astakos/identity/v2.0/ |
141 | 904091dd | Stavros Sachtouris | authentication token: myd3v3170k3n== |
142 | 904091dd | Stavros Sachtouris | |
143 | 904091dd | Stavros Sachtouris | cloud alias: testing |
144 | 904091dd | Stavros Sachtouris | autentication URL: https://testing.example.com/astakos/identity/v2.0/ |
145 | 904091dd | Stavros Sachtouris | authentication token: my73571ng70k3n== |
146 | 904091dd | Stavros Sachtouris | |
147 | 904091dd | Stavros Sachtouris | .. note:: the cloud alias is arbitrary and decided by the user. It is just a |
148 | 904091dd | Stavros Sachtouris | name to call a cloud setup in the kamaki context. |
149 | 904091dd | Stavros Sachtouris | |
150 | 904091dd | Stavros Sachtouris | The user should let kamaki know about these setups: |
151 | 904091dd | Stavros Sachtouris | |
152 | 904091dd | Stavros Sachtouris | .. code-block:: console |
153 | 904091dd | Stavros Sachtouris | |
154 | fa382f9e | Stavros Sachtouris | $ kamaki config set cloud.devel.url https://devel.example.com/astakos/identity/v2.0/ |
155 | fa382f9e | Stavros Sachtouris | $ kamaki config set cloud.devel.token myd3v3170k3n== |
156 | 904091dd | Stavros Sachtouris | $ |
157 | fa382f9e | Stavros Sachtouris | $ kamaki config set cloud.testing.url https://testing.example.com/astakos/identity/v2.0/ |
158 | fa382f9e | Stavros Sachtouris | $ kamaki config set cloud.testing.token my73571ng70k3n== |
159 | 904091dd | Stavros Sachtouris | $ |
160 | 904091dd | Stavros Sachtouris | |
161 | fa382f9e | Stavros Sachtouris | To check if all settings are loaded, a user may list all clouds, as shown |
162 | 904091dd | Stavros Sachtouris | bellow: |
163 | 904091dd | Stavros Sachtouris | |
164 | 904091dd | Stavros Sachtouris | .. code-block:: console |
165 | 904091dd | Stavros Sachtouris | |
166 | fa382f9e | Stavros Sachtouris | $ kamaki config getcloud |
167 | fa382f9e | Stavros Sachtouris | cloud.default.url = https://example.com/astakos.identity/v2.0/ |
168 | fa382f9e | Stavros Sachtouris | cloud.default.url = myd3f4u1770k3n== |
169 | fa382f9e | Stavros Sachtouris | cloud.devel.url = https://devel.example.com/astakos/identity/v2.0/ |
170 | fa382f9e | Stavros Sachtouris | cloud.devel.token = myd3v3170k3n== |
171 | fa382f9e | Stavros Sachtouris | cloud.testing.url = https://testing.example.com/astakos/identity/v2.0/ |
172 | fa382f9e | Stavros Sachtouris | cloud.testing.token = my73571ng70k3n== |
173 | 904091dd | Stavros Sachtouris | $ |
174 | 904091dd | Stavros Sachtouris | |
175 | fa382f9e | Stavros Sachtouris | or query kamaki for a specific cloud: |
176 | 904091dd | Stavros Sachtouris | |
177 | 904091dd | Stavros Sachtouris | .. code-block:: console |
178 | 904091dd | Stavros Sachtouris | |
179 | fa382f9e | Stavros Sachtouris | $ kamaki config get cloud.devel |
180 | fa382f9e | Stavros Sachtouris | cloud.devel.url = https://devel.example.com/astakos/identity/v2.0/ |
181 | fa382f9e | Stavros Sachtouris | cloud.devel.token = myd3v3170k3n== |
182 | 904091dd | Stavros Sachtouris | $ |
183 | 904091dd | Stavros Sachtouris | |
184 | fa382f9e | Stavros Sachtouris | Now kamaki can use any of these clouds, with the **- - cloud** attribute. If |
185 | fa382f9e | Stavros Sachtouris | the **- - cloud** option is ommited, kamaki will query the `default` cloud. |
186 | 904091dd | Stavros Sachtouris | |
187 | 904091dd | Stavros Sachtouris | One way to test this, is the `user athenticate` command: |
188 | 904091dd | Stavros Sachtouris | |
189 | 904091dd | Stavros Sachtouris | .. code-block:: console |
190 | 904091dd | Stavros Sachtouris | |
191 | 904091dd | Stavros Sachtouris | $ kamaki --cloud=devel user authenticate |
192 | 904091dd | Stavros Sachtouris | ... |
193 | 904091dd | Stavros Sachtouris | user : |
194 | 904091dd | Stavros Sachtouris | id : 725d5de4-1bab-45ac-9e98-38a60a8c543c |
195 | 904091dd | Stavros Sachtouris | name : Devel User |
196 | 904091dd | Stavros Sachtouris | $ |
197 | 904091dd | Stavros Sachtouris | $ kamaki --cloud=testing user authenticate |
198 | 904091dd | Stavros Sachtouris | ... |
199 | 904091dd | Stavros Sachtouris | user : |
200 | 904091dd | Stavros Sachtouris | id : 4ed5d527-bab1-ca54-89e9-c345c8a06a83 |
201 | 904091dd | Stavros Sachtouris | name : Testing User |
202 | 904091dd | Stavros Sachtouris | $ |
203 | 904091dd | Stavros Sachtouris | $ kamaki --cloud=default user authenticate |
204 | 904091dd | Stavros Sachtouris | ... |
205 | 904091dd | Stavros Sachtouris | user : |
206 | 904091dd | Stavros Sachtouris | id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473 |
207 | 904091dd | Stavros Sachtouris | name : Default User |
208 | 904091dd | Stavros Sachtouris | $ |
209 | 904091dd | Stavros Sachtouris | $ kamaki user authenticate |
210 | 904091dd | Stavros Sachtouris | ... |
211 | 904091dd | Stavros Sachtouris | user : |
212 | 904091dd | Stavros Sachtouris | id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473 |
213 | 904091dd | Stavros Sachtouris | name : Default User |
214 | 904091dd | Stavros Sachtouris | $ |
215 | 904091dd | Stavros Sachtouris | |
216 | fa382f9e | Stavros Sachtouris | In interactive cell, the cloud is picked when invoking the shell, with |
217 | 904091dd | Stavros Sachtouris | the **- - cloud** option. |
218 | 904091dd | Stavros Sachtouris | |
219 | 0c24b26b | Stavros Sachtouris | Optional features |
220 | 0c24b26b | Stavros Sachtouris | ----------------- |
221 | 0c24b26b | Stavros Sachtouris | |
222 | fa479dc3 | Stavros Sachtouris | For installing any or all of the following, consult the |
223 | fa479dc3 | Stavros Sachtouris | `kamaki installation guide <installation.html#install-ansicolors>`_ |
224 | 961e6040 | Stavros Sachtouris | |
225 | 0c24b26b | Stavros Sachtouris | * ansicolors |
226 | fa382f9e | Stavros Sachtouris | * Add colors to command line / console output |
227 | fa382f9e | Stavros Sachtouris | * Can be switched on/off in kamaki configuration file: `colors = on/off` |
228 | 4054c46d | Stavros Sachtouris | * Has not been tested on non unix / linux based platforms |
229 | 0c24b26b | Stavros Sachtouris | |
230 | 4054c46d | Stavros Sachtouris | * mock |
231 | 4054c46d | Stavros Sachtouris | * For kamaki contributors only |
232 | fa382f9e | Stavros Sachtouris | * Allow unit tests to run on kamaki.clients package |
233 | 4054c46d | Stavros Sachtouris | * Needs mock version 1.X or better |
234 | 0c24b26b | Stavros Sachtouris | |
235 | 904091dd | Stavros Sachtouris | * astakosclient |
236 | 904091dd | Stavros Sachtouris | * For advanced users mostly |
237 | 904091dd | Stavros Sachtouris | * Allows the use of a full astakos command line client |
238 | 904091dd | Stavros Sachtouris | |
239 | fa382f9e | Stavros Sachtouris | Any of the above features can be installed at any time before or after kamaki |
240 | fa382f9e | Stavros Sachtouris | installation. |
241 | 0c24b26b | Stavros Sachtouris | |
242 | 0c24b26b | Stavros Sachtouris | Configuration options |
243 | 0c24b26b | Stavros Sachtouris | --------------------- |
244 | 0c24b26b | Stavros Sachtouris | |
245 | 904091dd | Stavros Sachtouris | There are two kinds of configuration options: |
246 | 0c24b26b | Stavros Sachtouris | |
247 | 904091dd | Stavros Sachtouris | * kamaki-related (global) |
248 | 904091dd | Stavros Sachtouris | interface settings and constants of the kamaki internal mechanism, e.g. |
249 | 904091dd | Stavros Sachtouris | colors in the output, maximum threads per connection, custom logging or |
250 | 904091dd | Stavros Sachtouris | history files, etc. |
251 | 0c24b26b | Stavros Sachtouris | |
252 | fa382f9e | Stavros Sachtouris | * cloud-related |
253 | fa382f9e | Stavros Sachtouris | information needed to connect and use one or more clouds. There are some |
254 | fa382f9e | Stavros Sachtouris | mandatory options (URL, token) and some advanced / optional (e.g. |
255 | fa382f9e | Stavros Sachtouris | service-specific URL overrides or versions) |
256 | 0c24b26b | Stavros Sachtouris | |
257 | 904091dd | Stavros Sachtouris | Kamaki comes with preset default values to all kamaki-releated configuration |
258 | 904091dd | Stavros Sachtouris | options. Cloud-related information is not included in presets and should be |
259 | fa382f9e | Stavros Sachtouris | provided by the user. Kamaki-related options can also be modified. |
260 | 0c24b26b | Stavros Sachtouris | |
261 | 904091dd | Stavros Sachtouris | There are two ways of managing configuration options: edit the config file or |
262 | 904091dd | Stavros Sachtouris | use the kamaki config command. |
263 | 904091dd | Stavros Sachtouris | |
264 | 904091dd | Stavros Sachtouris | Using multiple configuration files |
265 | 904091dd | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
266 | 904091dd | Stavros Sachtouris | |
267 | 904091dd | Stavros Sachtouris | Kamaki setups are stored in configuration files. By default, a Kamaki |
268 | 904091dd | Stavros Sachtouris | installation stores options in *.kamakirc* file located at the user home |
269 | 904091dd | Stavros Sachtouris | directory. |
270 | 904091dd | Stavros Sachtouris | |
271 | 904091dd | Stavros Sachtouris | If a user needs to switch between different kamaki-related setups, Kamaki can |
272 | fa382f9e | Stavros Sachtouris | explicitly load configuration files with the **- - config** (or **- c**) option |
273 | 0c24b26b | Stavros Sachtouris | |
274 | 03d661d8 | Stavros Sachtouris | .. code-block:: console |
275 | 03d661d8 | Stavros Sachtouris | |
276 | 03d661d8 | Stavros Sachtouris | $ kamaki --config <custom_config_file_path> [other options] |
277 | 0c24b26b | Stavros Sachtouris | |
278 | fa382f9e | Stavros Sachtouris | .. note:: For accessing multiple clouds, users do NOT need to create multiple |
279 | fa382f9e | Stavros Sachtouris | configuration files. Instead, we suggest using a single configuration file |
280 | fa382f9e | Stavros Sachtouris | with multiple cloud setups. More details can be found at the |
281 | fa382f9e | Stavros Sachtouris | `multiple clouds guide <#multiple-clouds>`_. |
282 | 0c24b26b | Stavros Sachtouris | |
283 | 0c24b26b | Stavros Sachtouris | Modifying options at runtime |
284 | 0c24b26b | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
285 | 0c24b26b | Stavros Sachtouris | |
286 | 7536c9bf | Stavros Sachtouris | All kamaki commands can be used with the -o option in order to override configuration options at runtime. For example:: |
287 | 0c24b26b | Stavros Sachtouris | |
288 | 03d661d8 | Stavros Sachtouris | .. code-block:: console |
289 | 03d661d8 | Stavros Sachtouris | |
290 | 904091dd | Stavros Sachtouris | $ kamaki file list -o global.pithos_container=anothercontainer |
291 | 0c24b26b | Stavros Sachtouris | |
292 | 904091dd | Stavros Sachtouris | will invoke *kamaki file list* with the specified options, but the initial |
293 | 904091dd | Stavros Sachtouris | global.pithos_container values will not be modified. |
294 | 7ae842c2 | Stavros Sachtouris | |
295 | 0c24b26b | Stavros Sachtouris | Editing options |
296 | 0c24b26b | Stavros Sachtouris | ^^^^^^^^^^^^^^^ |
297 | 0c24b26b | Stavros Sachtouris | |
298 | 0c24b26b | Stavros Sachtouris | Kamaki config command allows users to see and manage all configuration options. |
299 | 0c24b26b | Stavros Sachtouris | |
300 | 0c24b26b | Stavros Sachtouris | * kamaki config list |
301 | 0c24b26b | Stavros Sachtouris | lists all configuration options currently used by a Kamaki installation |
302 | 0c24b26b | Stavros Sachtouris | |
303 | 0c24b26b | Stavros Sachtouris | * kamaki config get <group.option> |
304 | 904091dd | Stavros Sachtouris | show the value of a specific configuration option. Options must be of the |
305 | 904091dd | Stavros Sachtouris | form *group.option*. The term *option* is equivalent to *global.option* |
306 | 0c24b26b | Stavros Sachtouris | |
307 | 0c24b26b | Stavros Sachtouris | * kamaki config set <group.option> <value> |
308 | 904091dd | Stavros Sachtouris | set the group.option to value. If no group is given, the defaults to |
309 | fa382f9e | Stavros Sachtouris | *global*. |
310 | 0c24b26b | Stavros Sachtouris | |
311 | 329753ae | Stavros Sachtouris | * kamaki config delete <group.option> |
312 | 904091dd | Stavros Sachtouris | delete a configuration option. If no group is given, the defaults to |
313 | 904091dd | Stavros Sachtouris | *global* |
314 | 0c24b26b | Stavros Sachtouris | |
315 | 0c24b26b | Stavros Sachtouris | The above commands cause option values to be permanently stored in the Kamaki configuration file. |
316 | 0c24b26b | Stavros Sachtouris | |
317 | fa382f9e | Stavros Sachtouris | The commands above can also be used for **clouds** handling, using the `cloud.` |
318 | fa382f9e | Stavros Sachtouris | prefix. The cloud handling cases are similar but with slightly different |
319 | fa382f9e | Stavros Sachtouris | semantics: |
320 | fa382f9e | Stavros Sachtouris | |
321 | fa382f9e | Stavros Sachtouris | * kamaki config get cloud[.<cloud alias>[.option]] |
322 | fa382f9e | Stavros Sachtouris | * cloud |
323 | fa382f9e | Stavros Sachtouris | list all clouds and their settings |
324 | fa382f9e | Stavros Sachtouris | * cloud.<cloud alias> |
325 | fa382f9e | Stavros Sachtouris | list settings of the cloud aliased as <cloud alias>. If no |
326 | fa382f9e | Stavros Sachtouris | special is configured, use the term `cloud.default` |
327 | fa382f9e | Stavros Sachtouris | * cloud.<cloud alias>.<option> |
328 | 904091dd | Stavros Sachtouris | show the value of the specified option. If no special alias is |
329 | fa382f9e | Stavros Sachtouris | configured, use `cloud.default.<option>` |
330 | 904091dd | Stavros Sachtouris | |
331 | fa382f9e | Stavros Sachtouris | * kamaki config set cloud.<cloud alias>.<option> <value> |
332 | fa382f9e | Stavros Sachtouris | If the cloud alias <cloud alias> does not exist, create it. Then, create |
333 | fa382f9e | Stavros Sachtouris | (or update) the option <option> of this cloud, by setting its value |
334 | 904091dd | Stavros Sachtouris | to <value>. |
335 | 904091dd | Stavros Sachtouris | |
336 | fa382f9e | Stavros Sachtouris | * kamaki config delete cloud.<cloud alias>[.<option>] |
337 | fa382f9e | Stavros Sachtouris | * cloud.<cloud alias> |
338 | 904091dd | Stavros Sachtouris | delete the cloud alias <cloud alias> and all its options |
339 | fa382f9e | Stavros Sachtouris | * cloud.<cloud alias>.<option> |
340 | fa382f9e | Stavros Sachtouris | delete the <option> and its value from the cloud cloud aliased as |
341 | 904091dd | Stavros Sachtouris | <cloud alias> |
342 | 904091dd | Stavros Sachtouris | |
343 | fa382f9e | Stavros Sachtouris | .. note:: To see if a default cloud is configured, get the default_cloud value |
344 | fa382f9e | Stavros Sachtouris | |
345 | fa382f9e | Stavros Sachtouris | .. code-block:: console |
346 | fa382f9e | Stavros Sachtouris | |
347 | fa382f9e | Stavros Sachtouris | $ kamaki config get default_cloud |
348 | fa382f9e | Stavros Sachtouris | |
349 | 0c24b26b | Stavros Sachtouris | Editing the configuration file |
350 | 0c24b26b | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
351 | 0c24b26b | Stavros Sachtouris | |
352 | 329753ae | Stavros Sachtouris | The configuration file is a simple text file that can be created by the user. |
353 | 0c24b26b | Stavros Sachtouris | |
354 | 904091dd | Stavros Sachtouris | .. note:: users of kamaki < 0.9 can use kamaki 0.9.X to automatically convert |
355 | 904091dd | Stavros Sachtouris | their old configuration files to the new config file version (>= 3.0). To |
356 | 904091dd | Stavros Sachtouris | do this, follow `these instructions <#migrating-from-kamaki-0-8-x-to-0-9>`_ |
357 | 904091dd | Stavros Sachtouris | |
358 | 904091dd | Stavros Sachtouris | A simple way to create the configuration file is to set a configuration option |
359 | 904091dd | Stavros Sachtouris | using the kamaki config command. For example: |
360 | 03d661d8 | Stavros Sachtouris | |
361 | 03d661d8 | Stavros Sachtouris | .. code-block:: console |
362 | 0c24b26b | Stavros Sachtouris | |
363 | 904091dd | Stavros Sachtouris | $ kamaki config set global.log_file /home/exampleuser/logs/kamaki.log |
364 | 0c24b26b | Stavros Sachtouris | |
365 | 904091dd | Stavros Sachtouris | In the above example, if the kamaki configuration file does not exist, it will |
366 | 904091dd | Stavros Sachtouris | be created with all the default values plus the *global.log_file* option set to |
367 | 904091dd | Stavros Sachtouris | `/home/exampleuser/logs/kamaki.log` |
368 | 0c24b26b | Stavros Sachtouris | |
369 | 7536c9bf | Stavros Sachtouris | The configuration file is formatted so that it can be parsed by the python ConfigParser module. It consists of command sections that are denoted with brackets. Every section contains variables with values. For example:: |
370 | 0c24b26b | Stavros Sachtouris | |
371 | 904091dd | Stavros Sachtouris | [global] |
372 | 904091dd | Stavros Sachtouris | log_file = /home/exampleuser/logs/kamaki.log |
373 | 904091dd | Stavros Sachtouris | max_threads = 7 |
374 | 904091dd | Stavros Sachtouris | colors = off |
375 | 904091dd | Stavros Sachtouris | |
376 | fa382f9e | Stavros Sachtouris | [cloud "default"] |
377 | 904091dd | Stavros Sachtouris | url = |
378 | 904091dd | Stavros Sachtouris | token = |
379 | 904091dd | Stavros Sachtouris | |
380 | 904091dd | Stavros Sachtouris | A bunch of configuration options are created and set to their default options, |
381 | 904091dd | Stavros Sachtouris | except the log_file option which is set to whatever the specified value. |
382 | 0c24b26b | Stavros Sachtouris | |
383 | fa382f9e | Stavros Sachtouris | The [cloud "default"] section is special and is used to configure the default |
384 | fa382f9e | Stavros Sachtouris | cloud cloud. Kamaki will not be able to run without setting the url and token |
385 | 904091dd | Stavros Sachtouris | values to that section. |
386 | 904091dd | Stavros Sachtouris | |
387 | fa382f9e | Stavros Sachtouris | More clouds can be created on the side of the default cloud, e.g using the |
388 | fa382f9e | Stavros Sachtouris | examples at the `multiple clouds guide <#multiple-clouds>`_ :: |
389 | 904091dd | Stavros Sachtouris | |
390 | fa382f9e | Stavros Sachtouris | [cloud "devel"] |
391 | 904091dd | Stavros Sachtouris | url = https://devel.example.com/astakos/identity/v2.0/ |
392 | 904091dd | Stavros Sachtouris | token = myd3v3170k3n== |
393 | 904091dd | Stavros Sachtouris | |
394 | fa382f9e | Stavros Sachtouris | [cloud "testing"] |
395 | 904091dd | Stavros Sachtouris | url = https://testing.example.com/astakos/identity/v2.0/ |
396 | 904091dd | Stavros Sachtouris | token = my73571ng70k3n== |
397 | 0c24b26b | Stavros Sachtouris | |
398 | 0c24b26b | Stavros Sachtouris | Available options |
399 | 0c24b26b | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^ |
400 | 0c24b26b | Stavros Sachtouris | |
401 | 904091dd | Stavros Sachtouris | The [global] group is treated by kamaki as a generic group for kamaki-related |
402 | 904091dd | Stavros Sachtouris | settings, namely command cli specifications, the thread limit, console colors, |
403 | 904091dd | Stavros Sachtouris | history and log files, log detail options and pithos-specific options. |
404 | 0c24b26b | Stavros Sachtouris | |
405 | 0c24b26b | Stavros Sachtouris | * global.colors <on|off> |
406 | 7536c9bf | Stavros Sachtouris | enable / disable colors in command line based uis. Requires ansicolors, otherwise it is ignored |
407 | 0c24b26b | Stavros Sachtouris | |
408 | 31a30991 | Stavros Sachtouris | * global.log_file <logfile full path> |
409 | 9e87e4bb | Stavros Sachtouris | set a custom location for kamaki logging. Default value is ~/.kamaki.log |
410 | 31a30991 | Stavros Sachtouris | |
411 | 31a30991 | Stavros Sachtouris | * global.log_token <on|off> |
412 | 31a30991 | Stavros Sachtouris | allow kamaki to log user tokens |
413 | 31a30991 | Stavros Sachtouris | |
414 | 31a30991 | Stavros Sachtouris | * global.log_data <on|off> |
415 | 904091dd | Stavros Sachtouris | allow kamaki to log http data (by default, it logs only method, URL and |
416 | 904091dd | Stavros Sachtouris | headers) |
417 | 0c24b26b | Stavros Sachtouris | |
418 | 904091dd | Stavros Sachtouris | * global.file_cli <UI command specifications for file> |
419 | 904091dd | Stavros Sachtouris | a special package that is used to load storage commands to kamaki UIs. |
420 | 904091dd | Stavros Sachtouris | Don't touch this unless if you know what you are doing. |
421 | 0c24b26b | Stavros Sachtouris | |
422 | 904091dd | Stavros Sachtouris | * global.cyclades_cli <UI command specifications for cyclades> |
423 | 904091dd | Stavros Sachtouris | a special package that is used to load cyclades commands to kamaki UIs. |
424 | 904091dd | Stavros Sachtouris | Don't touch this unless you know what you are doing. |
425 | f5d9bc54 | Stavros Sachtouris | |
426 | 904091dd | Stavros Sachtouris | * global.flavor_cli <UI command specifications for VM flavors> |
427 | 904091dd | Stavros Sachtouris | a special package that is used to load cyclades VM flavor commands to |
428 | 904091dd | Stavros Sachtouris | kamaki UIs. Don't touch this unless you know what you are doing. |
429 | 0c24b26b | Stavros Sachtouris | |
430 | 904091dd | Stavros Sachtouris | * global.network_cli <UI command specifications for virtual networks> |
431 | 904091dd | Stavros Sachtouris | a special package that is used to load cyclades virtual network commands to |
432 | 904091dd | Stavros Sachtouris | kamaki UIs. Don't touch this unless you know what you are doing. |
433 | 0c24b26b | Stavros Sachtouris | |
434 | 904091dd | Stavros Sachtouris | * global.image_cli <UI command specs for Plankton or Compute image service> |
435 | 0c24b26b | Stavros Sachtouris | a special package that is used to load image-related commands to kamaki UIs. Don't touch this unless you know what you are doing. |
436 | 0c24b26b | Stavros Sachtouris | |
437 | 904091dd | Stavros Sachtouris | * global.user_cli <UI command specs for Astakos authentication service> |
438 | 904091dd | Stavros Sachtouris | a special package that is used to load astakos-related commands to kamaki |
439 | 904091dd | Stavros Sachtouris | UIs. Don't touch this unless you know what you are doing. |
440 | 329753ae | Stavros Sachtouris | |
441 | 904091dd | Stavros Sachtouris | * global.history_file <history file path> |
442 | 904091dd | Stavros Sachtouris | the path of a simple file for inter-session kamaki history. Make sure |
443 | 904091dd | Stavros Sachtouris | kamaki is executed in a context where this file is accessible for reading |
444 | 904091dd | Stavros Sachtouris | and writing. Kamaki automatically creates the file if it doesn't exist |
445 | a6370d73 | Stavros Sachtouris | |
446 | c5b9380c | Stavros Sachtouris | Additional features |
447 | c5b9380c | Stavros Sachtouris | ^^^^^^^^^^^^^^^^^^^ |
448 | c5b9380c | Stavros Sachtouris | |
449 | f5f2dc53 | Stavros Sachtouris | The livetest suite |
450 | f5f2dc53 | Stavros Sachtouris | """""""""""""""""" |
451 | 329753ae | Stavros Sachtouris | |
452 | 904091dd | Stavros Sachtouris | Kamaki contains a live test suite for the kamaki.clients API, where "live" |
453 | 904091dd | Stavros Sachtouris | means that the tests are performed against active services that up and running. |
454 | 904091dd | Stavros Sachtouris | The live test package is named "livetest", it is accessible as kamaki.clients. |
455 | 904091dd | Stavros Sachtouris | livetest and it is designed to check the actual relation between kamaki and |
456 | 904091dd | Stavros Sachtouris | synnefo services. |
457 | 329753ae | Stavros Sachtouris | |
458 | f5f2dc53 | Stavros Sachtouris | The livetest suite can be activated with the following option on the configuration file:: |
459 | f5d9bc54 | Stavros Sachtouris | |
460 | 904091dd | Stavros Sachtouris | [global] |
461 | 904091dd | Stavros Sachtouris | livetest_cli=livetest |
462 | 904091dd | Stavros Sachtouris | |
463 | 904091dd | Stavros Sachtouris | or with this kamaki command:: |
464 | f5f2dc53 | Stavros Sachtouris | |
465 | 904091dd | Stavros Sachtouris | kamaki config set livetest_cli livetest |
466 | f5f2dc53 | Stavros Sachtouris | |
467 | fa382f9e | Stavros Sachtouris | In most tests, livetest will run as long as the default cloud is configured |
468 | 904091dd | Stavros Sachtouris | correctly. Some commands, though, need some extra settings related to the cloud |
469 | 904091dd | Stavros Sachtouris | the test is performed against, or the example files used in kamaki. |
470 | f5f2dc53 | Stavros Sachtouris | |
471 | 904091dd | Stavros Sachtouris | Here is a list of settings needed: |
472 | f5f2dc53 | Stavros Sachtouris | |
473 | 904091dd | Stavros Sachtouris | * for all tests:: |
474 | fa382f9e | Stavros Sachtouris | * livetest.testcloud = <the cloud alias this test will run against> |
475 | f5f2dc53 | Stavros Sachtouris | |
476 | 904091dd | Stavros Sachtouris | * for astakos client:: |
477 | 904091dd | Stavros Sachtouris | * livetest.astakos_details = <A file with an authentication output> |
478 | 904091dd | Stavros Sachtouris | To create this file, pipeline the output of an authentication command |
479 | 904091dd | Stavros Sachtouris | with the -j option for raw jason output |
480 | f5f2dc53 | Stavros Sachtouris | |
481 | 904091dd | Stavros Sachtouris | .. code-block:: console |
482 | f5f2dc53 | Stavros Sachtouris | |
483 | 904091dd | Stavros Sachtouris | $ kamaki user authenticate -j > astakos.details |
484 | f5f2dc53 | Stavros Sachtouris | |
485 | 904091dd | Stavros Sachtouris | * livetest.astakos_name = <The exact "real" name of testing user> |
486 | 904091dd | Stavros Sachtouris | * livetest.astakos_id = <The valid unique user id of the testing user> |
487 | f5f2dc53 | Stavros Sachtouris | |
488 | 904091dd | Stavros Sachtouris | * for image client: |
489 | 904091dd | Stavros Sachtouris | * livetest.image_details = <A file with the image's metadata> |
490 | 904091dd | Stavros Sachtouris | To create this file, pipeline the output of an image metadata command |
491 | 904091dd | Stavros Sachtouris | with the -j option for raw jason output |
492 | f5f2dc53 | Stavros Sachtouris | |
493 | 904091dd | Stavros Sachtouris | .. code-block:: console |
494 | f5f2dc53 | Stavros Sachtouris | |
495 | 904091dd | Stavros Sachtouris | $ kamaki image meta <img id> -j > img.details |
496 | f5f2dc53 | Stavros Sachtouris | |
497 | 904091dd | Stavros Sachtouris | * livetest.image_id = <A valid image id used for testing> |
498 | 904091dd | Stavros Sachtouris | * livetest.image_local_path = <The local path of the testing image> |
499 | f5f2dc53 | Stavros Sachtouris | |
500 | 904091dd | Stavros Sachtouris | * for flavors (part of the compute client): |
501 | 904091dd | Stavros Sachtouris | * livetest.flavor_details = <A file with the flavor details> |
502 | 904091dd | Stavros Sachtouris | To create this file, pipeline the output of a flavor info command |
503 | 904091dd | Stavros Sachtouris | with the -j option for raw jason output |
504 | f5f2dc53 | Stavros Sachtouris | |
505 | 904091dd | Stavros Sachtouris | .. code-block:: console |
506 | f5f2dc53 | Stavros Sachtouris | |
507 | 904091dd | Stavros Sachtouris | $ kamaki flavor info <flavor id> -j > flavor.details |
508 | f5f2dc53 | Stavros Sachtouris | |
509 | f5f2dc53 | Stavros Sachtouris | |
510 | f5f2dc53 | Stavros Sachtouris | After setup, kamaki can run all tests:: |
511 | f5f2dc53 | Stavros Sachtouris | |
512 | f5f2dc53 | Stavros Sachtouris | $ kamaki livetest all |
513 | f5f2dc53 | Stavros Sachtouris | |
514 | f5f2dc53 | Stavros Sachtouris | a specific test (e.g. astakos):: |
515 | f5f2dc53 | Stavros Sachtouris | |
516 | f5f2dc53 | Stavros Sachtouris | $ kamaki livetest astakos |
517 | f5f2dc53 | Stavros Sachtouris | |
518 | f5f2dc53 | Stavros Sachtouris | or a specific method from a service (e.g. astakos authenticate):: |
519 | f5f2dc53 | Stavros Sachtouris | |
520 | f5f2dc53 | Stavros Sachtouris | $ kamaki livetest astakos authenticate |
521 | f5f2dc53 | Stavros Sachtouris | |
522 | 4054c46d | Stavros Sachtouris | The unit testing system |
523 | 4054c46d | Stavros Sachtouris | """"""""""""""""""""""" |
524 | 4054c46d | Stavros Sachtouris | |
525 | 904091dd | Stavros Sachtouris | Kamaki container a set of finegrained unit tests for the kamaki.clients |
526 | 904091dd | Stavros Sachtouris | package. This set is not used when kamaki is running. Instead, it is aimed to |
527 | 904091dd | Stavros Sachtouris | developers who debug or extent the kamaki clients library. For more |
528 | 904091dd | Stavros Sachtouris | information, check the |
529 | 904091dd | Stavros Sachtouris | `Going Agile <developers/extending-clients-api.html#going-agile>`_ entry at the |
530 | 904091dd | Stavros Sachtouris | `developers section <developers/extending-clients-api.html>`_. |