diff --git a/specs/juno/solum-camp-api.rst b/specs/juno/solum-camp-api.rst new file mode 100644 index 0000000..f0f2a69 --- /dev/null +++ b/specs/juno/solum-camp-api.rst @@ -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/