Service API SDK

This specification defines the design of Murano Service API SDK - a
high level client library allowing cloud applications (both
murano-deployed and external) to access applications's Service API in
consistent, convenient and secure way.

Change-Id: I6f1ba7b9079fc6ad5ef4ead491460506169d7d39
This commit is contained in:
Alexander Tivelkov 2016-02-16 16:24:55 +03:00
parent 9f095976f7
commit ab01a2df95
1 changed files with 259 additions and 0 deletions

View File

@ -0,0 +1,259 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
===============
Service API SDK
===============
https://blueprints.launchpad.net/murano/+spec/service-api-sdk
This specification defines the design of Murano Service API SDK - a high level
client library allowing cloud applications (both murano-deployed and external)
to access applications's Service API in consistent, convenient and secure way.
Problem description
===================
Service API is a way for murano applications to expose their configuration and
lifecycle & maintenance actions for other cloud applications, users and
administrators.
Since murano is designed to be a single integration point for applications in
the cloud, all the interactions with service APIs of deployed apps should be
done via Murano API by either of the two ways:
* Modifications of Object Model, i.e. changes of declarative definition of app
configuration;
* Calls of MuranoPL methods explicitly marked as externally executable actions.
Both these ways of interaction assume some deep and low-level work with murano
API: they require to fetch the object model from the environment, inspect it,
modify according to all the contracts and constraints, call appropriate methods
and so on. This does not bother end-users and administrators since the actual
API is hidden from them by various UI and CLI tools, but becomes a problem for
third-party software solutions since they have to interact with the API
directly and thus have to possess deep knowledge of murano internals.
If we want the cloud applications to be able to interact with each other via
murano we need to provide some higher level client library which will
encapsulate all the murano-related specifics and will provide the clients with
clean and streamlined software interface.
The primary consumers of this SDK library will be the developers of cloud
applications. This applications will integrate with SDK thus obtaining high
level access to their own (and their peers') service API exposed via murano.
Proposed change
===============
It is proposed to add a new set of python classes (distributed either as a
standalone pypi package or as a new module in python-muranoclient package)
which will provide a set of high level calls to murano API returning
dynamically constructed python objects representing appropriate entities of
object model. The attributes of these objects will match appropriate Input or
Output properties of their corresponding MuranoPL objects.
Consumer's code will be able to modify the values of Input (or InputOutput)
properties but only if the value being set matches the contracts of that
properties. Output properties are readonly, so attempts to modify the
corresponding python attributes will lead to exceptions.
The SDK will provide a context manager object creating a new session in the
given environment. Each property assignment being done within an appropriate
"with" code block will result in an API call immediately modifying the object
model of appropriate session. When the execution exits the "with" block the
session will be "committed", i.e. the changes will be copied to the main
environment object model. The SDK may be configured to automatically redeploy
the environment after commits.
The pythonic objects generated by the SDK will contain methods corresponding to
publicly-exposed MuranoPL methods ("actions"). Calling these pythonic methods
from the consumer code will execute appropriate actions. The parameters of the
called methods will be evaluated to match the contracts of appropriate MuranoPL
method arguments prior to calling the actual murano action API. These
dynamically generated methods will have names matching the names of appropriate
actions.
It will be possible to call these methods either synchronously or
asynchronously. In the former case the call will block the execution until the
action execution completes, so the method calls return final result, while the
actual execution will do polling on Action API under the hood. In the latter
case the action execution will be initiated, but the call will immediately
return a "Future" object which may be used later to retrieve the result (in a
single call if the action is already completed at that moment or by polling if
not).
The SDK will provide a factory class capable to create and configure the
instances of the client based on a set of configuration values. It should allow
passing these values both manually and reading them from a file in a specific
format. The latter will be used when the SDK access is provided to a virtual
machine deployed via murano: if the SDK access is granted to it the
configuration file will be delivered to the VM as part of the provisioning
process, so the SDK will be able to load it from the well-known location.
Deployment of SDK on the VMs may be done manually by the application developers
(e.g. they may include the dependency on appropriate python package in the
requirements.txt file of their python distribution), but it may be beneficial
to simplify this process by providing appropriate methods in the base class of
Standard Library: having a `deploySdk` method in the `LinuxMuranoInstance`
class will allow applications to easily deploy the SDK on its VMs with a single
call of a MuranoPL method. Such deployment will also sent a set of
configuration settings which will allow the SDK to properly connect to and
authenticate with murano API.
The SDK will include the authentication tooling: a set of utilities which will
allow applications to request access to murano API and the user to grant it.
This particular part is out of scope for this specification and should be
described separately.
Alternatives
------------
As an alternative to this SDK the client code could use regular Murano API
without any wrappers around it. This requires more efforts from application
developer and thus should be used only if the SDK does not provide the required
functionality.
Security Impact
---------------
Any consumers of Murano API should be properly authenticated to access its
resources. The regular users will use usual keystone-based authentication by
obtaining an access token using their username and password. However the
third-party applications which are the primary consumers of the SDK described
in this spec cannot be trusted with actual users credentials. Instead some role
delegation system should be used: based on trusts, OAuth delegation or
something else.
An authentication token of some kind should be delivered to VM and become part
of the SDK configuration file; this token will allow the SDK to authenticate in
murano API. This token will be scoped to
A separate spec is required to to describe the trust system, access scopes and
the changes which have to be introduced to support all of them in Murano.
Data model impact
-----------------
No model impact
REST API impact
---------------
To properly support transaction-like changes in Object Model the session API
needs to be improved to support session "commits" without the actual
deployments.
A new API call will be added:
* Complete Session
* Completes the session, thus merging its object model back to the
environment
* Method type: POST
* Normal http response code(s): 200
* Expected error http response code(s):
* 409 if the merge cannot be done due to a conflict, i.e. if the same parts
of the object model were modified by a another recently completed session
* 403 if the environment is being deployed
* URI: /v1/environments/%environment_id%/sessions/%session_id%/complete
* URI parameters:
* environment_id - id of the environment
* session_id - id of the session
Versioning impact
-----------------
Since the session completion operation adds a new call to murano API a minor
API version should be incremented
Other end user impact
---------------------
None
Deployer impact
---------------
None
Developer impact
----------------
Application developers will need to be familiar with SDK, as well as with the
ways to authorize their VM-based apps to access it.
Murano-dashboard / Horizon impact
---------------------------------
None
Implementation
==============
Assignee(s)
-----------
Primary assignee:
ativelkov
Work Items
----------
* Introduce API changes
* Create the SDK classes in python-muranoclient or standalone library
* Add helper methods to automate SDK deployments on the VMs provisioned by
murano-deployed applications.
Dependencies
============
* Authentication tooling has to be implemented before this SDK is created
Testing
=======
* The internals of the SDK should be covered by unit and functional tests.
* All the API calls utilized by the SDK should be covered by the integration
tests.
Documentation Impact
====================
The SDK has to be clearly documented so the application developers know how to
use it.
References
==========
None