Merge "[Docs] Murano plug-ins"

doc/source/draft/contributor-guide/plugins.rst

@@ -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.

doc/source/draft/contributor-guide/plugins/muranopl_extensions.rst

@@ -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.

doc/source/draft/contributor-guide/plugins/package_type_plugins.rst

@@ -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