Change the naming scheme for MuranoPL plugins
Current naming scheme for classes defined in MuranoPL extension plugins is not consistent with the naming scheme for regular MuranoPL classes and packages. This spec addresses this by changing the scheme and proposing a fallback logic which will provide a backward compatibility for the existing MuranoPL applications targeting old plugins. Change-Id: I05da65257b0002a2ecafe2b680d9ee6495b06474
This commit is contained in:
Alexander Tivelkov
parent
553f3b9db1
commit
c041259a2a
|
|
@ -0,0 +1,228 @@
|
|||
..
|
||||
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||
License.
|
||||
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
|
||||
=============================================
|
||||
Change the naming scheme for MuranoPL plugins
|
||||
=============================================
|
||||
|
||||
https://blueprints.launchpad.net/murano/+spec/plugin-fqn-rename
|
||||
|
||||
Current naming scheme for classes defined in MuranoPL extension plugins is not
|
||||
consistent with the naming scheme for regular MuranoPL classes and packages.
|
||||
|
||||
This spec addresses this by changing the scheme and proposing a fallback logic
|
||||
which will provide a backward compatibility for the existing MuranoPL
|
||||
applications targeting old plugins.
|
||||
|
||||
|
||||
|
||||
Problem description
|
||||
===================
|
||||
|
||||
MuranoPL classes and packages should have globally unique FQNs to prevent
|
||||
potential name collisions when environment combines packages provided by
|
||||
different developers. Recommended approach here is to start the name of a
|
||||
package with a reversed Internet domain name given that the domain is
|
||||
controlled by the developer of the package or class (such approach is inspired
|
||||
by package naming rules of Java, see [1] for more details)
|
||||
|
||||
The examples of such class names may include:
|
||||
|
||||
* ``com.example.Foo`` - for demo applications and packages
|
||||
|
||||
* ``org.openstack.projectName.Foo`` - for applications and packages developed
|
||||
and maintained by the teams of official Openstack projects
|
||||
|
||||
* ``com.companyname.Foo`` - for applications and packages developed and
|
||||
maintained by a third party controlling the "companyname.com" domain name
|
||||
|
||||
* ``io.murano.Foo`` - for applications and packages developed and maintained
|
||||
by the core murano team as part of the murano project. So, ``io.murano`` is
|
||||
a preferred alias for longer ``org.openstack.murano`` FQN prefix.
|
||||
|
||||
However, currently this approach is not working for the classes defined by
|
||||
MuranoPL extension plugins, since all the names of these classes have to start
|
||||
with ``io.murano.extension`` prefix, as this is the requirement of the current
|
||||
plugin management system. This breaks the naming convention and introduces the
|
||||
possibility of name collision for plugin-defined classes.
|
||||
|
||||
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
Current plugin system is based on stevedore library [2]. So we are utilizing
|
||||
the concepts of `namespace` and `entry point name`. The namespace value
|
||||
identifies the consumer of the plugin, the MuranoPL class plugins are
|
||||
identified by the ``io.murano.extension`` stevedore namespace. Entry-point
|
||||
names are the suffixes of the declared class' FQNs: the plugin loader forms the
|
||||
actual FQN of the class by concatenating the stevedore namespace with entry
|
||||
point name. For example, Murano's demo plugin [3] (providing Glance API
|
||||
connectivity) declares the following stevedore-based extension:
|
||||
|
||||
::
|
||||
|
||||
[entry_points]
|
||||
io.murano.extensions =
|
||||
mirantis.example.Glance = murano_exampleplugin:GlanceClient
|
||||
|
||||
The developer's provided entry-point name is ``mirantis.example.Glance`` here,
|
||||
and the current plugin loader will concatenate it with the namespace name thus
|
||||
resulting in class ``io.murano.extensions.mirantis.example.Glance`` being
|
||||
loaded by the class loader.
|
||||
|
||||
It is proposed to get rid of the concatenation: the stevedore's namespace name
|
||||
should be used **only** to identify the type of the plugin, while the FQNs of
|
||||
its classes should be defined only by the names of the entry points. So, when
|
||||
this change is implemented the example above will load a class with an FQN
|
||||
``mirantis.example.Glance``, without the ``io.murano.extensions`` prefix.
|
||||
|
||||
After this change is implemented the developers of the plugin will be able to
|
||||
follow the regular naming rules of Murano. So, our example plugin will have to
|
||||
be renamed to ``com.example.mirantis.Glance`` etc - and it will not be part of
|
||||
the ``io.murano`` space, as this plugin is just an example and is not supposed
|
||||
to be part of the core murano.
|
||||
|
||||
|
||||
Backwards compatibility
|
||||
-----------------------
|
||||
|
||||
The proposed change will effectively rename all the classes defined in the
|
||||
existing plugins by removing the ``io.murano.extensions`` prefix from their
|
||||
names. These may (and will) break all the MuranoPL code which relies on these
|
||||
plugins.
|
||||
|
||||
To prevent this there should be a fallback logic implemented for the
|
||||
class loader. When a class being loaded by name is not found and the name
|
||||
starts with the ``io.murano.extensions`` prefix, there should be a second
|
||||
attempt to load it by a shortened name without a prefix. If such class is found
|
||||
and is loaded, a warning message should be logged to indicate that the plugin
|
||||
is outdated and has to be updated with appropriate naming schema.
|
||||
|
||||
note::
|
||||
This backwards-compatibility mode may be considered a way to deprecate the
|
||||
old plugin naming scheme. In several releases this fallback logic may be
|
||||
removed completely.
|
||||
|
||||
|
||||
Alternatives
|
||||
------------
|
||||
|
||||
We may postpone the change of the naming scheme till the next version of the
|
||||
plugin system is introduced, which will some different format of plugins and
|
||||
their content etc.
|
||||
|
||||
However postponing is bad, since the plugin development for murano is already
|
||||
active, and having inconsistently named classes makes a bad example in the
|
||||
community. Waiting for another cycle or two may greatly increase the number of
|
||||
such bad examples.
|
||||
|
||||
|
||||
|
||||
Data model impact
|
||||
-----------------
|
||||
|
||||
None
|
||||
|
||||
REST API impact
|
||||
---------------
|
||||
None
|
||||
|
||||
|
||||
Versioning impact
|
||||
-----------------
|
||||
|
||||
None
|
||||
|
||||
|
||||
Other end user impact
|
||||
---------------------
|
||||
|
||||
None
|
||||
|
||||
|
||||
Security impact
|
||||
---------------
|
||||
|
||||
Because of the proposed change it will be now possible to define classes having
|
||||
the names colliding with the Core Library and thus overriding the behavior of
|
||||
the standard murano classes.
|
||||
|
||||
This should not be allowed unless the deployer explicitly allows that in the
|
||||
configuration.
|
||||
|
||||
|
||||
Deployer impact
|
||||
---------------
|
||||
|
||||
Deployers will have to monitor the logs of Murano Engine for the Warning
|
||||
messages produced by the loading of outdated plugins in the backwards
|
||||
compatibility mode.
|
||||
|
||||
Developer impact
|
||||
----------------
|
||||
|
||||
Plugin developers will have to update their plugin according the the correct
|
||||
naming scheme.
|
||||
|
||||
Application developers using the plugins will have to rename the class usages
|
||||
in their MuranoPL code to use the new names.
|
||||
|
||||
|
||||
Murano-dashboard / Horizon impact
|
||||
---------------------------------
|
||||
|
||||
None
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
Assignee(s)
|
||||
-----------
|
||||
|
||||
Primary assignee:
|
||||
ativelkov
|
||||
|
||||
Other contributors:
|
||||
ksnihyr
|
||||
|
||||
|
||||
Work Items
|
||||
----------
|
||||
|
||||
* Modify the plugin loader
|
||||
|
||||
* Add backwards compatibility mode to the class loader
|
||||
|
||||
* Update existing plugins to utilize the proper naming schema
|
||||
|
||||
* Update the documentation
|
||||
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
None
|
||||
|
||||
|
||||
Testing
|
||||
=======
|
||||
|
||||
No new testing needed. Existing plugin-loading tests should be updated so no
|
||||
warnings are displayed.
|
||||
|
||||
|
||||
Documentation Impact
|
||||
====================
|
||||
|
||||
Plugin development manual has to be updated.
|
||||
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
#. https://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html
|
||||
#. http://docs.openstack.org/developer/stevedore/
|
||||
#. http://git.openstack.org/cgit/openstack/murano/tree/contrib/plugins/murano_exampleplugin/setup.cfg?h=stable/mitaka
|
||||
Loading…
Reference in New Issue