Merge "Documentation for package type plugins"
This commit is contained in:
commit
5340ed8e0a
doc/source/draft
contributor-guide
index.rst@ -1,8 +0,0 @@
|
||||
.. _plugin-development:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
===================
|
||||
Developing a plugin
|
||||
===================
|
12
doc/source/draft/contributor-guide/plugins.rst
Normal file
12
doc/source/draft/contributor-guide/plugins.rst
Normal file
@ -0,0 +1,12 @@
|
||||
.. _plugins:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
===============
|
||||
Murano plug-ins
|
||||
===============
|
||||
|
||||
.. include:: plugins/muranopl_extensions.rst
|
||||
|
||||
.. include:: plugins/package_type_plugins.rst
|
@ -0,0 +1,8 @@
|
||||
.. _muranopl_extensions:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
|
||||
MuranoPL extension plug-ins
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
@ -0,0 +1,234 @@
|
||||
.. _package_type_plugins:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
|
||||
MuranoPL package type plug-ins
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The only package type natively supported by Murano is MuranoPL. However, it is
|
||||
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
|
||||
used to run Murano API and Murano Engine. For multi-node Murano deployments,
|
||||
plug-ins need to be installed on each node.
|
||||
|
||||
To associate a plug-in with a particular package format, it needs to have a
|
||||
special record in `[entry_points]` section of setup.cfg file:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
io.murano.plugins.packages =
|
||||
Name/Version = namespace:Class
|
||||
|
||||
For example:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[entry_points]
|
||||
io.murano.plugins.packages =
|
||||
Cloudify.TOSCA/1.0 = murano_cloudify_plugin.cloudify_tosca_package:CloudifyToscaPackage
|
||||
|
||||
|
||||
This declaration maps particular pair of format-name/version to Python class
|
||||
that implements Package API interface for the package type. It is possible
|
||||
to specify several different format names or versions and map them to single
|
||||
or different Python classes. For example, it is possible to specify
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[entry_points]
|
||||
io.murano.plugins.packages =
|
||||
Cloudify.TOSCA/1.0 = murano_cloudify_plugin.cloudify_tosca_package:CloudifyToscaPackage
|
||||
Cloudify.TOSCA/1.1 = murano_cloudify_plugin.cloudify_tosca_package:CloudifyToscaPackage
|
||||
Cloudify.TOSCA/2.0 = murano_cloudify_plugin.cloudify_tosca_package:CloudifyToscaPackage_v2
|
||||
|
||||
.. note::
|
||||
|
||||
A single Python plug-in package may contain several Murano plug-ins
|
||||
including of different types. For example, it is possible to combine
|
||||
MuranoPL extension and package type plug-ins into a single package.
|
||||
|
||||
|
||||
Tooling for package preparation
|
||||
-------------------------------
|
||||
|
||||
Some package formats may require additional tooling to prepare package ZIP
|
||||
archive of desired structure. In such cases it is expected that those tools
|
||||
will be provided by plug-in authors either as part of the same Python package
|
||||
(by exposing additional shell entry points) or as a separate package or
|
||||
distribution.
|
||||
|
||||
The only two exceptions to this rule are native MuranoPL packages and HOT
|
||||
packages that are built into Murano (there is no need to install additional
|
||||
plug-ins for them). Tooling for those two formats is a part of
|
||||
python-muranoclient.
|
||||
|
||||
|
||||
Package API interface reference
|
||||
-------------------------------
|
||||
|
||||
Plug-ins expose API for the rest of Murano to interact with the package
|
||||
by implementing `murano.packages.package.Package` interface.
|
||||
|
||||
|
||||
Class initializer:
|
||||
|
||||
`def __init__(self, format_name, runtime_version, source_directory, manifest):`
|
||||
|
||||
|
||||
* **format_name**: name part of the format identifier (string)
|
||||
* **runtime_version**: version part of the format identifier (instance of
|
||||
semantic_version.Version)
|
||||
* **source_directory**: path to the directory where package content was
|
||||
extracted (string)
|
||||
* **manifest**: contents of the manifest file (string->string dictionary)
|
||||
|
||||
**Note**: implementations must call base class (`Package`) initializer
|
||||
passing the first three of these arguments.
|
||||
|
||||
Abstract properties that must be implemented by the plug-in:
|
||||
|
||||
`def full_name(self):`
|
||||
|
||||
* Fully qualified name of the package. Must be unique within package
|
||||
scope of visibility (string)
|
||||
|
||||
`def version(self):`
|
||||
|
||||
* Package version (not to confuse with format version!). An instance of
|
||||
`semantic_version.Version`
|
||||
|
||||
`def classes(self):`
|
||||
|
||||
* List (or tuple) of MuranoPL class names (FQNs) that package contains
|
||||
|
||||
`def requirements(self):`
|
||||
|
||||
* Dictionary of requirements (dependencies on other packages) in a form
|
||||
of key-value mapping from required package FQN string to SemVer
|
||||
version range specifier (instance of semantic_version.Spec or string
|
||||
representation supported by Murano versioning scheme)
|
||||
|
||||
`def package_type(self):`
|
||||
|
||||
* Package type: "Application" or "Library"
|
||||
|
||||
`def display_name(self):`
|
||||
|
||||
* Human-readable name of the package as presented to the user (string)
|
||||
|
||||
`def description(self):`
|
||||
|
||||
* Package description (string or None)
|
||||
|
||||
`def author(self):`
|
||||
|
||||
* Package author (string or None)
|
||||
|
||||
`def supplier(self):`
|
||||
|
||||
* Package supplier (string or None)
|
||||
|
||||
`def tags(self):`
|
||||
|
||||
* List or tags for the package (list of strings)
|
||||
|
||||
`def logo(self):`
|
||||
|
||||
* Package (application) logo file content (str or None)
|
||||
|
||||
`def supplier_logo(self):`
|
||||
|
||||
* Package (application) supplier logo file content (str or None)
|
||||
|
||||
`def ui(self):`
|
||||
|
||||
* YAML-encoded string containing application's form definition (string or
|
||||
None)
|
||||
|
||||
Abstract methods that must be implemented by the plug-in:
|
||||
|
||||
`def get_class(self, name):`
|
||||
|
||||
* Returns string containing MuranoPL code (YAML-encoded string) for the
|
||||
class whose fully qualified name is in "name" parameter (string)
|
||||
|
||||
`def get_resource(self, name):`
|
||||
|
||||
* Returns path for resource file whose name is in "name" parameter (string)
|
||||
|
||||
|
||||
Properties that can be overridden in the plug-in:
|
||||
|
||||
`def format_name(self):`
|
||||
|
||||
* Canonical format name for the plug-in. Usually the same value that was
|
||||
passed to class initializer
|
||||
|
||||
|
||||
`def runtime_version(self):`
|
||||
|
||||
* Format version. Usually the same value that was passed to class
|
||||
initializer (semantic_version.Version)
|
||||
|
||||
`def blob(self):`
|
||||
|
||||
* Package file (.zip) content (str)
|
||||
|
||||
|
||||
PackageBase class
|
||||
-----------------
|
||||
|
||||
Usually, there is no need to manually implement all the methods and properties
|
||||
described. There is a `murano.packages.package.PackageBase` class that provides
|
||||
typical implementation of most of required properties by obtaining
|
||||
corresponding value from manifest file.
|
||||
|
||||
When inheriting from PackageBase class, plug-in remains responsible for
|
||||
implementation of:
|
||||
|
||||
* `ui` property
|
||||
* `classes` property
|
||||
* `get_class` method
|
||||
|
||||
This allows plug-in developers to concentrate on dynamic aspects of the package
|
||||
type plug-in while keeping all static aspects (descriptions, logos and so on)
|
||||
consistent across all package types (at least those who inherit from
|
||||
`PackageBase`).
|
@ -91,7 +91,7 @@ Contributing
|
||||
|
||||
contributor-guide/how_to_contribute
|
||||
contributor-guide/dev_guidelines
|
||||
contributor-guide/plugin_development
|
||||
contributor-guide/plugins
|
||||
contributor-guide/deploy_local_dev_env
|
||||
contributor-guide/testing
|
||||
contributor-guide/doc_guidelines
|
||||
|
Loading…
x
Reference in New Issue
Block a user