Initial spec for the Tuskar Juno REST API changes
Change-Id: I54f005486b8c3ec3caa9f9de4e04f9e1af59b50c
This commit is contained in:
Jay Dobies
parent
98106401e1
commit
d23801a6ba
|
|
@ -0,0 +1,302 @@
|
|||
..
|
||||
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||
License.
|
||||
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
|
||||
=============================
|
||||
Tuskar REST API Specification
|
||||
=============================
|
||||
|
||||
https://blueprints.launchpad.net/tripleo/+spec/tuskar-rest-api
|
||||
|
||||
In Juno, the Tuskar API is moving towards a model where roles correspond more
|
||||
closely with Heat provider resources. Tuskar is responsible for assembling
|
||||
the user-selected roles and their configuration into a Heat environment and
|
||||
performing the necessary calls into Heat to make the changes live when
|
||||
appropriate.
|
||||
|
||||
This specification describes the REST APIs a client will interact with in
|
||||
Tuskar, including the URLs, HTTP methods, request, and response data.
|
||||
|
||||
|
||||
Problem description
|
||||
===================
|
||||
|
||||
A detailed description of the problem:
|
||||
|
||||
* For a new feature this might be use cases. Ensure you are clear about the
|
||||
actors in each use case: End User vs Deployer
|
||||
|
||||
* For a major reworking of something existing it would describe the
|
||||
problems in that feature that are being addressed.
|
||||
|
||||
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
Below is a description of the Tuskar API REST APIs.
|
||||
|
||||
.. _retrieve-single-cloud:
|
||||
|
||||
**Retrieve a Single Cloud**
|
||||
|
||||
URL: ``/clouds/<cloud-name>/``
|
||||
|
||||
Method: ``GET``
|
||||
|
||||
Description: Returns the details of a specific cloud.
|
||||
|
||||
Notes:
|
||||
|
||||
* As of this time, there is no option to pre-fetch extra details about each
|
||||
cloud, such as it's roles or configuration. For usability, this may be
|
||||
desired in the future.
|
||||
|
||||
Request Data: None
|
||||
|
||||
Response Codes:
|
||||
|
||||
* 200 - if the cloud is found
|
||||
* 404 - if there is no cloud with the given name
|
||||
|
||||
Response Data:
|
||||
|
||||
JSON document containing the following:
|
||||
|
||||
* Name - Name of the cloud that was created.
|
||||
* Description - Description of the cloud that was created.
|
||||
* Stack ID - ID for the corresponding stack in Heat.
|
||||
|
||||
Response Example:
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
'name' : 'dev-cloud',
|
||||
'description' : 'Development testing cloud',
|
||||
'stack_id' : 'cbc36478b0bd8e67e89469c7749d4127'
|
||||
}
|
||||
|
||||
|
||||
.. _list-clouds:
|
||||
|
||||
**List Clouds**
|
||||
|
||||
URL: ``/clouds/``
|
||||
|
||||
Method: ``GET``
|
||||
|
||||
Description: Returns a list of all clouds known to Tuskar.
|
||||
|
||||
Notes:
|
||||
|
||||
* See the note in :ref:`Retrieve a Single Cloud <retrieve-single-cloud>` about
|
||||
pre-fetching a cloud's roles and configuration.
|
||||
|
||||
Request Data: None
|
||||
|
||||
Response Codes:
|
||||
|
||||
* 200 - if the list can be retrieved
|
||||
|
||||
Response Data:
|
||||
|
||||
JSON document containing a list of clouds. The details provided in each
|
||||
cloud is the same as for the GET operation on an individual cloud
|
||||
(see :ref:`Retrieve a Single Cloud <retrieve-single-cloud>`).
|
||||
|
||||
.. _create-new-cloud:
|
||||
|
||||
**Create a New Cloud**
|
||||
|
||||
URL: ``/clouds/``
|
||||
|
||||
Method: ``POST``
|
||||
|
||||
Description: Performs the following operations:
|
||||
|
||||
* Creates an entry in Tuskar's storage for the cloud. The details are outside
|
||||
of the scope of this spec, but the idea is that all of the necessary Heat
|
||||
environment infrastructure files and directories will be created and stored
|
||||
in Tuskar's storage solution.
|
||||
* Creates a new, empty stack in Heat that corresponds to this newly created
|
||||
cloud.
|
||||
|
||||
Notes:
|
||||
|
||||
* Returns immediately after the two operations complete. In other words, this
|
||||
is a synchronous operation that will result in the created cloud by the
|
||||
time it ends.
|
||||
* As of this time, this call does not support a larger batch operation that
|
||||
will add roles or set configuration values. From a REST perspective, this is
|
||||
acceptable, but from a usability standpoint we may want to add this support
|
||||
in the future.
|
||||
|
||||
Request Data:
|
||||
|
||||
JSON document containing the following:
|
||||
|
||||
* Name - Name of the cloud being created. Must be unique across all clouds
|
||||
created in Tuskar.
|
||||
* Description - Description of the cloud to create.
|
||||
|
||||
Request Example:
|
||||
|
||||
::
|
||||
|
||||
{
|
||||
'name' : 'dev-cloud',
|
||||
'description' : 'Development testing cloud'
|
||||
}
|
||||
|
||||
Response Codes:
|
||||
|
||||
* 201 - if the create is successful
|
||||
* 409 - if there is an existing cloud with the given name
|
||||
|
||||
Response Data:
|
||||
|
||||
JSON document describing the created cloud, with its stack ID populated.
|
||||
The details are the same as for the GET operation on an individual cloud
|
||||
(see :ref:`Retrieve a Single Cloud <retrieve-single-cloud>`).
|
||||
|
||||
|
||||
Alternatives
|
||||
------------
|
||||
|
||||
There are currently no alternative schemas for the REST APIs.
|
||||
|
||||
|
||||
Security impact
|
||||
---------------
|
||||
|
||||
Describe any potential security impact on the system. Some of the items to
|
||||
consider include:
|
||||
|
||||
* Does this change touch sensitive data such as tokens, keys, or user data?
|
||||
|
||||
* Does this change involve cryptography or hashing?
|
||||
|
||||
* Does this change require the use of sudo or any elevated privileges?
|
||||
|
||||
* Does this change involve using or parsing user-provided data? This could
|
||||
be directly at the API level or indirectly such as changes to a cache layer.
|
||||
|
||||
* Can this change enable a resource exhaustion attack, such as allowing a
|
||||
single API interaction to consume significant server resources? Some examples
|
||||
of this include launching subprocesses for each connection, or entity
|
||||
expansion attacks in XML.
|
||||
|
||||
For more detailed guidance, please see the OpenStack Security Guidelines as
|
||||
a reference (https://wiki.openstack.org/wiki/Security/Guidelines). These
|
||||
guidelines are a work in progress and are designed to help you identify
|
||||
security best practices. For further information, feel free to reach out
|
||||
to the OpenStack Security Group at openstack-security@lists.openstack.org.
|
||||
|
||||
Other end user impact
|
||||
---------------------
|
||||
|
||||
None
|
||||
|
||||
Performance Impact
|
||||
------------------
|
||||
|
||||
Describe any potential performance impact on the system, for example
|
||||
how often will new code be called, and is there a major change to the calling
|
||||
pattern of existing code.
|
||||
|
||||
Examples of things to consider here include:
|
||||
|
||||
* A small change in a utility function or a commonly used decorator can have a
|
||||
large impacts on performance.
|
||||
|
||||
Other deployer impact
|
||||
---------------------
|
||||
|
||||
Discuss things that will affect how you deploy and configure OpenStack
|
||||
that have not already been mentioned, such as:
|
||||
|
||||
* What config options are being added? Should they be more generic than
|
||||
proposed (for example a flag that other hypervisor drivers might want to
|
||||
implement as well)? Are the default values ones which will work well in
|
||||
real deployments?
|
||||
|
||||
* Is this a change that takes immediate effect after its merged, or is it
|
||||
something that has to be explicitly enabled?
|
||||
|
||||
* Please state anything that those doing continuous deployment, or those
|
||||
upgrading from the previous release, need to be aware of. Also describe
|
||||
any plans to deprecate configuration values or features. For example, if we
|
||||
change the directory name that instances are stored in, how do we handle
|
||||
instance directories created before the change landed? Do we move them? Do
|
||||
we have a special case in the code? Do we assume that the operator will
|
||||
recreate all the instances in their cloud?
|
||||
|
||||
Developer impact
|
||||
----------------
|
||||
|
||||
Discuss things that will affect other developers working on OpenStack.
|
||||
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
Assignee(s)
|
||||
-----------
|
||||
|
||||
Who is leading the writing of the code? Or is this a blueprint where you're
|
||||
throwing it out there to see who picks it up?
|
||||
|
||||
If more than one person is working on the implementation, please designate the
|
||||
primary author and contact.
|
||||
|
||||
Primary assignee:
|
||||
<launchpad-id or None>
|
||||
|
||||
Other contributors:
|
||||
<launchpad-id or None>
|
||||
|
||||
Work Items
|
||||
----------
|
||||
|
||||
Work items or tasks -- break the feature up into the things that need to be
|
||||
done to implement it. Those parts might end up being done by different people,
|
||||
but we're mostly trying to understand the timeline for implementation.
|
||||
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
* Include specific references to specs and/or blueprints in tripleo, or in other
|
||||
projects, that this one either depends on or is related to.
|
||||
|
||||
* If this requires functionality of another project that is not currently used
|
||||
by Tripleo (such as the glance v2 API when we previously only required v1),
|
||||
document that fact.
|
||||
|
||||
* Does this feature require any new library dependencies or code otherwise not
|
||||
included in OpenStack? Or does it depend on a specific version of library?
|
||||
|
||||
|
||||
Testing
|
||||
=======
|
||||
|
||||
Please discuss how the change will be tested.
|
||||
|
||||
Is this untestable in CI given current limitations (specific hardware /
|
||||
software configurations available)? If so, are there mitigation plans (3rd
|
||||
party testing, gate enhancements, etc).
|
||||
|
||||
|
||||
Documentation Impact
|
||||
====================
|
||||
|
||||
The REST API documentation will need to be updated accordingly.
|
||||
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
* https://wiki.openstack.org/wiki/TripleO/TuskarJunoPlanning/TemplateBackend
|
||||
* https://etherpad.openstack.org/p/juno-summit-tripleo-tuskar-planning
|
||||
Loading…
Reference in New Issue