Revision a4986073 docs/setup.rst
| b/docs/setup.rst | ||
|---|---|---|
| 1 | 1 |
Setup |
| 2 | 2 |
===== |
| 3 | 3 |
|
| 4 |
Kamaki is easy to install from source or as a package. Some advanced or ui features |
|
| 5 |
are optional and can be installed separately. Kamaki behavior can be configured in |
|
| 6 |
the kamaki config file. |
|
| 4 |
Kamaki is easy to install from the official repository or with the pypi mechanism. |
|
| 7 | 5 |
|
| 8 | 6 |
Quick Setup |
| 9 | 7 |
----------- |
| ... | ... | |
| 14 | 12 |
To set up Kamaki for a specific Synnefo deployment, users need an |
| 15 | 13 |
**authentication URL** and a **user token**. Users should also pick an alias to |
| 16 | 14 |
name the cloud configuration. This can be any single word, e.g., "default", |
| 17 |
"mycloud"or whatever suits the user. |
|
| 15 |
"mycloud" or whatever suits the user.
|
|
| 18 | 16 |
|
| 19 | 17 |
.. code-block:: console |
| 20 | 18 |
|
| ... | ... | |
| 28 | 26 |
|
| 29 | 27 |
$ kamaki config set default_cloud <cloud alias> |
| 30 | 28 |
|
| 31 |
Since version 0.14, Synnefo supports a single authentication URL for retrieving
|
|
| 32 |
all API endpoints. This URL is retrieved from the Synnefo Web UI and should be
|
|
| 33 |
set as the cloud URL for kamaki. All service-specific URLs are retrieved and
|
|
| 34 |
handled automatically. Users of Synnefo clouds >=0.14 are advised against using
|
|
| 35 |
any service-specific URLs. |
|
| 29 |
The endpoints (URLs) for each service are resolved automatically from a single
|
|
| 30 |
URL. This mechanism works for Synnefo v0.14 deployments or later. The
|
|
| 31 |
authentication URL is retrieved from the Synnefo Web UI and should be set as
|
|
| 32 |
the cloud URL for kamaki. Users of Synnefo clouds >=0.14 are advised against
|
|
| 33 |
using any service-specific URLs.
|
|
| 36 | 34 |
|
| 37 |
Migrating from kamaki 0.8.X to 0.9 or better
|
|
| 38 |
-------------------------------------------- |
|
| 35 |
Migrating configuration file to latest version
|
|
| 36 |
----------------------------------------------
|
|
| 39 | 37 |
|
| 40 |
This section refers to running installations of kamaki version <= 0.8.X. To |
|
| 41 |
check the current kamaki version: |
|
| 38 |
Each new version of kamaki might demand some changes to the configuration file. |
|
| 39 |
Kamaki features a mechanism of automatic migration of the configration file to |
|
| 40 |
the latest version, which involves heuristics for guessing and translating the |
|
| 41 |
file. |
|
| 42 |
|
|
| 43 |
Quick migration |
|
| 44 |
^^^^^^^^^^^^^^^ |
|
| 45 |
|
|
| 46 |
The easiest way is to backup and remove the configuration file. The default |
|
| 47 |
configuration file location is '${HOME}/.kamakirc'.
|
|
| 48 |
|
|
| 49 |
To reset kamaki, a user needs the authentication URL and TOKEN: |
|
| 42 | 50 |
|
| 43 | 51 |
.. code-block:: console |
| 44 | 52 |
|
| 45 |
$ kamaki -V |
|
| 53 |
$ kamaki config set cloud.default.url URL |
|
| 54 |
$ kamaki config set cloud.default.token TOKEN |
|
| 55 |
|
|
| 56 |
After that, a new configuration file will be created. In most cases, this is |
|
| 57 |
enough, since kamaki automatically sets the correct options for every |
|
| 58 |
functionality. |
|
| 59 |
|
|
| 60 |
Automatic migration |
|
| 61 |
^^^^^^^^^^^^^^^^^^^ |
|
| 62 |
|
|
| 63 |
Another way is to let kamaki change the file automatically. Kamaki always |
|
| 64 |
inspects the configuration file and, if understood as an older version, it |
|
| 65 |
suggests some necessary modifications (user permission is required). |
|
| 46 | 66 |
|
| 47 |
Existing kamaki users should convert their configuration files to v9. To do |
|
| 48 |
that, kamaki 0.9 can inspect the configuration file and suggests a list of |
|
| 49 |
config file transformations, which are performed automatically after users' |
|
| 50 |
permission. This mechanism is invoked when an API-related kamaki command is |
|
| 51 |
fired. On example 2.1 we suggest using the `user authenticate` command to start |
|
| 52 |
the conversion mechanism for the configuration file. |
|
| 67 |
On example 2.1 we suggest using the `user info` command to invoke the migration |
|
| 68 |
mechanism. |
|
| 53 | 69 |
|
| 54 | 70 |
.. code-block:: console |
| 55 | 71 |
:emphasize-lines: 1 |
| 56 | 72 |
|
| 57 | 73 |
Example 2.1: Convert config file while authenticating user "exampleuser" |
| 58 | 74 |
|
| 59 |
$ kamaki user authenticate
|
|
| 60 |
Config file format version >= 9.0 is required
|
|
| 75 |
$ kamaki user info
|
|
| 76 |
Config file format version >= 0.12 is required
|
|
| 61 | 77 |
Configuration file: "/home/exampleuser/.kamakirc" |
| 62 | 78 |
but kamaki can fix this: |
| 63 | 79 |
Calculating changes while preserving information |
| 64 | 80 |
... rescue global.token => cloud.default.token |
| 65 | 81 |
... rescue config.cli => global.config_cli |
| 66 | 82 |
... rescue history.file => global.history_file |
| 83 |
... change global.network_cli value: `cyclades` => `network` |
|
| 67 | 84 |
... DONE |
| 68 | 85 |
The following information will NOT be preserved: |
| 69 | 86 |
global.account = |
| ... | ... | |
| 74 | 91 |
file.url = https://pithos.okeanos.grnet.gr/v1 |
| 75 | 92 |
image.url = https://cyclades.okeanos.grnet.gr/plankton |
| 76 | 93 |
|
| 77 |
Kamaki is ready to convert the config file to version 9.0
|
|
| 94 |
Kamaki is ready to convert the config file to version 0.12
|
|
| 78 | 95 |
Overwrite file /home/exampleuser/.kamakirc ? [Y, y] |
| 79 | 96 |
|
| 80 | 97 |
At this point, we should examine the kamaki output. Most options are renamed to |
| ... | ... | |
| 82 | 99 |
|
| 83 | 100 |
Lets take a look at the discarded options: |
| 84 | 101 |
|
| 85 |
* `global.account` and `user.account` are not used anymore.
|
|
| 102 |
* `global.account` and `user.account` are not used since version 0.9
|
|
| 86 | 103 |
The same is true for the synonyms `store.account` and `pithos.account`. |
| 87 | 104 |
These options were used to explicitly set a user account or uuid to a |
| 88 | 105 |
pithos call. In the latest Synnefo version (>= 0.14), these features are |
| ... | ... | |
| 94 | 111 |
correct option after the conversion is complete (Example 2.2). |
| 95 | 112 |
|
| 96 | 113 |
Users should press *y* when they are ready, which will cause the default config |
| 97 |
file to be modified so that it conforms with the latest version.
|
|
| 114 |
file to be modified. |
|
| 98 | 115 |
|
| 99 | 116 |
.. code-block:: console |
| 100 | 117 |
:emphasize-lines: 1 |
| ... | ... | |
| 178 | 195 |
$ |
| 179 | 196 |
|
| 180 | 197 |
Now kamaki can use any of these clouds, with the **- - cloud** attribute. If |
| 181 |
the **- - cloud** option is ommited, kamaki will query the `default` cloud.
|
|
| 198 |
the **- - cloud** option is omitted, kamaki will query the `default` cloud.
|
|
| 182 | 199 |
|
| 183 |
One way to test this, is the `user athenticate` command:
|
|
| 200 |
One way to test this, is the `user info` command:
|
|
| 184 | 201 |
|
| 185 | 202 |
.. code-block:: console |
| 186 | 203 |
|
| 187 |
$ kamaki --cloud=devel user authenticate
|
|
| 204 |
$ kamaki --cloud=devel user info
|
|
| 188 | 205 |
... |
| 189 |
user : |
|
| 190 |
id : 725d5de4-1bab-45ac-9e98-38a60a8c543c |
|
| 191 |
name : Devel User |
|
| 206 |
id : 725d5de4-1bab-45ac-9e98-38a60a8c543c |
|
| 207 |
name : Devel User |
|
| 192 | 208 |
$ |
| 193 |
$ kamaki --cloud=testing user authenticate
|
|
| 209 |
$ kamaki --cloud=testing user info
|
|
| 194 | 210 |
... |
| 195 |
user : |
|
| 196 |
id : 4ed5d527-bab1-ca54-89e9-c345c8a06a83 |
|
| 197 |
name : Testing User |
|
| 211 |
id : 4ed5d527-bab1-ca54-89e9-c345c8a06a83 |
|
| 212 |
name : Testing User |
|
| 198 | 213 |
$ |
| 199 |
$ kamaki --cloud=default user authenticate
|
|
| 214 |
$ kamaki --cloud=default user info
|
|
| 200 | 215 |
... |
| 201 |
user : |
|
| 202 |
id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473 |
|
| 203 |
name : Default User |
|
| 216 |
id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473 |
|
| 217 |
name : Default User |
|
| 204 | 218 |
$ |
| 205 |
$ kamaki user authenticate
|
|
| 219 |
$ kamaki user info
|
|
| 206 | 220 |
... |
| 207 |
user : |
|
| 208 |
id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473 |
|
| 209 |
name : Default User |
|
| 221 |
id : 4d3f4u17-u53r-4u7h-451n-4u7h3n7ic473 |
|
| 222 |
name : Default User |
|
| 210 | 223 |
$ |
| 211 | 224 |
|
| 212 |
In interactive cell, the cloud can be picked when invoking the shell, with |
|
| 213 |
the **- - cloud** option. |
|
| 225 |
In interactive cell, the cloud option should be passed when calling the shell. |
|
| 214 | 226 |
|
| 215 | 227 |
.. code-block:: console |
| 216 | 228 |
|
| 217 |
$ kamaki --cloud=devel |
|
| 229 |
$ kamaki-shell --cloud=devel
|
|
| 218 | 230 |
kamaki v0.10 - Interactive Shell |
| 219 | 231 |
|
| 220 | 232 |
/exit terminate kamaki |
| ... | ... | |
| 262 | 274 |
mandatory options (URL, token) and some advanced / optional (e.g., |
| 263 | 275 |
service-specific URL overrides or versions) |
| 264 | 276 |
|
| 265 |
Kamaki comes with preset default values to all kamaki-releated configuration
|
|
| 277 |
Kamaki comes with preset default values to all kamaki-related configuration |
|
| 266 | 278 |
options. Cloud-related information is not included in presets and should be |
| 267 | 279 |
provided by the user. Kamaki-related options can also be modified. |
| 268 | 280 |
|
| ... | ... | |
| 307 | 319 |
Kamaki config command allows users to see and manage all configuration options. |
| 308 | 320 |
|
| 309 | 321 |
* kamaki config list |
| 310 |
lists all configuration options of a kamaki setup
|
|
| 322 |
lists all configuration options |
|
| 311 | 323 |
|
| 312 |
* kamaki config get <group.option> |
|
| 313 |
show the value of a specific configuration option. Options must be of the |
|
| 314 |
form *group.option*. A single *option* is equivalent to *global.option*, |
|
| 315 |
with the exception of the term *cloud* (see bellow) |
|
| 324 |
* kamaki config get <group>[.option] | <option> |
|
| 325 |
show the value of a configuration option.A single *option* is equivalent to |
|
| 326 |
*global.option*, except if this group exist (*global*, *cloud*) |
|
| 316 | 327 |
|
| 317 | 328 |
* kamaki config set <group.option> <value> |
| 318 | 329 |
set the group.option to value. If no group is given, it defaults to |
| 319 | 330 |
*global*. |
| 320 | 331 |
|
| 321 |
* kamaki config delete <group.option> |
|
| 322 |
delete a configuration option. If no group is given, it defaults to |
|
| 323 |
*global* |
|
| 332 |
* kamaki config delete <group>[.option] | <option> |
|
| 333 |
delete a configuration option, group, or global option. |
|
| 324 | 334 |
|
| 325 | 335 |
The above commands cause option values to be permanently stored in the Kamaki configuration file. |
| 326 | 336 |
|
| ... | ... | |
| 370 | 380 |
The configuration file is a simple text file that can be created by the user. |
| 371 | 381 |
|
| 372 | 382 |
.. note:: users of kamaki < 0.9 can use the latest versions to automatically |
| 373 |
convert their old configuration files to the new configuration file(s). |
|
| 374 |
See `these instructions <#migrating-from-kamaki-0-8-x-to-0-9-or-better>`_
|
|
| 383 |
convert their old configuration files to the new configuration file(s). See
|
|
| 384 |
`these instructions <#mMigrating-configuration-file-to-latest-version>`_
|
|
| 375 | 385 |
for more. |
| 376 | 386 |
|
| 377 | 387 |
A simple way to create the configuration file is to set a configuration option |
| ... | ... | |
| 379 | 389 |
|
| 380 | 390 |
.. code-block:: console |
| 381 | 391 |
|
| 382 |
$ kamaki config set global.log_file /home/exampleuser/logs/kamaki.log
|
|
| 392 |
$ kamaki config set log_file /home/exampleuser/logs/kamaki.log |
|
| 383 | 393 |
|
| 384 | 394 |
In the above example, if the kamaki configuration file does not exist, it will |
| 385 | 395 |
be created with all the default values plus the *global.log_file* option set to |
| ... | ... | |
| 542 | 552 |
$ kamaki livetest cyclades create_server |
| 543 | 553 |
|
| 544 | 554 |
|
| 545 |
The unit testing system
|
|
| 546 |
"""""""""""""""""""""""
|
|
| 555 |
The unit tests
|
|
| 556 |
"""""""""""""" |
|
| 547 | 557 |
|
| 548 |
Kamaki container a set of finegrained unit tests for the kamaki.clients
|
|
| 549 |
package. This set is not used when kamaki is running. Instead, it is aimed to
|
|
| 550 |
developers who debug or extent kamaki. For more information, check the
|
|
| 558 |
Kamaki features a set of unit tests for the kamaki.clients package. This set is
|
|
| 559 |
not used when kamaki is running. Instead, it is aimed to developers who debug
|
|
| 560 |
or extent kamaki. For more information, check the |
|
| 551 | 561 |
`Going Agile <developers/extending-clients-api.html#going-agile>`_ entry at the |
| 552 | 562 |
`developers section <developers/extending-clients-api.html>`_. |
Also available in: Unified diff