Commit 56d361de authored by Stavros Sachtouris's avatar Stavros Sachtouris
Browse files

Merge branch 'develop' into feature-floating-ips

parents 03033b54 c088076b
......@@ -4,7 +4,16 @@ Bug Fixes:
Changes:
- Adjust astakos authenticate to the new url scheme of synnefo >= 0.14 [#3832, #3874]
as a side effect, some renamings in astakos.AstakosClient:
info --> user_info, user --> list_users
Features:
- Implement an optional astakosclient cli exposed as "astakos", with the following methods:
authenticate, uuid, username, quotas, service uuid/username/quotas
- Add some astakos/keystone kamaki-lib api calls [#3874], used to access astakos-calls cache:
get_services, get_service_details, get_service_endpoints
- Implement floating ip methods for compute and cyclades clients [#3862]
ComputeRestClient: floating_ip_pools_get, floating_ips_get/post/delete
CycladesRestClient: floating_ip_pools_get, floating_ips_get/post/delete
......@@ -12,4 +21,5 @@ Features:
alloc/get_delete_floating_ip
CycladesClient: get_floating_ip_pools, get_floating_ips,
alloc/get_delete_floating_ip, dis/assoc_floating_ip_to_server
- Add Examples to documentation
This document describes changes and steps to upgrade from kamaki 0.8.X to kamaki 0.9
This document describes changes and steps to upgrade from kamaki 0.9.X to
kamaki 0.10
README
=======
./kamaki is a simple, yet intuitive, command-line tool/interactive shell for managing clouds.
./kamaki is a multipurpose, interactive command-line tool and also a client
development API for managing clouds.
As a development API, it is an initial implementation of the Synnefo API
( http://www.synnefo.org cloud management software extends OpenStack ), while
preserving compatibility with the OpenStack API.
It is an initial implementation of the OpenStack Compute API v1.1, with custom
extensions specific to the Synnefo IaaS (www.synnefo.org) cloud management software.
Configuration
=============
Since kamaki 0.9, the format of the configuration file has changed. In this
scenario, we have an old configuration file at ${HOME}/.kamakirc that we need
to convert. We also create a new one from scratch. In both cases, we have to
set up one or more clouds in a single configuration and we also examine a case
of multiple configurations.
Convert old configuration file
------------------------------
First, back up the old file
.. code-block:: console
$ cp ~/.kamakirc ~/backups/.kamakirc
Now, let kamaki do the conversion
.. code-block:: console
$ kamaki user authenticate
. Config file format version >= 9.0 is required
. Configuration file: /home/someuser/.kamakirc
. Attempting to fix this:
. Calculating changes while preserving information
. ... rescue global.token => cloud.default.token
. ... rescue user.cli => global.user_cli
. ... rescue network.cli => global.network_cli
. ... rescue file.cli => global.file_cli
. ... rescue flavor.cli => global.flavor_cli
. ... rescue config.cli => global.config_cli
. ... rescue image.cli => global.image_cli
. ... rescue server.cli => global.server_cli
. ... rescue history.file => global.history_file
. ... rescue history.cli => global.history_cli
. ... DONE
. The following information will NOT be preserved:
. global.account = AccountName
. user.url = https://accounts.example.com
. user.account = UserAccountName
. compute.url = https://cyclades.example.com/api/v1.1
. file.url = https://pithos.example.com/v1
. image.url = https://cyclades.example.com/plankton
. store.account = OldForgotenAccountName
. Kamaki is ready to convert the config file
. Create (overwrite) file .kamakirc.okeanos ? [y/N]
.
<y is pressed>
.
. No cloud "default" is configured
. | To configure a new cloud "default", find and set the
. | single authentication URL and token:
. | kamaki config set cloud.default.url <URL>
. | kamaki config set cloud.default.token <t0k3n>
$
.. warning:: A new cloud configuration with the name "default" is created. The
global token that was set in the old configuration file, is preserved as
the token of the "default" cloud. Still, kamaki needs a url for the cloud
and it encourages you to reset the token as well.
.. note:: Some options are discarded. Among them, are the service urls, like
user.url, compute.url, image.url and file.url . These settings are obsolete
since Synnefo 0.14 and kamaki 0.9 so you do not need to recover them. The
same is true for user accounts (retrieved automatically)
.. note:: You can safely remove the global.XXX_cli options from kamaki
configuration file. Kamaki can automatically resolve the default values for
these internal options. These options are usefull when overloading the
default command behaviors, but are not needed otherwise.
Attempt to create a new configuration
-------------------------------------
Ask kamaki to load from a non-existing configuration file
.. code-block:: console
$ kamaki -c nonexisting.cnf user authenticate
. No cloud is configured
. | To configure a new cloud "<cloud name>", find and set the
. | single authentication URL and token:
. | kamaki config set cloud.<cloud name>.url <URL>
. | kamaki config set cloud.<cloud name>.token <t0k3n>
$ ls -l nonexisting.cnf
. ls: cannot access nonexisting.cnf: No such file or directory
$
.. note:: configuration file is not created, but it will be when we set the
first configuration value in it, as shown in the following subsection.
Configure a cloud and create a new configuration
------------------------------------------------
Set the URL for new cloud "mytest"
.. code-block:: console
$ kamaki -c nonexisting.cnf config set cloud.mytest.url https://accounts.example.com/identity/v2.0/
Try to connect
.. code-block:: console
$ kamaki -c nonexisting.cnf user authenticate
. No authentication token provided for cloud "mytest"
. | Set a token for cloud mytest:
. | kamaki config set cloud.mytest.token <token>
Set token to cloud "mytest"
.. code-block:: console
$ kamaki -c nonexisting.cnf config set cloud.mytest.token myt35t70k3n==
Check that the file is created, everything is set up correctly and working
.. code-block:: console
$ ls -l nonexisting.cnf
. -rw======- 1 someuser someuser 491 Jun 17 13:39 nonexisting.cnf
$ kamaki -c nonexisting.cnf config get cloud
. cloud.mytest.url = https://accounts.example.com/identity/v2.0/
. cloud.mytest.token = myt35t70k3n==
$ kamaki -c nonexisting.cnf user autenticate
. ...
. user:
. id: s0me-3x4mp13-u53r-1d
. name: Some User
. roles:
. id: 1
. name: default
. roles_links:
$
Failed or incomplete cloud configurations
-----------------------------------------
Now let kamaki use the default configuration ( ${HOME}/.kamakirc ). Let the old
token be `my0ld70k3n==` and let it be invalid.
Check for clouds and attempt to authenticate
.. code-block:: console
$ kamaki config get cloud
. cloud.default.token = my0ld70k3n==
$ kamaki user authenticate
. No authentication URL provided for cloud "mytest"
. | Set a URL for cloud mytest:
. | kamaki config set cloud.mytest.url <URL>
$
Set a non-existing URL for cloud.default and attempt authentication
.. code-block:: console
$ kamaki config set cloud.default.url https://nonexisting.example.com
$ kamaki user authenticate
. Failed while http-connecting to https://nonexisting.example.com
$
Set the URL from the previous example and attempt authentication
.. code-block:: console
$ kamaki config set cloud.default.url https://accounts.example.com/identity/v2.0/
$ kamaki user authenticate
. (401) Authorization failed for token gZH99orgkfYHmGksZKvHJw==
. | UNAUTHORIZED unauthorized (Invalid token)
$
After some searching at the deployments UI, you found out that the URL/token
pair you need is::
URL: https://accounts.deploymentexample.com/identity/v2.0
TOKEN: myd3pl0ym3nt70k3n==
Set up the correct values and attempt authentication
.. code-block:: console
$ kamaki config set cloud.default.url https://accounts.deploymentexample.com/identity/v2.0
$ kamaki config set cloud.default.token myd3pl0ym3nt70k3n==
$ kamaki user authenticate
. ...
. user:
. id: my-d3pl0ym3nt-u53r-1d
. name: Example Username
$
Multiple clouds in a single configuration
-----------------------------------------
We now have two configurations::
Configuration file: ${HOME}/.kamakirc (default)
Clouds:
ALIAS: default
URL: https://accounts.deploymentexample.com/identity/v2.0
TOKEN: myd3pl0ym3nt70k3n==
Copnfiguration file: nonexisting.cnf
Clouds:
ALIAS: mytest
URL: https://accounts.example.com/identity/v2.0/
TOKEN: myt35t70k3n==
As we can see, the default configuration handles only one cloud, aliased as
"default". We will add the second cloud as well.
.. code-block:: console
$ kamaki config set cloud.mytest.url https://accounts.example.com/identity/v2.0/
$ kamaki config set cloud.mytest.token myt35t70k3n==
$
Check all clouds
.. code-block:: console
$ kamaki config get cloud
. cloud.default.url = https://accounts.deploymentexample.com/identity/v2.0/
. cloud.default.token = myd3pl0ym3nt70k3n==
. cloud.mytest.url = https://accounts.example.com/identity/v2.0/
. cloud.mytest.token = myt35t70k3n==
$
Check if kamaki knows one of the clouds to be the default
.. code-block:: console
$ kamaki config get default_cloud
. default
$
Authenticate against different clouds
.. code-block:: console
$ kamaki user authenticate
. ...
. <response from deploymentexample.com>
. ...
$ kamaki ==cloud=mytest user authenticate
. ...
. <response from example.com>
. ...
$ kamaki ==cloud=default user authenticate
. ...
. <response from deploymentexample.com, same as default behavior>
. ...
$ kamaki ==cloud=nonexistingcloud user authenticate
. No cloud "nonexistingcloud" is configured
. | To configure a new cloud "nonexistingcloud", find and set the
. | single authentication URL and token:
. | kamaki config set cloud.nonexistingcloud.url <URL>
. | kamaki config set cloud.nonexistingcloud.token <t0k3n>
$
Confuse kamaki by removing the default_cloud option, set mytest as default
.. code-block:: console
$ kamaki config delete default_cloud
$ kamaki user authenticate
. Found 2 clouds but none of them is set as default
. | Please, choose one of the following cloud names:
. | default, mytest
. | To set a default cloud:
. | kamaki config set default_cloud <cloud name>
$ kamaki config set default_cloud mytest
$ kamaki user authenticate
. ...
. <response from example.com>
. ...
$
`Question`: What will happen if the "default" cloud alias **and** the
default_cloud option are removed?
.. code-block:: console
$ kamaki config delete cloud.default
$ kamaki config delete default_cloud
$ kamaki user authenticate
. ...
. <response from example.com>
. ...
$
`Answer`: kamaki doesn't have a default_cloud option, but there is only one
cloud configuration (`mytest`), therefore there is no ambiguity in resolving
the default cloud.
Multiple configurations
-----------------------
In the following example, a user wants to experiment with upload and download
for different number of threads. The plan is to contuct a set of tests with 3
threads at most and another one with 5. All experiments will be run against the
same Synnefo cloud (the "mytest" cloud from the previous example).
Let's create the 3-threaded configuration first
.. code-block:: console
$ kamaki -c 3thread config set cloud.test.url https://accounts.example.com/identity/v2.0/
$ kamaki -c 3thread config set cloud.test.token myt35t70k3n==
$
Let's set the max_thread option to 3 as well as a seperate file for logs.
.. code-block:: console
$ kamaki -c 3thread config set max_thread 3
$ kamaki -c 3thread config log_file ./logs/kamaki.3threads.log
$
Now, let's create the 5-threaded configuration by modifying a copy of 3thread
.. code-block:: console
$ cp 3thread 5thread
$ kamaki -c 5thread config set max_thread 5
$ kamaki -c 5thread config log_file ./logs/kamaki.5threads.log
$
Use kamaki to upload with 3 threads and 5 threads respectively
.. code-block:: console
$ kamaki -c 3thread file upload testfiles/test1 testcontainer
$ kamaki -c 5thread file upload testfiles/test1 testcontainer
$
Image registration
==================
In Synnefo, an image is loaded as a file to the storage service (Pithos+), and
then is registered to the image service (Plankton). The image location at the
storage server is unique through out a deployment and also necessary for the
image to exist.
The image location format::
pithos://<user id>/<container>/<object path>
e.g.:
pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump
Register an image
-----------------
Let the image file `debian_base3.diskdump` be a debian image located at the
current directory.
Upload the image to container `pithos`
.. code-block:: console
[kamaki]: file upload debian_base3.diskdump pithos
Uploading /home/someuser/debian_base3.diskdump --> pithos:debian_base3.diskdump
Done
[kamaki]:
Register the image object with the name 'Debian Base Alpha'
.. code-block:: console
[kamaki]: image register 'Debian Base Alpha' pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump
checksum: 3cb03556ec971f...e8dd6190443b560cb7
container-format: bare
created-at: 2013-06-19 08:00:22
deleted-at:
disk-format: diskdump
id: 7h1rd-1m4g3-1d
is-public: False
location: pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump
name: Debian Base Alpha
owner: s0m3-u53r-1d
properties:
size: 903471104
status: available
updated-at: 2013-06-19 08:01:00
Metadata file uploaded as pithos:debian_base3.diskdump.meta (version 1352)
[kamaki]:
.. note:: The `image register` command automatically create a meta file and
uploads it to the same location as the image. The meta file can be
downloaded and reused for more image registrations.
Read the metafile
.. code-block:: console
[kamaki]: file cat pithos:debian_base3.diskdump
{
"status": "available",
"name": "Debian Base Gama",
"checksum": "3cb03556ec971f...e8dd6190443b560cb7",
"id": "7h1rd-1m4g3-1d2",
"updated-at": "2013-06-19 08:01:00",
"created-at": "2013-06-19 08:00:22",
"properties": {},
"location": "pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump",
"is-public": "False",
"owner": "s0m3-u53r-1d",
"disk-format": "diskdump",
"size": "903471104",
"deleted-at": "",
"container-format": "bare"
}
[kamaki]:
Images registered by me
-----------------------
List all images, then list only images owned by the user with id s0m3-u53r-1d
.. code-block:: console
[kamaki]: image list
f1r57-1m4g3-1d Debian Base Alpha
container_format: bare
disk_format: diskdump
size: 474066944
status: available
53c0nd-1m4g3-1d Beta Debian Base
container_format: bare
disk_format: diskdump
size: 474066944
status: available
7h1rd-1m4g3-1d Debian Base Gama
container_format: bare
disk_format: diskdump
size: 474066944
status: available
[kamaki]: image list --owner=s0m3-u53r-1d
7h1rd-1m4g3-1d Debian Base Gama
container_format: bare
disk_format: diskdump
size: 474066944
status: available
[kamaki]:
.. note:: To get the current user id, use `user authenticate` in kamaki
Unregister an image
-------------------
An image can be unregistered by its image id, but only if the current user is
also the image owner. In this example, there is only one image owned by current
user.
Unregister image owned by current user
.. code-block:: console
[kamaki]: image unregister 7h1rd-1m4g3-1d
[kamaki]:
Check if the image is deleted
.. code-block:: console
[kamaki]: image list --owner=s0m3-u53r-1d
[kamaki]:
Attempt to unregister an image of another user
.. code-block:: console
[kamaki]: image unregister f1r57-1m4g3-1d
(403) FORBIDDEN forbidden ()
[kamaki]:
Register with properties
------------------------
The image will be registered again, but with some custom properties::
OS: Linux
user: someuser
These properties can be added freely by the user, and they have no significance
for the image server, but they could be used to help using the image more
efficiently.
Attempt to register with properties
.. code-block:: console
[kamaki]: image register 'Debian Base Gama' pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump -p OS=Linux -p user=someuser
Metadata file pithos:debian_base3.diskdump.meta already exists
[kamaki]:
It's true that the metafile is already there, but we can override it (**-f**)
.. code-block:: console
[kamaki]: image register -f 'Debian Base Gama' pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump -p OS=Linux -p user=someuser
[kamaki]:
Register with a meta file
-------------------------
Download the meta file of the image (it was uploaded recently)
.. code-block:: console
[kamaki]: file download pithos:debian_base3.diskdump.meta
Downloading pithos:debian_base3.diskdump.meta --> /home/someuser/debian_base3.diskdump.meta
Done
[kamaki]:
The metadata file can be edited. Let's edit the file, by adding properties::
OS: Linux
user: root
The resulting file will look like this:
.. code-block:: javascript
{
"status": "available",
"name": "Debian Base Gama",
"checksum": "3cb03556ec971f...e8dd6190443b560cb7",
"id": "7h1rd-1m4g3-1d2",
"updated-at": "2013-06-19 08:01:00",
"created-at": "2013-06-19 08:00:22",
"properties": {
"OS": "Linux",
"USER": "root"
},
"location": "pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump",
"is-public": "False",
"owner": "s0m3-u53r-1d",
"disk-format": "diskdump",
"size": "903471104",
"deleted-at": "",
"container-format": "bare"
}
.. warning:: make sure the file is in a valid json format, otherwise image
register will fail
In the following registration, a different name will be used for the image.
Register the image (don't forget the -f parameter, to override the metafile).
.. code-block:: console
[kamaki]: image register -f 'Debian Base Delta' pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump --metafile=debian_base3.diskdump.meta
checksum: 3cb03556ec971f...e8dd6190443b560cb7
container-format: bare
created-at: 2013-06-19 08:00:22
deleted-at:
disk-format: diskdump
id: 7h1rd-1m4g3-1d
is-public: False
location: pithos://s0m3-u53r-1d/pithos/debian_base3.diskdump
name: Debian Base Delta
owner: s0m3-u53r-1d
properties:
OS: Linux
USER: root
size: 903471104
status: available
updated-at: 2013-06-19 08:01:00
Metadata file uploaded as pithos:debian_base3.diskdump.meta (version 1359)
[kamaki]:
Reregistration: priorities and overrides
----------------------------------------
Let's review the examples presented above::
- Register an image with name `Debian Base Gama`
- Unregister the image
- Register a new image of the uploaded image object, with custom properties
- Reregister the image with a meta file and modified properties and name
**The image id is related to the image object**
Although the image was unregistered and reregistered, the image id, that is
produced automatically at the server side, was the same. This is due to the
fact that image ids are 1 to 1 related to image objects uploaded to Pithos+