Magnum Labels Override¶
Problem Description¶
Magnum accepts labels at cluster or nodegroup creation in the format of key/value pairs. If no labels are provided, then:
Clusters inherit the labels already configured in the corresponding Cluster Template
Nodegroups inherit the labels already configured in the Cluster where they belong.
In case labels are provided at cluster/nodegroup creation, labels configured in the levels above are ignored.
This behavior, forces users to provide the full set of configured labels in order to change a subset of them.
At the same time, it is very difficult for operators to keep track of the user provided labels when a problem occurs.
This proposal tries to address the problem described above.
Use Cases¶
Below are some of the use cases:
As a user, when creating a new cluster I want to be able to override some labels without having to provide all the labels that my cluster template contains.
As a user, while creating a nodegroup I want to be able to override some labels without having to provide all the labels that my cluster contains.
As an operator, I want to be able to properly track the labels that the user provided while creating a cluster or nodegroup.
Proposed Changes¶
In the scope of this spec, by using the term “parent labels”:
For clusters, we refer to the labels configured at cluster template level.
For nodegroups, we refer to labels configured in the cluster level.
The term “provided labels” refers to the labels provided by the client at cluster or nodegroup creation time.
The proposed change includes:
Introducing a new boolean flag, which will indicate whether the provided labels will be used to override specific values of the parent labels or replacing them completely, which is the current behaviour.
Three new fields will be added in the GET response for clusters and nodegroups. The fields will contain the differences between the current labels and the parent labels. The fields will be generated by the Magnum API when showing a cluster or nodegroup.
Check section REST API Impact for more details.
Alternatives¶
An alternative approach to this proposal would be the one described in the
following change [1]. The idea would be to append the + or - symbols
when passing labels to the API. The meaning is the following:
* + = merge this label to the already configured labels
* - = do not inherit the label
This alternative is considered to be more error prone and the code changes are more complicated than the proposed solution.
Another alternative, would be to persist the labels used to override specific parent labels in a new DB field. This would allow, operators to properly track the client’s input. On the downside, with this approach, we would have to adapt the code wherever the labels are currently used to respect the inheritance.
The proposed solution was chosen over its alternatives because it:
minimizes the impact on the current functionality
eliminates the need for online data migrations
makes the functionality backwards compatible
Data Model Impact¶
N/A
REST API Impact¶
The label inheritance to be respected is:
Cluster Template -> Cluster -> Nodegroup
A new boolean flag will be added to the API. The flag’s proposed name is
--merge-labels. The default value of this flag will be False meaning
that we will maintain as default the current functionality:
* If labels are provided then the parent labels will be ignored.
* If labels are not provided then the parent labels will be copied over to
the object that is being created.
In case the flag is True, the API will retrieve the object’s parent labels
and update the dictionary with the provided labels.
Consider a scenario where the following exists:
cluster_template.labels = {'label1': 'value1', 'label2': 'value2'}
A cluster is created using this cluster template with the following command:
openstack coe cluster create --cluster-template .. --labels label1=value3 \
--labels label4=value4 --merge-labels <cluster_name>
The resulting labels that will be stored in the cluster and the default nodegroups will be:
labels = {'label1': 'value3', 'label2': 'value2', 'label4': 'value4'}
Now consider adding a new nodegroup to that cluster:
openstack coe nodegroup create --labels label4=label5 --merge-labels \
<cluster_name> ng1
The resulting labels that will be stored in the nodegroup will be:
labels = {'label1': 'value3', 'label2': 'value2', 'label4': 'value5'}
If the flag is not provided while creating a nodegroup:
openstack coe nodegroup create --labels label4=label5 <cluster_name> ng2
The current functionality will be used and the resulting labels stored in the nodegroup will be:
labels = {'label4': 'value5'}
This change leads to a minor version increase in the Magnum API.
The post methods of Clusters and Nodegroups APIs will be adapted as shown below:
* Old APIs will not accept the --merge-labels flag.
* New APIs will allow clients to provide the --merge-labels flag with
a default value of `False``.
The GET methods of Clusters and Nodegroups APIs will be adapted to show the
differences between the provided and parent labels. The proposed fields are:
* labels_overridden: labels that exist in both parent and object labels but
have different value
* labels_added: labels that do not exist in the parent labels and were
added in the object
* labels_skipped: labels that exist in the parent dict but do not exist in
the object's labels. Specifically, this field will be
used when the user did not provide the --merge-labels
(used the current functionality) and did not provide some
of the labels that exist in the parent.
CLI Impact¶
The OpenStack client commands will be adapted:
create cluster: create cluster overriding a specific set of labels:
openstack coe cluster create --merge-labels --labels label1=value1 ...
create nodegroup: create a nodegroup overriding a specific set of labels:
openstack coe nodegroup create --merge-labels --labels label1=value1 ...
Known Limitations¶
With the proposed implementation, users will not be able to remove a configured label. Although it would be possible by adding a –remove-label option, the result of this action is not clear. Meaning that from user/client perspective, it is not clear if the label will not be used or its default value will be propagated to Heat.
Other Implementation Options¶
See Alternatives.
Security Impact¶
N/A
Notifications Impact¶
N/A
Other End User Impact¶
Users will be able to provide labels in a new way, using this functionality. The old way of providing labels (via –labels) will still be supported.
Implementation¶
The corresponding story in storyboard is 2007515 [2].
The implementation tasks can be found below:
New microversion in the cluster and nodegroup API and the relevant validations.
Adapt the client, adding the new functionality to the openstack client.
Assignee(s)¶
ttsiouts
Documentation Impact¶
Magnum documentation for labels will be adapted to describe the new way of overriding labels.
The API reference guide should be updated accordingly to include the new –merge-labels flag..
