Statistics
| Branch: | Tag: | Revision:

root / docs / collection_of_examples / configuration.rst @ 9d0a8ecf

History | View | Annotate | Download (10.7 kB)

1
Configuration
2
=============
3

    
4
Since kamaki 0.9, the format of the configuration file has changed. In this
5
scenario, we have an old configuration file at ${HOME}/.kamakirc that we need
6
to convert. We also create a new one from scratch. In both cases, we have to
7
set up one or more clouds in a single configuration and we also examine a case
8
of multiple configurations.
9

    
10
Convert old configuration file
11
------------------------------
12

    
13
First, back up the old file
14

    
15
.. code-block:: console
16

    
17
    $ cp ~/.kamakirc ~/backups/.kamakirc
18

    
19
Now, let kamaki do the conversion
20

    
21
.. code-block:: console
22

    
23
    $ kamaki user authenticate
24
    . Config file format version >= 9.0 is required
25
    . Configuration file: /home/someuser/.kamakirc
26
    . Attempting to fix this:
27
    . Calculating changes while preserving information
28
    . ... rescue global.token => cloud.default.token
29
    . ... rescue user.cli => global.user_cli
30
    . ... rescue network.cli => global.network_cli
31
    . ... rescue file.cli => global.file_cli
32
    . ... rescue flavor.cli => global.flavor_cli
33
    . ... rescue config.cli => global.config_cli
34
    . ... rescue image.cli => global.image_cli
35
    . ... rescue server.cli => global.server_cli
36
    . ... rescue history.file => global.history_file
37
    . ... rescue history.cli => global.history_cli
38
    . ... DONE
39
    . The following information will NOT be preserved:
40
    .     global.account = AccountName
41
    .     user.url = https://accounts.example.com
42
    .     user.account = UserAccountName
43
    .     compute.url = https://cyclades.example.com/api/v1.1
44
    .     file.url = https://pithos.example.com/v1
45
    .     image.url = https://cyclades.example.com/plankton
46
    .     store.account = OldForgotenAccountName
47
    . Kamaki is ready to convert the config file
48
    . Create (overwrite) file .kamakirc.okeanos ? [y/N]
49
    .
50
    <y is pressed>
51
    .
52
    . No cloud "default" is configured
53
    . |  To configure a new cloud "default", find and set the
54
    . |  single authentication URL and token:
55
    . |    kamaki config set cloud.default.url <URL>
56
    . |    kamaki config set cloud.default.token <t0k3n>
57
    $
58

    
59
.. warning:: A new cloud configuration with the name "default" is created. The
60
    global token that was set in the old configuration file, is preserved as
61
    the token of the "default" cloud. Still, kamaki needs a url for the cloud
62
    and it encourages you to reset the token as well.
63

    
64
.. note:: Some options are discarded. Among them, are the service urls, like
65
    user.url, compute.url, image.url and file.url . These settings are obsolete
66
    since Synnefo 0.14 and kamaki 0.9 so you do not need to recover them. The
67
    same is true for user accounts (retrieved automatically)
68

    
69
.. note:: You can safely remove the global.XXX_cli options from kamaki
70
    configuration file. Kamaki can automatically resolve the default values for
71
    these internal options. These options are usefull when overloading the
72
    default command behaviors, but are not needed otherwise.
73

    
74
Attempt to create a new configuration
75
-------------------------------------
76

    
77
Ask kamaki to load from a non-existing configuration file
78

    
79
.. code-block:: console
80

    
81
    $ kamaki -c nonexisting.cnf user authenticate
82
    . No cloud is configured
83
    . |  To configure a new cloud "<cloud name>", find and set the
84
    . |  single authentication URL and token:
85
    . |    kamaki config set cloud.<cloud name>.url <URL>
86
    . |    kamaki config set cloud.<cloud name>.token <t0k3n>
87
    $ ls -l nonexisting.cnf
88
    . ls: cannot access nonexisting.cnf: No such file or directory
89
    $
90

    
91
.. note:: configuration file is not created, but it will be when we set the
92
    first configuration value in it, as shown in the following subsection.
93

    
94
Configure a cloud and create a new configuration
95
------------------------------------------------
96

    
97
Set the URL for new cloud "mytest"
98

    
99
.. code-block:: console
100

    
101
    $ kamaki -c nonexisting.cnf config set cloud.mytest.url https://accounts.example.com/identity/v2.0/
102

    
103
Try to connect
104

    
105
.. code-block:: console
106

    
107
    $ kamaki -c nonexisting.cnf user authenticate
108
    . No authentication token provided for cloud "mytest"
109
    . |  Set a token for cloud mytest:
110
    . |    kamaki config set cloud.mytest.token <token>
111

    
112
Set token to cloud "mytest"
113

    
114
.. code-block:: console
115

    
116
    $ kamaki -c nonexisting.cnf config set cloud.mytest.token myt35t70k3n==
117

    
118
Check that the file is created, everything is set up correctly and working
119

    
120
.. code-block:: console
121

    
122
    $ ls -l nonexisting.cnf
123
    . -rw======- 1 someuser someuser 491 Jun 17 13:39 nonexisting.cnf
124
    $ kamaki -c nonexisting.cnf config get cloud
125
    . cloud.mytest.url = https://accounts.example.com/identity/v2.0/
126
    . cloud.mytest.token = myt35t70k3n==
127
    $ kamaki -c nonexisting.cnf user autenticate
128
    . ...
129
    . user:          
130
    .     id:          s0me-3x4mp13-u53r-1d
131
    .     name:        Some User
132
    .     roles:      
133
    .          id:   1
134
    .          name: default
135
    .     roles_links:
136
    $
137

    
138
Failed or incomplete cloud configurations
139
-----------------------------------------
140

    
141
Now let kamaki use the default configuration ( ${HOME}/.kamakirc ). Let the old
142
token be `my0ld70k3n==` and let it be invalid.
143

    
144
Check for clouds and attempt to authenticate
145

    
146
.. code-block:: console
147

    
148
    $ kamaki config get cloud
149
    . cloud.default.token = my0ld70k3n==
150
    $ kamaki user authenticate
151
    . No authentication URL provided for cloud "mytest"
152
    . |  Set a URL for cloud mytest:
153
    . |    kamaki config set cloud.mytest.url <URL>
154
    $
155

    
156
Set a non-existing URL for cloud.default and attempt authentication
157

    
158
.. code-block:: console
159

    
160
    $ kamaki config set cloud.default.url https://nonexisting.example.com
161
    $ kamaki user authenticate
162
    . Failed while http-connecting to https://nonexisting.example.com
163
    $
164

    
165
Set the URL from the previous example and attempt authentication
166

    
167
.. code-block:: console
168

    
169
    $ kamaki config set cloud.default.url https://accounts.example.com/identity/v2.0/
170
    $ kamaki user authenticate
171
    . (401) Authorization failed for token gZH99orgkfYHmGksZKvHJw==
172
    . |  UNAUTHORIZED unauthorized (Invalid token)
173
    $
174

    
175
After some searching at the deployments UI, you found out that the URL/token
176
pair you need is::
177

    
178
    URL: https://accounts.deploymentexample.com/identity/v2.0
179
    TOKEN: myd3pl0ym3nt70k3n==
180

    
181
Set up the correct values and attempt authentication
182

    
183
.. code-block:: console
184

    
185
    $ kamaki config set cloud.default.url https://accounts.deploymentexample.com/identity/v2.0
186
    $ kamaki config set cloud.default.token myd3pl0ym3nt70k3n==
187
    $ kamaki user authenticate
188
    . ...
189
    . user:
190
    .     id: my-d3pl0ym3nt-u53r-1d
191
    .     name: Example Username
192
    $
193

    
194
Multiple clouds in a single configuration
195
-----------------------------------------
196

    
197
We now have two configurations::
198

    
199
    Configuration file: ${HOME}/.kamakirc    (default)
200
      Clouds:
201
        ALIAS: default
202
        URL: https://accounts.deploymentexample.com/identity/v2.0
203
        TOKEN: myd3pl0ym3nt70k3n==
204

    
205
    Copnfiguration file: nonexisting.cnf
206
      Clouds:
207
        ALIAS: mytest
208
        URL: https://accounts.example.com/identity/v2.0/
209
        TOKEN: myt35t70k3n==
210

    
211
As we can see, the default configuration handles only one cloud, aliased as
212
"default". We will add the second cloud as well.
213

    
214
.. code-block:: console
215

    
216
    $ kamaki config set cloud.mytest.url https://accounts.example.com/identity/v2.0/
217
    $ kamaki config set cloud.mytest.token myt35t70k3n==
218
    $
219

    
220
Check all clouds
221

    
222
.. code-block:: console
223

    
224
    $ kamaki config get cloud
225
    . cloud.default.url = https://accounts.deploymentexample.com/identity/v2.0/
226
    . cloud.default.token = myd3pl0ym3nt70k3n==
227
    . cloud.mytest.url = https://accounts.example.com/identity/v2.0/
228
    . cloud.mytest.token = myt35t70k3n==
229
    $
230

    
231
Check if kamaki knows one of the clouds to be the default
232

    
233
.. code-block:: console
234

    
235
    $ kamaki config get default_cloud
236
    . default
237
    $
238

    
239
Authenticate against different clouds
240

    
241
.. code-block:: console
242

    
243
    $ kamaki user authenticate
244
    . ...
245
    . <response from deploymentexample.com>
246
    . ...
247
    $ kamaki --cloud=mytest user authenticate
248
    . ...
249
    . <response from example.com>
250
    . ...
251
    $ kamaki --cloud=default user authenticate
252
    . ...
253
    . <response from deploymentexample.com, same as default behavior>
254
    . ...
255
    $ kamaki --cloud=nonexistingcloud user authenticate
256
    . No cloud "nonexistingcloud" is configured
257
    . |  To configure a new cloud "nonexistingcloud", find and set the
258
    . |  single authentication URL and token:
259
    . |    kamaki config set cloud.nonexistingcloud.url <URL>
260
    . |    kamaki config set cloud.nonexistingcloud.token <t0k3n>
261
    $
262

    
263
Confuse kamaki by removing the default_cloud option, set mytest as default
264

    
265
.. code-block:: console
266

    
267
    $ kamaki config delete default_cloud
268
    $ kamaki user authenticate
269
    . Found 2 clouds but none of them is set as default
270
    . |  Please, choose one of the following cloud names:
271
    . |  default, mytest
272
    . |  To set a default cloud:
273
    . |    kamaki config set default_cloud <cloud name>
274
    $ kamaki config set default_cloud mytest
275
    $ kamaki user authenticate
276
    . ...
277
    . <response from example.com>
278
    . ...
279
    $
280

    
281
`Question`: What will happen if the "default" cloud alias **and** the
282
default_cloud option are removed?
283

    
284
.. code-block:: console
285

    
286
    $ kamaki config delete cloud.default
287
    $ kamaki config delete default_cloud
288
    $ kamaki user authenticate
289
    . ...
290
    . <response from example.com>
291
    . ...
292
    $
293

    
294
`Answer`: kamaki doesn't have a default_cloud option, but there is only one
295
cloud configuration (`mytest`), therefore there is no ambiguity in resolving
296
the default cloud.
297

    
298
Multiple configurations
299
-----------------------
300

    
301
In the following example, a user wants to experiment with upload and download
302
for different number of threads. The plan is to contuct a set of tests with 3
303
threads at most and another one with 5. All experiments will be run against the
304
same Synnefo cloud (the "mytest" cloud from the previous example).
305

    
306
Let's create the 3-threaded configuration first
307

    
308
.. code-block:: console
309

    
310
    $ kamaki -c 3thread config set cloud.test.url https://accounts.example.com/identity/v2.0/
311
    $ kamaki -c 3thread config set cloud.test.token myt35t70k3n==
312
    $
313

    
314
Let's set the max_thread option to 3 as well as a seperate file for logs.
315

    
316
.. code-block:: console
317

    
318
    $ kamaki -c 3thread config set max_thread 3
319
    $ kamaki -c 3thread config log_file ./logs/kamaki.3threads.log
320
    $
321

    
322
Now, let's create the 5-threaded configuration by modifying a copy of 3thread
323

    
324
.. code-block:: console
325

    
326
    $ cp 3thread 5thread
327
    $ kamaki -c 5thread config set max_thread 5
328
    $ kamaki -c 5thread config log_file ./logs/kamaki.5threads.log
329
    $
330

    
331
Use kamaki to upload with 3 threads and 5 threads respectively
332

    
333
.. code-block:: console
334

    
335
    $ kamaki -c 3thread file upload testfiles/test1 testcontainer
336
    $ kamaki -c 5thread file upload testfiles/test1 testcontainer
337
    $