342 lines
8.7 KiB
ReStructuredText
342 lines
8.7 KiB
ReStructuredText
..
|
||
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||
License.
|
||
|
||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||
|
||
=============================
|
||
Support of custom node labels
|
||
=============================
|
||
|
||
https://blueprints.launchpad.net/fuel/+spec/node-custom-attributes
|
||
|
||
Custom node labels support should be introduced in Fuel to allow the user
|
||
to filter and sort nodes in OpenStack environment.
|
||
|
||
|
||
Problem description
|
||
===================
|
||
|
||
Now there is no way in Fuel to add custom labels to nodes. At the same time
|
||
this is an extremely useful feature for management of large environments:
|
||
labels can be used for sorting and filtering of node list to show only nodes
|
||
that are characterized by specified parameters. Labels enable users to map
|
||
their own organizational structures onto node list.
|
||
|
||
|
||
Proposed change
|
||
===============
|
||
|
||
In Fuel (both Web UI and CLI) user should be able to create, read, update or
|
||
delete unlimited number of custom labels (i.e. rack number, position) of
|
||
a particular node or a node group. Unlike names and IDs, labels do not provide
|
||
uniqueness. In general, it is expected many nodes to carry the same labels.
|
||
|
||
Labels are key-value pairs. Label key must be unique for a given node. Both
|
||
label key and value must be strings of 100 characters or less excluding an
|
||
empty string. We need 100 characters length limitation to avoid storing tons
|
||
of data in labels.
|
||
Label can also have `null` value that means an absence of label value (label
|
||
is like a simple tag in this case).
|
||
|
||
.. code-block:: json
|
||
|
||
...,
|
||
"labels": {
|
||
"label1": "value1",
|
||
"label2": null,
|
||
...
|
||
}
|
||
|
||
For Web UI
|
||
----------
|
||
|
||
List of assigned labels should be shown on node panel, both standard (under
|
||
a role list) and compact (in its extended view when user hovers a node).
|
||
|
||
There should be an interface in Web UI to manage node or node group labels
|
||
(CRUD operations).
|
||
|
||
Interface should also support an autocompletion of label keys (i.e. show
|
||
dynamic list of previously assigned labels for nodes - user type "r"
|
||
and it automatically shows "rack number") during creation. This will also
|
||
prevent user from entering in incorrect keys.
|
||
|
||
All custom labels should be included in node list filtering and sorting
|
||
scopes.
|
||
|
||
User should be able to choose a label key from filter list and select its
|
||
particular values. Filter options list should also include 'Not specified'
|
||
option to filter nodes with not specified value of the label.
|
||
|
||
User should be able to choose a label key in sorter list and group nodes
|
||
according its values. Nodes with not specified value of chosen label go last
|
||
in sorted node list.
|
||
|
||
For Nailgun
|
||
-----------
|
||
|
||
Data model impact
|
||
^^^^^^^^^^^^^^^^^
|
||
|
||
New ``labels`` attribute of JSON type should be added to ``Node`` model
|
||
into Nailgun database.
|
||
|
||
The new field should also be added to already existing entries in database.
|
||
Migration should add ``labels`` column with empty JSON object value "{}".
|
||
|
||
REST API impact
|
||
^^^^^^^^^^^^^^^
|
||
|
||
No new methods needed.
|
||
|
||
Existing ``PUT /api/nodes/{node_id}`` method should be modified to be able
|
||
to accept data (Ok code 200, server error code starting from 500) in the form
|
||
of the following JSON:
|
||
|
||
.. code-block:: json
|
||
|
||
{
|
||
"id": 1,
|
||
"labels": {
|
||
"label1": "value1",
|
||
"label2": null,
|
||
...
|
||
}
|
||
}
|
||
|
||
API should return 400 Bad Request in case of the following bad scenarios
|
||
(that are possible from CLI):
|
||
|
||
* user tries to add label with invalid key (key is not a string or an empty
|
||
string or a string with more than 100 characters)
|
||
* user tries to apply invalid value to label (value is string with more than
|
||
100 characters or value is not a string or null)
|
||
* user tries to add/update/delete label of non-existing node
|
||
|
||
Accordingly, this new ``labels`` field should be added to the method output:
|
||
|
||
.. code-block:: json
|
||
|
||
{
|
||
"id": 1,
|
||
"name": "node#1",
|
||
...
|
||
"labels": {
|
||
"label1": "value1",
|
||
"label2": null,
|
||
...
|
||
}
|
||
}
|
||
|
||
Similarly existing ``GET /api/nodes/{node_id}`` method should return
|
||
the new field.
|
||
|
||
Collection methods ``PUT /api/nodes/` and ``GET /api/nodes/`` should
|
||
also be updated with the new field.
|
||
|
||
For Fuel Client
|
||
---------------
|
||
|
||
Adding support for key-value labels is pretty easy as far as all logic is
|
||
encapsulated in the Fuel API. Adding, removing or changing these labels
|
||
should only be done on the Nailgun's side so the official python-fuelclient
|
||
and the rest of the client will be able to use it in a unified way.
|
||
|
||
There is a list of new commands to be added to work with labels from CLI:
|
||
|
||
to create or update label(s) for node(s)
|
||
|
||
::
|
||
|
||
fuel2 node label set -l |--labels key_1=[value_1] [key_2=[value_2] ... ] \
|
||
-n | --nodes node_id_1 [node_id_2 ...]
|
||
|
||
to create or update label(s) for ALL nodes
|
||
|
||
::
|
||
|
||
fuel2 node label set -l |--labels key_1=[value_1] [key_2=[value_2] ... ] \
|
||
--nodes-all
|
||
|
||
to delete label(s) of node(s)
|
||
|
||
::
|
||
|
||
fuel2 node label delete -l |--labels key_1[=value_1] [key_2[=value_2] ... ] \
|
||
-n | --nodes node_id_1 [node_id_2 ...]
|
||
|
||
to delete ALL labels of ALL nodes
|
||
|
||
::
|
||
|
||
fuel2 node label delete --labels-all --nodes-all
|
||
|
||
to display values of label(s) of node(s)
|
||
|
||
::
|
||
|
||
fuel2 node label list -n | --nodes node_id_1 [node_id_2 ...]
|
||
|
||
node_id | label_name | label_value
|
||
1 | key1 | value1
|
||
2 | key2 | value2
|
||
3 | key2 | value3
|
||
|
||
It should also be possible to filter nodes by labels and its values
|
||
|
||
::
|
||
|
||
fuel2 node list --labels key1[=value_1] [key2[=value_2] ... ]
|
||
|
||
Node labels should also be shown in the output of ``fuel2 node list`` command,
|
||
but should not be included to the output of the command ``fuel2 node show``,
|
||
because formatting of the table may be screwed up if there is a lot of labels
|
||
on a single node.
|
||
|
||
Also white spaces will be trimmed from the key-value label pair:
|
||
``" some key = some value"`` will be led to ``"some key=some value"``
|
||
|
||
All the commands above should fail and not to apply any changes if they get
|
||
400 Bad Request response from Nailgun API (see `For Nailgun`_ section).
|
||
|
||
Alternatives
|
||
------------
|
||
|
||
None.
|
||
|
||
Data model impact
|
||
-----------------
|
||
|
||
See `For Nailgun`_ section of the proposed change.
|
||
|
||
REST API impact
|
||
---------------
|
||
|
||
See `For Nailgun`_ section of the proposed change.
|
||
|
||
Upgrade impact
|
||
--------------
|
||
|
||
Since we have data model impact, we have to prepare an Alembic migration
|
||
that should update clusters to fit the new format.
|
||
|
||
Security impact
|
||
---------------
|
||
|
||
None.
|
||
|
||
Notifications impact
|
||
--------------------
|
||
|
||
None.
|
||
|
||
Other end user impact
|
||
---------------------
|
||
|
||
None.
|
||
|
||
Performance Impact
|
||
------------------
|
||
|
||
None.
|
||
|
||
Plugin impact
|
||
-------------
|
||
|
||
None.
|
||
|
||
Other deployer impact
|
||
---------------------
|
||
|
||
No impact. The feature was intended for organizing node lists (on UI mostly),
|
||
filtering and sorting nodes in more flexible way. So, labels data will not
|
||
go to deployment info for now.
|
||
|
||
Developer impact
|
||
----------------
|
||
|
||
None.
|
||
|
||
Infrastructure impact
|
||
---------------------
|
||
|
||
None.
|
||
|
||
|
||
Implementation
|
||
==============
|
||
|
||
Assignee(s)
|
||
-----------
|
||
|
||
Primary assignee:
|
||
|
||
* Julia Aranovich (jkirnosova@mirantis.com)
|
||
|
||
Developers:
|
||
|
||
* Julia Aranovich (jkirnosova@mirantis.com) - JS and Nailgun code
|
||
* Bogdan Dudko (bdudko@mirantis.com) - visual design
|
||
* Andrey Popovych (apopovych@mirantis.com) - CLI code
|
||
|
||
Mandatory Design Reviewers:
|
||
|
||
* Vitaly Kramskikh (vkramskikh@mirantis.com)
|
||
* Roman Prikhodchenko (rprikhodchenko@mirantis.com)
|
||
|
||
Approver:
|
||
|
||
* Sheena Gregson (sgregson@mirantis.com)
|
||
|
||
Work Items
|
||
----------
|
||
|
||
* Describe custom node labels management workflow.
|
||
* Modify DB structure and API to work with labels.
|
||
* Implement corresponding UI controls including tests coverage.
|
||
* Implement CLI functionality (CRUD operations).
|
||
|
||
|
||
Dependencies
|
||
============
|
||
|
||
* Node compact representation
|
||
https://blueprints.launchpad.net/openstack/?searchtext=node-list-view-modes
|
||
* Node list sorters and filters
|
||
https://blueprints.launchpad.net/openstack/?searchtext=node-list-sorters-and-filters
|
||
|
||
|
||
Testing
|
||
=======
|
||
|
||
* Custom node labels management in UI should be covered by functional tests.
|
||
* Python unit tests for the REST API and DB change are also required.
|
||
* Custom node labels management in CLI should be covered by unit tests.
|
||
|
||
Acсeptance Criteria
|
||
-------------------
|
||
|
||
* User can create, read, edit, remove custom node labels both from Fuel Web UI
|
||
and CLI.
|
||
* User can manage custom labels for a group of nodes both from Fuel Web UI
|
||
and CLI.
|
||
* Custom node labels are validated during creation or update, so user is not
|
||
able to assign invalid data to node.
|
||
* User can filter nodes in Fuel Web UI to show only nodes that are
|
||
characterized by specified custom parameters.
|
||
* User can sort list of nodes in Fuel Web UI to group them by specified
|
||
custom parameters.
|
||
|
||
|
||
Documentation Impact
|
||
====================
|
||
|
||
The documentation should cover how the end user experience has been changed.
|
||
|
||
|
||
References
|
||
==========
|
||
|
||
#fuel-ui on freenode
|