Commit 1f969912 authored by Stavros Sachtouris's avatar Stavros Sachtouris

Update docs and Changelog for get_endpoint_url

Closes #2
parent 62d6e983
......@@ -23,4 +23,5 @@ Features:
- Datetime support in DateArgument
- Resources can be reassigned to projects
- Update account API commands to reflect changes in synnefo 0.16
- Implement a get_endpoint_url method and use it
......@@ -2,8 +2,8 @@ Creating applications with kamaki API
=====================================
Kamaki features a clients API for building third-party client applications that
communicate with Synnefo and (in most cases) OpenStack cloud services. The package is
called *kamaki.clients* and serves as a library.
communicate with Synnefo and (in most cases) OpenStack cloud services. The
package is called *kamaki.clients* and serves as a library.
A showcase of an application built on *kamaki.clients* is *kamaki.cli*, the
command line interface of kamaki.
......@@ -46,32 +46,28 @@ respectively.
Using endpoints to get the authentication url
---------------------------------------------
In OpenStack, each service (e.g., `compute`, `object-store`, etc.) has a number
of `endpoints`. These `endpoints` are URIs which are used by kamaki as prefixes
to form the corresponding API calls. Client applications need just one of these
`endpoints`, namely the `publicURL` (also referred to as `publicURL` in the
internals of kamaki client libraries).
Each client is initialized with a URL called ``the endpoint URL``. To get one,
an AstakosClient should be initialized first. The AstakosClient is an Astakos
client class. Astakos implements the OpenStack Identity API and the Synnefo
Account API. The astakos library features a simple call (``get_endpoint_url``)
which returns the initialization URL for a given service type (e.g., 'compute',
'object-store', 'network', 'image')
Here are instructions for getting the publicURL for a service::
Kamaki features a library of clients. Each client abides to a service type,
stored in ``service_type`` attribute in the client class.
1. From the deployment UI get the AUTHENTICATION_URL and TOKEN
(Example 1.2)
2. Use them to instantiate an AstakosClient
(Example 1.2)
3. Use AstakosClient instance to get endpoints for the service of interest
(Example 1.3)
4. The 'publicURL' endpoint is the URL we are looking for
(Example 1.3)
The values of ``service_type`` for each client are shown bellow::
The AstakosClient is a client for the Synnefo/Astakos server. Synnefo/Astakos
is an identity server that implements the OpenStack identity API and it
can be used to get the URLs needed for API calls URL construction. The astakos
kamaki client library simplifies this process.
storage.StorageClient, pithos.PithosClient --> object-store
compute.ComputeClient, cyclades.CycladesClient --> compute
network.NetworkClient, cyclades.CycladesNetworkClient --> network
image.ImageClient --> image
astakos.AstakosClient --> identity
Let's review with a few examples.
First, an astakos client must be initialized (Example 1.2). An
AUTHENTICATION_URL and a TOKEN can be acquired from the Synnefo deployment UI.
AUTHENTICATION_URL and a TOKEN can be acquired from the service web UI.
.. code-block:: python
:emphasize-lines: 1
......@@ -82,32 +78,19 @@ AUTHENTICATION_URL and a TOKEN can be acquired from the Synnefo deployment UI.
astakos = AstakosClient(AUTHENTICATION_URL, TOKEN)
Next, the astakos client can be used to retrieve the `publicURL` values for the
services of interest. In this case (Example 1.3) they are *cyclades* (compute)
and *pithos* (object-store). A number of endpoints is related to each service,
but kamaki clients only need the ones labeled ``publicURL``.
Next, the astakos client can be used to retrieve the URL for each service. In
this case (Example 1.3) we need a *compute* and an *object-store* URL. They
will be used to initialize a *cyclades* and a *pithos* client respectively.
.. code-block:: python
:emphasize-lines: 1
Example 1.3: Retrieve cyclades and pithos publicURL values
cyclades_endpoints = astakos.get_service_endpoints('compute')
cyclades_URL = cyclades_endpoints['publicURL']
pithos_endpoints = astakos.get_service_endpoints('object-store')
pithos_URL = pithos_endpoints['publicURL']
Example 1.3: Retrieve cyclades and pithos URLs
The ``get_service_endpoints`` method is called with the service name as an
argument. Here are the service names for the kamaki clients::
storage.StorageClient, pithos.PithosClient --> object-store
compute.ComputeClient, cyclades.CycladesClient --> compute
network.NetworkClient, cyclades.CycladesNetworkClient --> network
image.ImageClient --> image
astakos.AstakosClient --> identity, account
cyclades_URL = astakos.get_endpoint_url(CycladesClient.service_type)
pithos_URL = astakos.get_endpoint_url(PithosClent.service_type)
For example
It's time to initialize both clients.
.. code-block:: python
:emphasize-lines: 1
......@@ -199,8 +182,7 @@ The following example concatenates examples 1.1 to 1.4 plus error handling
raise
try:
cyclades_endpoints = astakos.get_service_endpoints('compute')
CYCLADES_URL = cyclades_endpoints['publicURL']
CYCLADES_URL = astakos.get_endpoint_url(CycladesClient.service_type)
except ClientError:
print('Failed to get endpoints for cyclades')
......@@ -210,8 +192,7 @@ The following example concatenates examples 1.1 to 1.4 plus error handling
print('Failed to initialize Cyclades client')
try:
pithos_endpoints = astakos.get_service_endpoints('object-store')
PITHOS_URL = pithos_endpoints['publicURL']
PITHOS_URL = astakos.get_endpoint_url(PithosClient.service_type)
except ClientError:
print('Failed to get endpoints for pithos')
......@@ -257,7 +238,7 @@ Batch-create servers
astakos = AstakosClient(AUTHENTICATION_URL, TOKEN)
CYCLADES_URL = astakos.get_service_endpoints('compute')['publicURL']
CYCLADES_URL = astakos.get_endpoint_url(CycladesClient.service_type)
cyclades = CycladesClient(CYCLADES_URL, TOKEN)
# (name, flavor-id, image-id)
......@@ -300,11 +281,11 @@ Register a banch of pre-uploaded images
astakos = AstakosClient(AUTHENTICATION_URL, TOKEN)
USER_UUID = astakos.user_info['id']
PITHOS_URL = astakos.get_service_endpoints('object-store')['publicURL']
PITHOS_URL = astakos.get_endpoint_url(PithosClient.service_type)
pithos = PithosClient(
PITHOS_URL, TOKEN, account=USER_UUID, container=IMAGE_CONTAINER)
IMAGE_URL = astakos.get_service_endpoints('image')['publicURL']
IMAGE_URL = astakos.get_endpoint_url(ImageClient.service_type)
plankton = ImageClient(IMAGE_URL, TOKEN)
for img in pithos.list_objects():
......@@ -336,12 +317,12 @@ Two servers and a private network
astakos = AstakosClient(AUTHENTICATION_URL, TOKEN)
NETWORK_URL = astakos.get_service_endpoints('network')['publicURL']
NETWORK_URL = astakos.get_endpoint_url(CycladesNetworkClient.service_type)
network = CycladesNetworkClient(NETWORK_URL, TOKEN)
net = network.create_network(type='MAC_FILTERED', name='My private network')
CYCLADES_URL = astakos.get_service_endpoints('compute')['publicURL']
CYCLADES_URL = astakos.get_endpoint_url(CycladesClient.service_type)
cyclades = CycladesClient(CYCLADES_URL, TOKEN)
FLAVOR_ID = 'put your flavor id here'
......
......@@ -82,18 +82,14 @@ This is the plan:
AUTH_URL, AUTH_TOKEN))
raise
# 3. Get the endpoints
# Identity, Account --> astakos
# Compute, Network --> cyclades
# Object-store --> pithos
# Image --> plankton
# 3. Get the endpoint URLs
try:
endpoints = dict(
astakos=AUTH_URL,
cyclades=auth.get_service_endpoints('compute')['publicURL'],
network=auth.get_service_endpoints('network')['publicURL'],
pithos=auth.get_service_endpoints('object-store')['publicURL'],
plankton=auth.get_service_endpoints('image')['publicURL']
cyclades=auth.get_endpoint_url(CycladesClient.service_type),
network=auth.get_endpoint_url(CycladesNetworkClient.service_type),
pithos=auth.get_endpoint_url(PithosClient.service_type),
plankton=auth.get_endpoint_url(ImageClient.service_type)
)
user_id = auth.user_info['id']
except ClientError:
......@@ -641,11 +637,13 @@ logging more. We also added some command line interaction candy.
print(' Get the endpoints')
try:
endpoints = dict(
astakos=auth.get_service_endpoints('identity')['publicURL'],
cyclades=auth.get_service_endpoints('compute')['publicURL'],
network=auth.get_service_endpoints('network')['publicURL'],
pithos=auth.get_service_endpoints('object-store')['publicURL'],
plankton=auth.get_service_endpoints('image')['publicURL']
# Astakos implements identity and account APIs - The endpoint
# URL is the same for both services
astakos=auth.get_endpoint_url('identity'),
cyclades=auth.get_endpoint_url(CycladesClient.service_type),
network=auth.get_endpoint_url(CycladesNetworkClient.service_type),
pithos=auth.get_endpoint_url(PithosClient.service_type),
plankton=auth.get_endpoint_url(ImageClient.service_type)
)
user_id = auth.user_info['id']
except ClientError:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment