Merge "[Docs] Murano plug-ins"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
984ed67978
@ -7,6 +7,120 @@
|
||||
Murano plug-ins
|
||||
===============
|
||||
|
||||
Murano plug-ins help to extend the capability of murano.
|
||||
|
||||
Murano plug-in types
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
There are two types of murano plug-ins which serve different purposes:
|
||||
|
||||
* Extend murano Core Library by implementing additional functionality.
|
||||
* Add new package type classes.
|
||||
|
||||
.. include:: plugins/muranopl_extensions.rst
|
||||
|
||||
.. include:: plugins/package_type_plugins.rst
|
||||
|
||||
Creating a Murano plug-in
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Murano plug-in is a setuptools-compliant python package with ``setup.py`` and
|
||||
all other necessary files. For more information about defining stevedore
|
||||
plug-ins, see `stevedore documentation
|
||||
<http://docs.openstack.org/developer/stevedore/>`_.
|
||||
|
||||
The structure of the demo application package
|
||||
---------------------------------------------
|
||||
|
||||
The package must meet the following requirements:
|
||||
|
||||
* It must be a ZIP archive.
|
||||
* The root folder of the archive must contain a ``manifest.yaml`` file.
|
||||
* The manifest must be a valid YAML file representing key-value associative
|
||||
array.
|
||||
* The manifest should contain a *Format* key, that is, a format identifier. If
|
||||
it is not present, "MuranoPL/1.0" is used.
|
||||
|
||||
Murano uses the *Format* attribute of the manifest file to find an appropriate
|
||||
plug-in for a particular package type. All interactions between the rest of
|
||||
Murano and package file contents are done through the plug-in interface alone.
|
||||
|
||||
Because Murano never directly accesses files inside the packages, it is
|
||||
possible for plug-ins to dynamically generate MuranoPL classes on the fly.
|
||||
Those classes will be served as adapters between Murano and third-party systems
|
||||
responsible for deployment of particular package types. Thus, for Murano all
|
||||
packages remain to be of MuranoPL type though some of them are "virtual".
|
||||
|
||||
The format identifier has the following format: ``Name/Version``.
|
||||
For example, ``Heat.HOT/1.0``. If name is not present, it is assumed to be
|
||||
``MuranoPL`` (thus ``1.0`` becomes ``MuranoPL/1.0``). Version strings are in
|
||||
SemVer three-component format (major.minor.patch). Missing version components
|
||||
are assumed to be zero (thus 1.0 becomes 1.0.0).
|
||||
|
||||
Installing a plug-in
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To use a plug-in, install it on murano nodes in the same Python environment
|
||||
with murano engine service.
|
||||
|
||||
To install a plug-in:
|
||||
|
||||
#. Execute the plug-in setup script.
|
||||
|
||||
Alternatively, use a package deployment tool, such as pip:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cd plugin_dir
|
||||
pip install .
|
||||
|
||||
#. Restart murano engine. After that, it will be possible to upload and deploy
|
||||
the applications that use the capabilities that a plug-in provides.
|
||||
|
||||
Plug-in versioning
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Plug-ins located in Murano repository have the same version as Murano.
|
||||
Therefore, to use a specific version of such plug-in, checkout to this version.
|
||||
Then specify the version of plug-in classes in your application's manifest file
|
||||
as usual:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
Require:
|
||||
murano.plugins.example: 2.0.0
|
||||
|
||||
It should be standard SemVer format version string consisting of three parts:
|
||||
Major.Minor.Patch. For more information about versioning, refer to
|
||||
:ref:`versioning`.
|
||||
|
||||
.. note::
|
||||
Enable Glare to use versioning.
|
||||
|
||||
Organization
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
Documentation helps users understand what your plug-in does. For plug-ins
|
||||
located in the Murano repository, create a ``README.rst`` file in the main
|
||||
folder of the plug-in. The ``README.rst`` file may contain information about
|
||||
the plug-in and an installation guide.
|
||||
|
||||
Code
|
||||
----
|
||||
|
||||
The code of your plug-in may be located in the following repositories:
|
||||
|
||||
* Murano repository. In this case, the plug-in should be located in the
|
||||
``murano/contrib/plugins`` folder.
|
||||
|
||||
* A separate repository. In this case, create your own project.
|
||||
|
||||
Bugs
|
||||
----
|
||||
|
||||
All bugs for specific plug-ins are reported in their projects. Bugs related
|
||||
to plug-ins located in Murano repository should be reported in the `Murano
|
||||
<https://bugs.launchpad.net/murano/>`_ project.
|
||||
|
||||
@ -6,3 +6,42 @@
|
||||
|
||||
MuranoPL extension plug-ins
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Murano plug-ins allow extending MuranoPL with new classes. Therefore, using
|
||||
such plug-ins applications with MuranoPL format, you access some additional
|
||||
functionality defined in a plug-in. For example, the Magnum plug-in, which
|
||||
allows murano to deploy applications such as Kubernetes using the capabilities
|
||||
of the Magnum client.
|
||||
|
||||
MuranoPL extension plug-ins can be used for the following purposes:
|
||||
|
||||
* Providing interaction with external services.
|
||||
|
||||
For example, you want to interact with the OpenStack Image service to get
|
||||
information about images suitable for deployment. A plug-in may request image
|
||||
data from glance during deployment, performing any necessary checks.
|
||||
|
||||
* Enabling connections between murano applications and external hardware
|
||||
|
||||
For example, you have an external load balancer located on a powerful
|
||||
hardware and you want your applications launched in OpenStack to use that
|
||||
load balancer. You can write a plug-in that interacts with the load balancer
|
||||
API. Once done, add new apps to the pool of your load balancer or make any
|
||||
other configurations from within your application definition.
|
||||
|
||||
* Extending Core Library class functionality, which is responsible for creating
|
||||
networks, interaction with murano-agent, and others
|
||||
|
||||
For example, you want to create networks with special parameters for all of
|
||||
your applications. You can just copy the class that is responsible for
|
||||
network management from the Murano Core library, make the desired
|
||||
modification, and load the new class as a plug-in. Both classes will be
|
||||
available, and it is up to you to decide which way to create your networks.
|
||||
|
||||
* Optimization of frequently used operations. Plug-in classes are written in
|
||||
Python, therefore, the opportunity for improvement is significant.
|
||||
|
||||
Murano provides a number of optimization opportunities depending on the
|
||||
improvement needs. For example, classes in the Murano Core Library can be
|
||||
rewritten in C and used from Python code to improve their performance in
|
||||
particular use cases.
|
||||
|
||||
@ -12,37 +12,6 @@ possible to extend Murano with support for other formats of application
|
||||
definitions. TOSCA CSARs and HOT templates are the two examples of alternate
|
||||
ways to define applications.
|
||||
|
||||
Package structure
|
||||
-----------------
|
||||
|
||||
The only assumptions Murano makes about package format are:
|
||||
|
||||
* It is a ZIP archive
|
||||
* There is a ``manifest.yaml`` file in the root folder of that archive
|
||||
* Manifest must be a valid YAML file representing key-value associative array
|
||||
* There should be a "Format" key in manifest - format identifier. If it is
|
||||
not present, "MuranoPL/1.0" is used.
|
||||
|
||||
Murano uses the "Format" attribute of the manifest file to find an appropriate
|
||||
plug-in for a particular package type. All interactions between the rest of
|
||||
Murano and package file contents are done through the plug-in interface alone.
|
||||
|
||||
Because Murano never directly accesses files inside the packages, it is
|
||||
possible for plug-ins to dynamically generate MuranoPL classes on the fly.
|
||||
Those classes will be served as adapters between Murano and 3rd party systems
|
||||
responsible for deployment of particular package types. Thus for Murano all
|
||||
packages remain to be of MuranoPL type though some of them are "virtual".
|
||||
|
||||
The format identifier has the following format: `Name/Version`.
|
||||
For example, "Heat.HOT/1.0". If name is not present, it is assumed to be
|
||||
"MuranoPL" (thus "1.0" becomes "MuranoPL/1.0"). Version strings are in SemVer
|
||||
3-component format (major.minor.patch). Missing version components are assumed
|
||||
to be zero (thus 1.0 becomes 1.0.0).
|
||||
|
||||
|
||||
Package type plug-ins
|
||||
---------------------
|
||||
|
||||
Package types plug-ins are normal Python packages that can be distributed
|
||||
through PyPI and installed using :command:`pip` or its alternatives. It is
|
||||
important that the plug-in be installed to the same Python instance that is
|
||||
|
||||
Loading…
Reference in New Issue
Block a user