Merge "Spec on capability to edit existing environment properties"

This commit is contained in:
Jenkins 2016-10-05 12:53:34 +00:00 committed by Gerrit Code Review
commit b85fe80e12
1 changed files with 363 additions and 0 deletions

View File

@ -0,0 +1,363 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License.
http://creativecommons.org/licenses/by/3.0/legalcode
==================================================
Capability to edit existing environment properties
==================================================
https://blueprints.launchpad.net/murano/+spec/environment-edit
The spec proposes mechanism for users to edit any details of an existing
environment, for example edit its regions, set home region, change the
networks or any other possible input field.
Problem description
===================
Current Murano API and python-muranoclient only allow to specify its home
region and default network during the environment creation. These parameters
cannot be seen and cannot be updated by the user after the environment
creation. Users may want to examine and change these or other environment
properties after it is created. Adding a mechanism to apply custom JSON-patch
to environment object model would provide this capability and add a great
flexibility in managing environments.
Proposed change
===============
Changes in API
--------------
It is proposed to create a new API endpoint
`/environments/<env_id>/model` and two calls to it using GET and PATCH
requests.
**GET** request provides environment object model where all environment
properties can be seen. See the `REST API impact` section for the example of
such output. If session is specified in the request and it is not in deploying
state, response gives modified environment model from the session, otherwise
actual environment model.
**PATCH** request allows to perform custom change to the environment object
model using JSON-patch object. It requires session to be specified by request
and saves changes to environment model in the specified session.
JSON-patch is a valid JSON that contains a list of changes to be applied to
the current object. Each change contains a dictionary with three keys: ``op``,
``path`` and ``value``. ``op`` (operation) can be one of the three values:
`add`, `replace` or remove`. *See RFC 6902 [1] for details*.
To indicate that body of the request is JSON-patch and validate correct
format of the body, a new media type should be added -
`application/env-model-json-patch`. During the validation in the middleware,
the following conditions must be checked against the passed object:
* It is a valid JSON-patch object (already implemented for
`application/murano-packages-json-patch` media type and should be reused).
Otherwise `400 Bad Request` response is given.
* Not all kinds of operations can be applied to all sections of the
environment model. The list of allowed operations is the following:
+ defaultNetworks: replace
+ name: replace
+ region: replace
+ regions: add, replace, remove
+ services: add, replace, remove
+ ?: add, replace, remove
Attempt to perform the restricted change will result in the `403 Forbidden`
response.
* Types of the environment properties and possible values are validated by the
appropriate JSON-schema. Otherwise `400 Bad Request` response is given.
Changes in python-muranoclient
------------------------------
To support the new API calls, corresponding python-muranoclient methods for
environments are needed: ``get_model`` and ``update_model`` respectively.
New CLI command that displays the result of ``get_model`` method:
.. code-block:: shell
murano environment-model-show <ENV_ID> [--path <PATH>] [--session-id <SESSION_ID>]
<PATH> allows to get a specific section of the model, for example
`defaultNetworks`, `region` or `?` or any of the subsections. It defaults to
'/' which means getting the whole model. Specifying <SESSION_ID> allows to get
the state of the environment with pending changes, while omitting it gives
the actual state.
New CLI command that allows to update environment model with a custom patch:
.. code-block:: shell
murano environment-model-edit <ENV_ID> <FILE> --session-id <SESSION_ID>
The command calls ``update_model`` method with data (JSON-patch) provided in
the <FILE> file. Changes are to be saved in session <SESSION_ID>.
Alternatives
------------
Separate CLI command can be created for updating each environment property.
It will be somewhat easier for users because file with JSON-patch will not be
needed. On the other hand, it will require creating a bunch of commands
instead of one generic and necessity to add new commands in future for the
possible new properties.
Data model impact
-----------------
None
REST API impact
---------------
**Get environment model**
+----------+-------------------------------------+------------------------+--------------------------+
| Method | URI | Header | Description |
+==========+=====================================+========================+==========================+
| GET | /environments/<env_id>/model/<path> | X-Configuration-Session| Get an Environment model |
| | | (optional) | |
+----------+-------------------------------------+------------------------+--------------------------+
Specifying <path> allows to get a specific section of the model, for example
`defaultNetworks`, `region` or `?` or any of the subsections.
*Response*
**Content-Type**
application/json
::
{
"defaultNetworks": {
"environment": {
"internalNetworkName": "net_two",
"?": {
"type": "io.murano.resources.ExistingNeutronNetwork",
"id": "594e94fcfe4c48ef8f9b55edb3b9f177"
}
},
"flat": null
},
"region": "RegionTwo",
"name": "new_env",
"regions": {
"": {
"defaultNetworks": {
"environment": {
"autoUplink": true,
"name": "new_env-network",
"externalRouterId": null,
"dnsNameservers": [],
"autogenerateSubnet": true,
"subnetCidr": null,
"openstackId": null,
"?": {
"dependencies": {
"onDestruction": [{
"subscriber": "c80e33dd67a44f489b2f04818b72f404",
"handler": null
}]
},
"type": "io.murano.resources.NeutronNetwork/0.0.0@io.murano",
"id": "e145b50623c04a68956e3e656a0568d3",
"name": null
},
"regionName": "RegionOne"
},
"flat": null
},
"name": "RegionOne",
"?": {
"type": "io.murano.CloudRegion/0.0.0@io.murano",
"id": "c80e33dd67a44f489b2f04818b72f404",
"name": null
}
},
"RegionOne": "c80e33dd67a44f489b2f04818b72f404",
"RegionTwo": {
"defaultNetworks": {
"environment": {
"autoUplink": true,
"name": "new_env-network",
"externalRouterId": "e449bdd5-228c-4747-a925-18cda80fbd6b",
"dnsNameservers": ["8.8.8.8"],
"autogenerateSubnet": true,
"subnetCidr": "10.0.198.0/24",
"openstackId": "00a695c1-60ff-42ec-acb9-b916165413da",
"?": {
"dependencies": {
"onDestruction": [{
"subscriber": "f8cb28d147914850978edb35eca156e1",
"handler": null
}]
},
"type": "io.murano.resources.NeutronNetwork/0.0.0@io.murano",
"id": "72d2c13c600247c98e09e2e3c1cd9d70",
"name": null
},
"regionName": "RegionTwo"
},
"flat": null
},
"name": "RegionTwo",
"?": {
"type": "io.murano.CloudRegion/0.0.0@io.murano",
"id": "f8cb28d147914850978edb35eca156e1",
"name": null
}
}
},
services: []
"?": {
"type": "io.murano.Environment/0.0.0@io.murano",
"_actions": {
"f7f22c174070455c9cafc59391402bdc_deploy": {
"enabled": true,
"name": "deploy",
"title": "deploy"
}
},
"id": "f7f22c174070455c9cafc59391402bdc",
"name": null
}
}
+----------------+-----------------------------------------------------------+
| Code | Description |
+================+===========================================================+
| 200 | Environment model received successfully |
+----------------+-----------------------------------------------------------+
| 403 | User is not authorized to access environment |
+----------------+-----------------------------------------------------------+
| 404 | Environment is not found or specified section of the |
| | model does not exist |
+----------------+-----------------------------------------------------------+
**Update environment model**
*Request*
+----------+--------------------------------+------------------------+-----------------------------+
| Method | URI | Header | Description |
+==========+================================+========================+=============================+
| PATCH | /environments/<env_id>/model/ | X-Configuration-Session| Update an Environment model |
+----------+--------------------------------+------------------------+-----------------------------+
* **Content-Type**
application/env-model-json-patch
* **Example**
::
[{
"op": "replace",
"path": "/defaultNetworks/flat",
"value": true
}]
*Response*
**Content-Type**
application/json
See GET request response.
+----------------+-----------------------------------------------------------+
| Code | Description |
+================+===========================================================+
| 200 | Environment is edited successfully |
+----------------+-----------------------------------------------------------+
| 400 | Body format is invalid |
+----------------+-----------------------------------------------------------+
| 403 | User is not authorized to access environment or specified |
| | operation is forbidden for the given property |
+----------------+-----------------------------------------------------------+
| 404 | Environment is not found or specified section of the |
| | model does not exist |
+----------------+-----------------------------------------------------------+
Versioning impact
-----------------
None
Other end user impact
---------------------
Users will get new CLI commands to examine and edit environment object model.
Deployer impact
---------------
None
Developer impact
----------------
None
Murano-dashboard / Horizon impact
---------------------------------
New python-muranoclient method can be used for providing environment edit
capability from GUI, but this perspective is out of scope of this spec.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
vakovalchuk
Work Items
----------
* Implement new API call to get object model of environment
* Implement new API calls to update the object model of environment
* Implement new python-muranoclient methods to support new API calls
* Add shell command that allows to display environment object model
* Add shell command that allows to apply JSON-patch to the environment model
* Add the same commands to the OpenStack client shell
Dependencies
============
None
Testing
=======
* API calls should be tested by unit tests and tempest tests
* CLI commands should be tested by unit tests
Documentation Impact
====================
* API calls should be described in the Murano API specification
* CLI commands should be described in the end user guide
References
==========
[1] https://tools.ietf.org/html/rfc6902