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