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:
parent
9f095976f7
commit
ab01a2df95
|
@ -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
|
Loading…
Reference in New Issue