Merge "Add specification for the Solum CAMP API."
This commit is contained in:
commit
47d890e181
|
@ -0,0 +1,430 @@
|
||||||
|
..
|
||||||
|
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||||
|
License.
|
||||||
|
|
||||||
|
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||||
|
|
||||||
|
==========================================
|
||||||
|
Solum CAMP API
|
||||||
|
==========================================
|
||||||
|
|
||||||
|
https://blueprints.launchpad.net/solum/+spec/solum-camp-api
|
||||||
|
|
||||||
|
The Cloud Application Management for Platforms (CAMP) [CAMP-v1.1]_
|
||||||
|
specification is an open standard for managing applications in a PaaS
|
||||||
|
environment. CAMP was created with the goals of increasing
|
||||||
|
interoperability between independent application management tools and
|
||||||
|
PaaS clouds as well furthering the portability of applications across
|
||||||
|
different clouds. Due to its mindshare, momentum, etc. OpenStack is an
|
||||||
|
obvious candidate for a CAMP implementation. The Solum project, which
|
||||||
|
is partially based on CAMP, is the natural place for this
|
||||||
|
implementation.
|
||||||
|
|
||||||
|
|
||||||
|
Problem description
|
||||||
|
===================
|
||||||
|
|
||||||
|
Although the Solum API and resource model are similar (and in some
|
||||||
|
cases identical) to the API and resource model defined in the CAMP
|
||||||
|
specification, they are also different in a number of significant
|
||||||
|
ways. Tools and applications written to consume the CAMP API cannot
|
||||||
|
use the Solum API. What is required is to provide a CAMP facade on the
|
||||||
|
services provided by Solum.
|
||||||
|
|
||||||
|
|
||||||
|
Proposed change
|
||||||
|
===============
|
||||||
|
|
||||||
|
This specification proposes adding an alternate, CAMP compliant, API
|
||||||
|
to the Solum API service. This API (hereafter called the "Solum CAMP
|
||||||
|
API") will exist alongside the current REST API (hereafter referred to
|
||||||
|
as the "Solum API").
|
||||||
|
|
||||||
|
This proposal is scoped by the following constraints:
|
||||||
|
|
||||||
|
* The existence of the Solum CAMP API shall have no impact on Users
|
||||||
|
and Deployers that interact exclusively with in the Solum API. The
|
||||||
|
"solum" command-line client, the Horizon plugin, the python-solum
|
||||||
|
library etc. shall be unaffected by the Solum CAMP API.
|
||||||
|
|
||||||
|
* The use cases supported by the Solum CAMP API shall be a subset of
|
||||||
|
those supported by the Solum API; Users should not have to choose
|
||||||
|
between alternate sets of functionality. Consumers of the CAMP API
|
||||||
|
should do so because their application/tool requires that API.
|
||||||
|
|
||||||
|
* From a functional perspective, entities (applications, plans,
|
||||||
|
components) created by interacting with one API shall be visible via
|
||||||
|
the other API. For example, if a User creates an application via the
|
||||||
|
Solum API, another User should (if they are authorized to do so) be
|
||||||
|
able to see the "assembly" resource that represents that application
|
||||||
|
via the Solum CAMP API.
|
||||||
|
|
||||||
|
* From an implementation perspective the Solum CAMP API should, to the
|
||||||
|
greatest extent possible, re-use existing Solum classes and
|
||||||
|
configuration settings.
|
||||||
|
|
||||||
|
* The architectural constraints and implementation conventions of
|
||||||
|
Solum shall be strictly adhered to.
|
||||||
|
|
||||||
|
Alternatives
|
||||||
|
------------
|
||||||
|
|
||||||
|
None.
|
||||||
|
|
||||||
|
Data model impact
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
The impact of the Solum CAMP API on the data model can be divided into
|
||||||
|
two separate areas: impacts on the data model due to the
|
||||||
|
implementation of CAMP-specific resource types and impacts on the data
|
||||||
|
model due to the difference between Solum resources and their CAMP
|
||||||
|
analogs (i.e. the difference between the Solum API's the CAMP API's
|
||||||
|
versions of the "assembly" resource).
|
||||||
|
|
||||||
|
CAMP-specific resources
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The CAMP-specific resources (i.e. resource types that exist in the
|
||||||
|
CAMP API but not the Solum API) are either static (e.g. the
|
||||||
|
"platform_endpoints" resource or the "type_definitions" resource) or
|
||||||
|
act as collections of other resources (e.g. the "services"
|
||||||
|
resource). The information presented by these resources is either a
|
||||||
|
reflection of configuration information or information about other
|
||||||
|
resources. In neither case is it necessary to store data about
|
||||||
|
multiple instances of these resource types.
|
||||||
|
|
||||||
|
CAMP-analog resources
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
At the time of this writing it appears that the majority of the
|
||||||
|
CAMP-analog resources (for example, the CAMP version of the "assembly"
|
||||||
|
resource) can be implemented without changing the database
|
||||||
|
schema. This is due to the fact that most of the CAMP-required
|
||||||
|
attributes that are missing from their Solum API counterparts are
|
||||||
|
Links to other resources. The information necessary to synthesize these
|
||||||
|
Links is present in Solum, but is presented in a different fashion by
|
||||||
|
the Solum API.
|
||||||
|
|
||||||
|
*If* additional information is required to support a CAMP-analog
|
||||||
|
resource, the suggested solution would be to create an additional
|
||||||
|
table that contains the CAMP-unique information and cross-references
|
||||||
|
the Solum resource using its id as a key.
|
||||||
|
|
||||||
|
|
||||||
|
REST API impact
|
||||||
|
---------------
|
||||||
|
|
||||||
|
CAMP's REST API is described by the Cloud Application Management for
|
||||||
|
Platforms (CAMP) specification. The URLs for Solum CAMP API resources
|
||||||
|
will exist in a separate sub-tree (named "camp") from those of the
|
||||||
|
Solum API.
|
||||||
|
|
||||||
|
The URL of the "platform_endpoints" resource (the resource that is
|
||||||
|
used to advertise the existence of distinct CAMP implementations) will
|
||||||
|
be:
|
||||||
|
|
||||||
|
*Solum_API_base_URL*/camp/platform_endpoints
|
||||||
|
|
||||||
|
The URL of the "platform_endpoint" resource for the CAMP v1.1
|
||||||
|
implementation will be:
|
||||||
|
|
||||||
|
*Solum_API_base_URL*/camp/camp_v1_1_endpoint
|
||||||
|
|
||||||
|
The URL of the "platform" resource (the root of the CAMP v1.1
|
||||||
|
resource tree) will be:
|
||||||
|
|
||||||
|
*Solum_API_base_URL*/camp/v1_1/platform
|
||||||
|
|
||||||
|
Security impact
|
||||||
|
---------------
|
||||||
|
|
||||||
|
Since the Solum CAMP API functions as an alternate interface to the
|
||||||
|
core Solum functionality, the addition of this API should not create
|
||||||
|
any additional attack vectors beyond those that may already exist
|
||||||
|
within Solum.
|
||||||
|
|
||||||
|
Notifications impact
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
The Solum CAMP API will send the same notifications, for the same
|
||||||
|
events, as the existing Solum API.
|
||||||
|
|
||||||
|
Other end user impact
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
Users employing CAMP compliant tools for managing their applications
|
||||||
|
will be able to use OpenStack/Solum without having to change these
|
||||||
|
tools.
|
||||||
|
|
||||||
|
Performance Impact
|
||||||
|
------------------
|
||||||
|
|
||||||
|
None.
|
||||||
|
|
||||||
|
Other deployer impact
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
The Solum CAMP API will be enabled/disabled via a configuration option
|
||||||
|
(e.g."camp-support-enabled = [True | False]"). The Solum CAMP API will
|
||||||
|
be enabled by default. Solum's configuration documentation will be
|
||||||
|
updated to describe this option and the effect of enabling/disabling
|
||||||
|
it.
|
||||||
|
|
||||||
|
Developer impact
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Adding additional code to the Solum project will have a maintenance
|
||||||
|
impact as features are added and bugs are fixed. For example, a change
|
||||||
|
to a handler class that is shared by the Solum API and CAMP API could
|
||||||
|
break the CAMP API code. The following steps will be taken to address
|
||||||
|
this impact:
|
||||||
|
|
||||||
|
* Ensure that interface between the Solum CAMP API and the core Solum
|
||||||
|
code is as clean as possible. This decreases the probability that
|
||||||
|
unrelated changes will break the CAMP API code or that changes to
|
||||||
|
the CAMP API will break other Solum code.
|
||||||
|
|
||||||
|
* Assign resources to maintain the Solum CAMP API code. The
|
||||||
|
implementation assignees identified below will be assigned this
|
||||||
|
task.
|
||||||
|
|
||||||
|
Implementation
|
||||||
|
==============
|
||||||
|
|
||||||
|
Assignee(s)
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Primary assignee:
|
||||||
|
gilbert.pilz
|
||||||
|
|
||||||
|
Other contributors:
|
||||||
|
anish-karmarkar
|
||||||
|
|
||||||
|
Work Items
|
||||||
|
----------
|
||||||
|
|
||||||
|
static resources
|
||||||
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Some of the resources defined in CAMP are static for a given
|
||||||
|
deployment and configuration. This work item will implement those
|
||||||
|
resources.
|
||||||
|
|
||||||
|
:Resources to be implemented:
|
||||||
|
platform
|
||||||
|
|
||||||
|
platform_endpoints
|
||||||
|
|
||||||
|
platform_endpoint
|
||||||
|
|
||||||
|
formats
|
||||||
|
|
||||||
|
format
|
||||||
|
|
||||||
|
type_definitions
|
||||||
|
|
||||||
|
type_definition
|
||||||
|
|
||||||
|
attribute_definition
|
||||||
|
|
||||||
|
At the completion of this step it will be possible to perform a
|
||||||
|
successful HTTP GET on these resources. Some of the attributes in
|
||||||
|
these resource may be missing or contain dummy values.
|
||||||
|
|
||||||
|
top-level container resources
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
This work item will implement the "top-level" container resources
|
||||||
|
defined by CAMP.
|
||||||
|
|
||||||
|
:Resources to be implemented:
|
||||||
|
|
||||||
|
assemblies
|
||||||
|
|
||||||
|
services
|
||||||
|
|
||||||
|
plans
|
||||||
|
|
||||||
|
Upon completion of this item it will be possible to perform a
|
||||||
|
successful HTTP GET on these resources. The Link arrays in these
|
||||||
|
resources will reference the Solum API versions of the "assembly",
|
||||||
|
"service", and "plan" resources (respectively) even though the Solum
|
||||||
|
versions of some of these resources are not CAMP-compliant.
|
||||||
|
|
||||||
|
register a Plan via the Solum CAMP API
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
This item will implement the code necessary to allow Users to POST a
|
||||||
|
Plan to the *Solum_API_base_URL*/camp/v1_1/plans resource using one of
|
||||||
|
the methods described in Section 6.12.2, "Registering a Plan by Value"
|
||||||
|
of the CAMP Specification.
|
||||||
|
|
||||||
|
Upon completion of this item it will be possible to POST a Plan to
|
||||||
|
*Solum_API_base_URL*/camp/v1_1/plans and have the contents of that
|
||||||
|
file appear as a "plan" resource in both the
|
||||||
|
*Solum_API_base_URL*/camp/v1_1/plans resource (as an element in the
|
||||||
|
plans_links array) and *Solum_API_base_URL*/v1/plans resource (as per
|
||||||
|
today). Note the "plan" resource in question will be the Solum version
|
||||||
|
of the resource; at this point there will be no CAMP-analog of the
|
||||||
|
"plan" resource.
|
||||||
|
|
||||||
|
Sending a DELETE request to the
|
||||||
|
*Solum_API_base_URL*/camp/v1_1/plan/*uuid* resource will remove the
|
||||||
|
"plan" resource from both the CAMP and Solum collections.
|
||||||
|
|
||||||
|
create an assembly from a reference to a plan resource
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
This item will implement the code necessary to allow Users create a
|
||||||
|
running application by POST-ing a reference to a "plan" resource to
|
||||||
|
the *Solum_API_base_URL*/camp/v1_1/assemblies resource as described in
|
||||||
|
Section 6.11.1, "Deploying an Application by Reference" of the CAMP
|
||||||
|
Specification.
|
||||||
|
|
||||||
|
:Resources to be implemented:
|
||||||
|
assembly
|
||||||
|
|
||||||
|
component
|
||||||
|
|
||||||
|
Upon completion of this item it will be possible to POST a reference
|
||||||
|
to a plan resource to *Solum_API_base_URL/camp/v1_1/assemblies* and
|
||||||
|
have Solum build and create a running application. This application
|
||||||
|
will be represented by two, analogous resources, a CAMP version
|
||||||
|
(*Solum_API_base_URL*/camp/v1_1/assembly/*uuid*) and a Solum version
|
||||||
|
(Solum_API_base_URL/v1/assemblies/*uuid*). Each resource will be
|
||||||
|
referenced by its corresponding container. The CAMP version of the
|
||||||
|
"assembly" resource will reference a tree of CAMP-specific "component"
|
||||||
|
resources (also analogs of their Solum counterparts)
|
||||||
|
|
||||||
|
Sending a DELETE request to the
|
||||||
|
*Solum_API_base_URL*/camp/v1_1/assembly/*uuid* resource will halt the
|
||||||
|
application and remove it from the system, removing both the CAMP and
|
||||||
|
Solum versions of the "assembly" resource and any corresponding
|
||||||
|
"component" resources.
|
||||||
|
|
||||||
|
create an assembly directly from a Plan file
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
This item will implement the code necessary to allow Users to create a
|
||||||
|
running application by POST-ing a Plan to the
|
||||||
|
*Solum_API_base_URL*/camp/v1_1/assemblies resource using one of the
|
||||||
|
methods described in Section 6.11.2, "Deploying an Application by
|
||||||
|
Value" of the CAMP Specification. This will be implemented by
|
||||||
|
combining the implementations of the two previous items.
|
||||||
|
|
||||||
|
Upon completion of this item it will be possible to POST a Plan file
|
||||||
|
to *Solum_API_base_URL*/camp/v1_1/assemblies and have Solum build and
|
||||||
|
create a running application. As a side-effect, a "plan" resource
|
||||||
|
will be created. The "assembly" and "component" resources will be the
|
||||||
|
same as for the preceding item.
|
||||||
|
|
||||||
|
Sending a DELETE request to the
|
||||||
|
*Solum_API_base_URL*/camp/v1_1/assembly/uuid resource will halt the
|
||||||
|
application and remove it from the system, removing both the CAMP and
|
||||||
|
Solum versions of the "assembly" resource and any corresponding
|
||||||
|
"component" resources but not the "plan" resource.
|
||||||
|
|
||||||
|
select_attr support
|
||||||
|
^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The CAMP specification requires implementations to support the use of
|
||||||
|
the "select_attr" query parameter as defined in sections 6.5, "Request
|
||||||
|
Parameters", and 6.10.1.1, "Partial Updates with PUT", of the CAMP
|
||||||
|
specification.
|
||||||
|
|
||||||
|
The Solum API does not support the use of the “select_attr” query
|
||||||
|
parameter. This item will add support for “select_attr”, for both
|
||||||
|
GET and PUT, to all resources exposed by the Solum CAMP API.
|
||||||
|
|
||||||
|
Upon completion of this item it should be possible for Users to use
|
||||||
|
the “select_attr” query parameter in conjunction with the GET and PUT
|
||||||
|
methods to retrieve and update (where permitted) a subset of a
|
||||||
|
resource’s attributes.
|
||||||
|
|
||||||
|
HTTP PATCH / JSON Patch support
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The CAMP specification requires implementations to support the use of
|
||||||
|
the HTTP PATCH method in conjunction with the
|
||||||
|
"application/json-patch+json" [RFC6902]_ media type.
|
||||||
|
|
||||||
|
The Solum API does not support the HTTP PATCH method. This item
|
||||||
|
will add support for the use of JSON Patch in conjunction with the
|
||||||
|
HTTP PATCH method to all resources.
|
||||||
|
|
||||||
|
Upon completion of this item it should be possible for Users to use
|
||||||
|
HTTP PATCH with a JSON Patch payload to update (where permitted) all
|
||||||
|
or subset of a resource’s attributes.
|
||||||
|
|
||||||
|
|
||||||
|
Dependencies
|
||||||
|
============
|
||||||
|
|
||||||
|
No dependencies other than those that already exist in Solum.
|
||||||
|
|
||||||
|
|
||||||
|
Testing
|
||||||
|
=======
|
||||||
|
|
||||||
|
In addition to unit tests, this project will develop a number of
|
||||||
|
tempest tests which will exercise the main use cases of the Solum CAMP
|
||||||
|
API. These tests will have the following pattern:
|
||||||
|
|
||||||
|
1. Walk the Solum CAMP API resource tree to find the appropriate
|
||||||
|
resource (e.g. "assemblies" resource)
|
||||||
|
|
||||||
|
2. Perform some action on that resource (e.g. POST a Plan file to that
|
||||||
|
resource).
|
||||||
|
|
||||||
|
3. Verify that the action has produced the desired result (e.g. the
|
||||||
|
creation of a new "assembly" resource.
|
||||||
|
|
||||||
|
The assertions defined in the "Cloud Application Management for
|
||||||
|
Platform (CAMP) Test Assertions" [CAMP-Test-Assertions-v1.1]_ document
|
||||||
|
will be used, where appropriate, to verify the proper behavior of the
|
||||||
|
API. Note, it is not our intention to cover every assertion defined in
|
||||||
|
this document, but simply to leverage the work that has been done in
|
||||||
|
this area.
|
||||||
|
|
||||||
|
|
||||||
|
Documentation Impact
|
||||||
|
====================
|
||||||
|
|
||||||
|
Information about the CAMP API (specifications, primers, etc.) is
|
||||||
|
provided by the OASIS CAMP Technical Committee.
|
||||||
|
|
||||||
|
Information about enabling/disabling the Solum CAMP API and any other
|
||||||
|
configuration information will be added to the Solum documentation.
|
||||||
|
|
||||||
|
|
||||||
|
References
|
||||||
|
==========
|
||||||
|
|
||||||
|
Specifications
|
||||||
|
--------------
|
||||||
|
|
||||||
|
.. [CAMP-v1.1] *Cloud Application Management for Platforms Version
|
||||||
|
1.1.* Edited by Jaques Durand, Adrian Otto, Gilbert Pilz, and Tom
|
||||||
|
Rutt. 12 February 2014. OASIS Committee Specification Draft 04 /
|
||||||
|
Public Review Draft 02.
|
||||||
|
http://docs.oasis-open.org/camp/camp-spec/v1.1/csprd02/camp-spec-v1.1-csprd02.html
|
||||||
|
Latest version:
|
||||||
|
http://docs.oasis-open.org/camp/camp-spec/v1.1/camp-spec-v1.1.html
|
||||||
|
|
||||||
|
.. [CAMP-Test-Assertions-v1.1] *Cloud Application Management for
|
||||||
|
Platforms (CAMP) Test Assertions v1.1.* Edited by Jaques Durand, Adrian
|
||||||
|
Otto, Gilbert Pilz, and Tom Rutt. 12 February 2014. OASIS Committee
|
||||||
|
Specification Draft 01 / Public Review Draft 01.
|
||||||
|
http://docs.oasis-open.org/camp/camp-ta/v1.1/csprd01/camp-ta-v1.1-csprd01.html
|
||||||
|
Latest version:
|
||||||
|
http://docs.oasis-open.org/camp/camp-ta/v1.1/camp-ta-v1.1.html
|
||||||
|
|
||||||
|
.. [RFC6902] Bryan, P., Ed., and M. Nottingham, Ed., "JavaScript
|
||||||
|
Object Notation (JSON) Patch", RFC 6902,
|
||||||
|
April 2013. http://www.ietf.org/rfc/rfc6902.txt
|
||||||
|
|
||||||
|
Implementations
|
||||||
|
---------------
|
||||||
|
|
||||||
|
* nCAMP, CAMP v1.1 Proof of Concept.
|
||||||
|
http://ec2-107-20-16-71.compute-1.amazonaws.com/campSrv/
|
Loading…
Reference in New Issue