Creates a new Plugin Development Guide
Since Fuel 6.0 supports Pluggable architecture, a separate Guide is created to describe the following: * how to install a plugin * example plugins * how to create a plugin * how plugin UI elements should look like Links to plug-in-related CRs: * Certification issue (to be posted to Plug-in DevGuide): https://review.openstack.org/#/c/140421/ * User Guide instructions for installing plug-ins: https://review.openstack.org/#/c/130506/ * Update Terminology articles https://review.openstack.org/#/c/140350/ Change-Id: I78668b7bdc0e1b4f09244146a789bb12c921100c Closes-Bug: 1397889
This commit is contained in:
irina povolotskaya
Dmitry Borodaenko
parent
eb54a6ef21
commit
dd0dfcb4b7
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 77 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
|
|
@ -13,6 +13,7 @@ Documentation
|
|||
operations
|
||||
virtualbox
|
||||
reference-architecture
|
||||
plugin-dev
|
||||
terminology
|
||||
file-ref
|
||||
release-notes
|
||||
|
|
|
|||
|
|
@ -0,0 +1,4 @@
|
|||
.. include:: /pages/plugin-dev/010-fuel-plugin-intro.rst
|
||||
.. include:: /pages/plugin-dev/040-install-plugin.rst
|
||||
.. include:: /pages/plugin-dev/plugin-cert.rst
|
||||
.. include:: /pages/plugin-dev/000-plugins-faq.rst
|
||||
|
|
@ -64,6 +64,12 @@ for demonstration and evaluation purposes.
|
|||
A deep dive into the structure of the Mirantis OpenStack environment,
|
||||
network considerations, and deployment options.
|
||||
|
||||
|
||||
:ref:`plugin-dev` `(pdf) <pdf/Mirantis-OpenStack-6.0-Fuel-Plug-in-Guide.pdf>`__
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Instructions on creating, installing and certifying plug-ins for Fuel.
|
||||
|
||||
:ref:`terminology-ref` `(pdf) <pdf/Mirantis-OpenStack-6.0-Terminology-Reference.pdf>`__
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,98 @@
|
|||
.. _000-plugins-faq:
|
||||
|
||||
FAQ
|
||||
===
|
||||
|
||||
Where can I find Fuel Plug-in Builder source code?
|
||||
--------------------------------------------------
|
||||
|
||||
**fuel-plugin-builder** is located in `fuel-plugins <https://github.com/stackforge/fuel-plugins/tree/master/fuel_plugin_builder>`_ repository.
|
||||
|
||||
|
||||
Are there any plug-ins examples?
|
||||
--------------------------------
|
||||
|
||||
The `Fuel plug-ins <https://github.com/stackforge/fuel-plugins>`_ repository has
|
||||
several useful examples.
|
||||
|
||||
How can I reuse Puppet modules from Fuel?
|
||||
-----------------------------------------
|
||||
|
||||
According to the design, every plug-in should have all necessary components to be then deployed.
|
||||
This means, every plug-in should have its own copy of Fuel Puppet modules.
|
||||
If you do not want to keep copy of Fuel library manifests in your repository,
|
||||
you can use **pre_build_hook** to download the required modules during the
|
||||
plug-in build. To do that, add the following code into your hook:
|
||||
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
#!/bin/bash
|
||||
set -eux
|
||||
|
||||
ROOT="$(dirname `readlink -f $0`)"
|
||||
MODULES="${ROOT}"/deployment_scripts/puppet/modules
|
||||
mkdir -p "${MODULES}"
|
||||
REPO_PATH='https://github.com/stackforge/fuel-library/tarball/f43d885914d74fbd062096763222f350f47480e1'
|
||||
RPM_REPO="${ROOT}"/repositories/centos/
|
||||
DEB_REPO="${ROOT}"/repositories/ubuntu/
|
||||
|
||||
wget -qO- "${REPO_PATH}" | \
|
||||
tar -C "${MODULES}" --strip-components=3 -zxvf - \
|
||||
stackforge-fuel-library-f43d885/deployment/puppet/{inifile,stdlib}
|
||||
|
||||
The code then copies *inifile* and *stdlib* modules from **fuel-library** repository.
|
||||
|
||||
.. warning::
|
||||
|
||||
To reuse existing Puppet manifests you can also specify several Puppet
|
||||
modules in your task with colon separator: for example,
|
||||
*puppet_modules: "puppet/modules:/etc/puppet/modules"*.
|
||||
Note that we do not
|
||||
recommend using this approach, because Fuel puppet modules can be changed
|
||||
during OpenStack update procedure; this can lead to compatibility failures.
|
||||
|
||||
How can I download the packages which are required for a plug-in?
|
||||
-----------------------------------------------------------------
|
||||
|
||||
Use **wget** in your **pre_build_hook** script to download packages
|
||||
in the required directories:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
#!/bin/bash
|
||||
set -eux
|
||||
|
||||
ROOT="$(dirname `readlink -f $0`)"
|
||||
RPM_REPO="${ROOT}"/repositories/centos/
|
||||
DEB_REPO="${ROOT}"/repositories/ubuntu/
|
||||
|
||||
wget -P "${RPM_REPO}" http://mirror.fuel-infra.org/fuel-plugins/6.0/centos/glusterfs-3.5.2-1.mira2.x86_64.rpm
|
||||
wget -P "${DEB_REPO}" http://mirror.fuel-infra.org/fuel-plugins/6.0/ubuntu/glusterfs-client_3.5.2-4_amd64.deb
|
||||
|
||||
It downloads two packages in your plug-in's directories before Fuel Plugin Builder starts
|
||||
building repositories.
|
||||
|
||||
Why is there no /etc/astute.yaml file, when I run pre_deployment task?
|
||||
----------------------------------------------------------------------
|
||||
|
||||
If you have task with "stage: pre_deployment" parameter set, you will not find
|
||||
**/etc/astute.yaml** file on the target node during the task execution.
|
||||
The file **/etc/astute.yaml** is a symlink that is created before Fuel
|
||||
deploys a role.
|
||||
|
||||
Target node can have several roles and each role contains its own file with
|
||||
deployment data.
|
||||
|
||||
Here is the example of a node with
|
||||
ID 2 and two roles, Controller and Cinder:
|
||||
|
||||
::
|
||||
|
||||
root@node-2:~# ls -l /etc/ | grep yaml
|
||||
-rw------- 1 root root 8712 Nov 19 12:48 controller.yaml
|
||||
-rw------- 1 root root 8700 Nov 19 12:48 cinder.yaml
|
||||
|
||||
Let's assume that we need deployment data file for Controller role.
|
||||
|
||||
We can use '/etc/controller.yaml' file directly in deployment script.
|
||||
|
|
@ -0,0 +1,50 @@
|
|||
|
||||
.. raw:: pdf
|
||||
|
||||
PageBreak
|
||||
|
||||
.. _010-fuel-plugin-intro:
|
||||
|
||||
What Is Pluggable Architecture
|
||||
==============================
|
||||
|
||||
Beginning with Mirantis OpenStack 6.0, our cloud deployment manager, Fuel, features the ability to install plug-ins when you deploy your environment. Plug-ins are downloadable software components that extend the functionality of your environments in a flexible, repeatable and reliable manner.
|
||||
There is no need to install drivers and patches manually after Fuel deploys your cloud - plug-ins do this for you.
|
||||
|
||||
What can plug-ins do for me?
|
||||
----------------------------
|
||||
|
||||
Plug-ins allow you to install and configure additional functionality for your cloud, such as additional storage types and networking functionality. For example, a Load Balancing as a Service (LBaaS) plug-in allows you to add network load balancing functionality to your cloud so that incoming traffic can be spread across multiple nodes. Or you might want to use a GlusterFS plug-in so that you can use a Gluster file system as backend storage for blocks (Cinder).
|
||||
|
||||
What kinds of plug-ins are available?
|
||||
-------------------------------------
|
||||
|
||||
Plug-ins come in the following flavors:
|
||||
|
||||
* Compute - extend Nova
|
||||
|
||||
* Network - extend Neutron
|
||||
|
||||
* Storage - extend Cinder and Glance
|
||||
|
||||
* Operations - extend monitoring and logging
|
||||
|
||||
Plug-ins are also divided into two categories:
|
||||
|
||||
* *Certified*: certified plug-ins are thoroughly reviewed, tested and supported by Mirantis.
|
||||
|
||||
* *Non-Certified*: non-certified plug-ins are reviewed by Mirantis, but not supported or guaranteed.
|
||||
|
||||
All plug-ins, both certified and non-certified are digitally signed and hosted by Mirantis.
|
||||
|
||||
For more information about Fuel plug-ins certification and proposed
|
||||
workflow, see :ref:`plugin-cert`.
|
||||
|
||||
.. raw:: pdf
|
||||
|
||||
PageBreak
|
||||
|
||||
.. include:: /pages/plugin-dev/020-fuel-plugin-dev.rst
|
||||
.. include:: /pages/plugin-dev/030-fuel-plugin-dev-ui.rst
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,660 @@
|
|||
.. _020-fuel-plugin-dev:
|
||||
|
||||
Developing a plug-in for Fuel
|
||||
=============================
|
||||
|
||||
This section provides step-by-step instructions
|
||||
that will help you to develop your own
|
||||
plug-in.
|
||||
|
||||
|
||||
Preparing your environment
|
||||
--------------------------
|
||||
|
||||
To prepare your environment for plug-in development, follow these steps:
|
||||
|
||||
#. Install the standard Linux development tools.
|
||||
If you have Ubuntu 12.04.2 LTS, run:
|
||||
|
||||
::
|
||||
|
||||
sudo apt-get install createrepo rpm dpkg-dev
|
||||
|
||||
If you have Centos 6.5, run:
|
||||
|
||||
::
|
||||
|
||||
yum install createrepo rpm dpkg-devel
|
||||
|
||||
#. Install the Fuel Plug-in Builder (*fuel-plugin-builder*). To do that, follow these steps:
|
||||
|
||||
* Install pip
|
||||
|
||||
::
|
||||
|
||||
easy_install pip
|
||||
|
||||
|
||||
* Install Fuel Plug-in Builder:
|
||||
|
||||
::
|
||||
|
||||
pip install fuel-plugin-builder
|
||||
|
||||
.. _create-build-plugin:
|
||||
|
||||
Creating your plug-in
|
||||
---------------------
|
||||
|
||||
To create your Fuel plug-in, follow these steps:
|
||||
|
||||
#. Generate the plug-in structure
|
||||
|
||||
::
|
||||
|
||||
fpb --create fuel_plugin_name
|
||||
|
||||
#. Your plug-in must have the following format:
|
||||
|
||||
::
|
||||
|
||||
fuel_plugin_name/
|
||||
├── deployment_scripts
|
||||
│ └── deploy.sh
|
||||
├── environment_config.yaml
|
||||
├── metadata.yaml
|
||||
├── pre_build_hook
|
||||
├── repositories
|
||||
│ ├── centos
|
||||
│ └── ubuntu
|
||||
└── tasks.yaml
|
||||
|
||||
|
||||
* **tasks.yaml** - specify when, where and how to run your scripts.
|
||||
|
||||
* **metadata.yaml** - set name, version, compatibility for your plug-in.
|
||||
|
||||
* **environment_config.yaml** - set plug-in-specific parameters, which user can configure on the **Settings** tab of the Fuel web UI.
|
||||
|
||||
* **deployment_scripts** - directory where you can add your bash script or puppet manifests.
|
||||
|
||||
* **repositories** - add Ubuntu or CentOS packages which are required for your plug-in.
|
||||
|
||||
#. Build your plug-in:
|
||||
|
||||
::
|
||||
|
||||
fpb --build fuel_plugin_name
|
||||
|
||||
After your plug-in is built, you can see it in your plug-in's directory;
|
||||
for example, `fuel_plugin_name/fuel_plugin_name-0.1.0.fp` can be used.
|
||||
|
||||
For instructions on installing your plug-in, see :ref:`040-install-plugin`.
|
||||
|
||||
|
||||
Plug-in structure details
|
||||
-------------------------
|
||||
|
||||
tasks.yaml
|
||||
++++++++++
|
||||
|
||||
By default, Fuel Plug-in Builder generates two tasks:
|
||||
|
||||
- The first one runs a *deploy.sh* bash script that is located in *deployment_scripts* directory;
|
||||
this task is applied only on nodes with Controller role.
|
||||
|
||||
- The second task creates '/tmp/plugin.all' file that contains 'all' text;
|
||||
this task is applied to all nodes in the environment.
|
||||
|
||||
Each task has a 'stage' parameter which tells when to run a particular task;
|
||||
'stage' can have either 'post_deployment' or 'pre_deployment' value.
|
||||
|
||||
- *post_deployment* - run task when deployment of entire environment
|
||||
is completed.
|
||||
|
||||
- *pre_deployment* - run task when deployment is started before
|
||||
OpenStack node roles are deployed.
|
||||
|
||||
For each task, you must also specify execution 'timeout' in seconds, otherwise,
|
||||
the deployment will fail if timeout expires.
|
||||
|
||||
Fuel supports two types of plug-ins, `shell` and `puppet`: the first one runs
|
||||
the specified shell command, the second applies Puppet manifests.
|
||||
|
||||
Example of `shell` tasks:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# This tasks will be applied on controller nodes,
|
||||
# here you can also specify several roles, for example
|
||||
# ['cinder', 'compute'] will be applied only on
|
||||
# cinder and compute nodes
|
||||
- role: ['controller']
|
||||
stage: post_deployment
|
||||
type: shell
|
||||
parameters:
|
||||
cmd: ./deploy.sh
|
||||
timeout: 42
|
||||
# Task is applied for all roles
|
||||
- role: '*'
|
||||
stage: pre_deployment
|
||||
type: shell
|
||||
parameters:
|
||||
cmd: echo all > /tmp/plugin.all
|
||||
timeout: 42
|
||||
|
||||
Task with *puppet* allows you
|
||||
to apply your own Puppet manifests on OpenStack nodes.
|
||||
For more information, see :ref:`Puppet in Fuel <puppet-fuel>` section.
|
||||
|
||||
To do that, add your *site.pp* file in
|
||||
*deployment_scripts/puppet/manifests/*
|
||||
directory. Then put all required modules
|
||||
in *deployment_scripts/puppet/modules* directory.
|
||||
|
||||
- *puppet_manifest* - specify directory path
|
||||
for your manifest relative to **deployment_scripts**.
|
||||
|
||||
- *puppet_modules* - specify directory path
|
||||
for your modules relative to **deployment_scripts**.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Deployment will be applied on controllers only
|
||||
- role: ['controller']
|
||||
stage: post_deployment
|
||||
type: puppet
|
||||
parameters:
|
||||
puppet_manifest: puppet/manifests/site.pp
|
||||
puppet_modules: puppet/modules
|
||||
timeout: 360
|
||||
|
||||
environment_config.yaml
|
||||
+++++++++++++++++++++++
|
||||
|
||||
This file describes additional attributes that will appear on the **Settings** tab of the Fuel web UI
|
||||
When the environment is deployed,
|
||||
these attributes are passed to the task executor so that the data is available in the */etc/astute.yaml*
|
||||
file on each target node and can be accessed from your bash or puppet scripts.
|
||||
|
||||
By default, your configuration file (**environment_config.yaml**) adds text field on Fuel web UI:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
attributes:
|
||||
fuel_plugin_name_text:
|
||||
value: 'Set default value'
|
||||
label: 'Text field'
|
||||
description: 'Description for text field'
|
||||
weight: 25
|
||||
type: "text"
|
||||
|
||||
For more information on Fuel web UI elements for a plug-in, see :ref:`fuel-plugin-dev-ui`.
|
||||
|
||||
metadata.yaml
|
||||
+++++++++++++
|
||||
|
||||
This file contains the description of your plug-in:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Plugin name
|
||||
name: fuel_plugin_name
|
||||
# Human-readable name for your plugin, it will be shown on UI
|
||||
# as a name of plugin group
|
||||
title: Title for fuel_plugin_name plugin
|
||||
# Plugin version
|
||||
version: 1.0.0
|
||||
# Description
|
||||
description: Enable to use plugin X
|
||||
# Required fuel version
|
||||
fuel_version: ['6.0']
|
||||
|
||||
# The plugin is compatible with releases in the list
|
||||
releases:
|
||||
- os: ubuntu
|
||||
version: 2014.2-6.0
|
||||
mode: ['ha', 'multinode']
|
||||
deployment_scripts_path: deployment_scripts/
|
||||
repository_path: repositories/ubuntu
|
||||
- os: centos
|
||||
version: 2014.2-6.0
|
||||
mode: ['ha', 'multinode']
|
||||
deployment_scripts_path: deployment_scripts/
|
||||
repository_path: repositories/centos
|
||||
|
||||
# Version of plugin package
|
||||
package_version: '1.0.0'
|
||||
|
||||
* *name* - internal name for your plug-in, can consist of
|
||||
lowercase letters, '-' and '_' symbols.
|
||||
|
||||
* *title* - human-readable name for the plug-in that will appear
|
||||
on the Fuel web UI.
|
||||
|
||||
* *description* - description for your plug-in.
|
||||
|
||||
* *version* - plug-in version; for more information on this
|
||||
issue, see `Semantic Versioning 2.0.0 <http://semver.org/>`_.
|
||||
|
||||
* *fuel_version* - a list of plug-in-compatible
|
||||
versions of Fuel.
|
||||
|
||||
* *package_version* - version of plug-in format; do not change it until
|
||||
you are trying to migrate your plug-in to a newer format. Fuel uses
|
||||
this version to choose the way a plug-in should be installed.
|
||||
|
||||
* *releases* - a list of OpenStack releases compatible with the plug-in.
|
||||
Release can look like *2014.2-6.0*.
|
||||
|
||||
* *os* - a name of supported Linux distribution, for example *ubuntu* or *centos*.
|
||||
|
||||
* *version* - version of OpenStack release.
|
||||
|
||||
* *mode* - a list plug-in-compatible modes;
|
||||
'ha' - used if plug-in supports High Availability, 'multinode' -
|
||||
if it does not.
|
||||
|
||||
* *deployment_scripts_path* - a path in your plug-in directory
|
||||
where all deployment scripts for the release are located
|
||||
relative to the top of the plug-in directory.
|
||||
|
||||
* *repository_path* - a path in your plug-in directory
|
||||
where all packages for the release are located
|
||||
relative to the top of the plug-in directory.
|
||||
|
||||
Implementation details
|
||||
----------------------
|
||||
|
||||
Installation
|
||||
++++++++++++
|
||||
|
||||
Installation procedure consists of the following steps:
|
||||
|
||||
#. User uploads *fuel_plugin_name-1.0.0.fp* file on the Fuel Master node;
|
||||
this file represents a tar.gz archive.
|
||||
|
||||
#. When plug-in is uploaded, user runs the following command:
|
||||
|
||||
::
|
||||
|
||||
|
||||
fuel plugins --install fuel_plugin_name-1.0.0.fp
|
||||
|
||||
|
||||
#. Fuel client copies the contents of *fuel_plugin_name-1.0.0.fp* file to the
|
||||
*/var/www/nailgun/plugins/fuel_plugin_name-1.0.0* directory.
|
||||
|
||||
#. Fuel client registers the plug-in using REST API Service (Nailgun);
|
||||
it sends a POST request with the contents
|
||||
of **metadata.yaml** file to **/api/v1/plugins** url.
|
||||
|
||||
Configuration
|
||||
+++++++++++++
|
||||
|
||||
Configuration procedure consists of the following steps:
|
||||
|
||||
#. When a new environment is created, Nailgun tries to find plug-ins which
|
||||
are compatible with the environment.
|
||||
|
||||
#. Nailgun merges the contents of the
|
||||
**environment_config.yaml** files with the basic attributes of the environment
|
||||
and generates a separate group and the checkbox on the Fuel web UI for each plug-in.
|
||||
|
||||
#. The plug-in is disabled until the user enables it.
|
||||
Then Fuel web UI sends the data to Nailgun;
|
||||
Nailgun parses the request and creates relations between **Plugin** and **Cluster**
|
||||
models.
|
||||
|
||||
.. note::
|
||||
|
||||
User cannot disable or reconfigure plug-in after environment is deployed.
|
||||
|
||||
Deployment
|
||||
++++++++++
|
||||
|
||||
After environment is created and configured, user starts a deployment.
|
||||
Meanwhile, Nailgun gets the list of enabled plug-ins from the database.
|
||||
For each plug-in from the list, Nailgun parses **tasks.yaml** file:
|
||||
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
- role: ['controller']
|
||||
stage: post_deployment
|
||||
type: shell
|
||||
parameters:
|
||||
cmd: ./deploy.sh
|
||||
timeout: 42
|
||||
- role: '*'
|
||||
stage: pre_deployment
|
||||
type: shell
|
||||
parameters:
|
||||
cmd: echo all > /tmp/plugin.all
|
||||
timeout: 42
|
||||
|
||||
Here is an example of tasks generated for task executor when a two-node
|
||||
environment is deployed; node has a Controller role with UID 7 and Compute role with UID 8.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"pre_deployment": [
|
||||
{
|
||||
"uids": ["8", "7"],
|
||||
"parameters": {
|
||||
"path": "/etc/apt/sources.list.d/fuel_plugin_name-1.0.0.list",
|
||||
"data": "deb http://10.20.0.2:8080/plugins/
|
||||
fuel_plugin_name-1.0.0/repositories/ubuntu /"
|
||||
},
|
||||
"priority": 100,
|
||||
"fail_on_error": true,
|
||||
"type": "upload_file",
|
||||
"diagnostic_name": "fuel_plugin_name-1.0.0"
|
||||
},
|
||||
{
|
||||
"uids": ["8", "7"],
|
||||
"parameters": {
|
||||
"src": "rsync://10.20.0.2:/plugins/fuel_plugin_name-1.0.0/deployment_scripts/",
|
||||
"dst": "/etc/fuel/plugins/fuel_plugin_name-1.0.0/"
|
||||
},
|
||||
"priority": 200,
|
||||
"fail_on_error": true,
|
||||
"type": "sync",
|
||||
"diagnostic_name": "fuel_plugin_name-1.0.0"
|
||||
},
|
||||
{
|
||||
"uids": ["8", "7"],
|
||||
"parameters": {
|
||||
"cmd": "echo all > /tmp/plugin.all",
|
||||
"cwd": "/etc/fuel/plugins/fuel_plugin_name-1.0.0/",
|
||||
"timeout": 42
|
||||
},
|
||||
"priority": 300,
|
||||
"fail_on_error": true,
|
||||
"type": "shell",
|
||||
"diagnostic_name": "fuel_plugin_name-1.0.0"
|
||||
}
|
||||
],
|
||||
"post_deployment": [
|
||||
{
|
||||
"uids": ["7"],
|
||||
"parameters": {
|
||||
"cmd": "./deploy.sh",
|
||||
"cwd": "/etc/fuel/plugins/fuel_plugin_name-1.0.0/",
|
||||
"timeout": 42
|
||||
},
|
||||
"priority": 100,
|
||||
"fail_on_error": true,
|
||||
"type": "shell",
|
||||
"diagnostic_name": "fuel_plugin_name-1.0.0"
|
||||
}
|
||||
],
|
||||
"deployment_info": "<Here is regular deployment info>"
|
||||
}
|
||||
|
||||
* *pre_deployment* - has three tasks; two of them are generated automatically by Nailgun
|
||||
while the third one is initiated by user and taken from from **tasks.yaml** file, converted to
|
||||
task executor format.
|
||||
|
||||
- the first task adds a new repository for the node; repository's path
|
||||
is built according to the following template:
|
||||
**http://{{master_ip}}:8080/plugins/{{plugin_name}}-{{plugin_version}}/{{repository_path}}**,
|
||||
where *master_ip* is an IP address of the Fuel Master node; *plugin_name*
|
||||
is a plug-in name; *plugin_version* is the plug-in version,
|
||||
*repository_path* is a path for a specific release in
|
||||
**metadata.yaml** file.
|
||||
|
||||
- the second tasks copies plug-in deployment scripts on the target nodes.
|
||||
Rsync is used to copy the files. Path to these files is pretty similar to the repository
|
||||
path. The only difference is that the deployment scripts path is taken from
|
||||
**deployment_scripts_path** that is placed into **metadata.yaml** file.
|
||||
|
||||
* *post_deployment* - has only one task which is taken from
|
||||
*tasks.yaml* file; **uids** field contains a list of nodes on which user should run
|
||||
a particular task. In this example, *tasks.yaml* file has **"role: ['controller']"** and
|
||||
this role is assigned to controller with UID 7.
|
||||
|
||||
* *deployment_info* - this section contains configuration information
|
||||
required for deployment and not related to plug-ins.
|
||||
|
||||
Debugging your plug-in
|
||||
----------------------
|
||||
|
||||
You can use :ref:`virtualbox` for much (perhaps all) of your testing and debugging.
|
||||
|
||||
Debugging UI
|
||||
++++++++++++
|
||||
|
||||
UI elements are described in **environment_config.yaml** file.
|
||||
|
||||
To check how your built plug-in looks on the Fuel web UI, install and create an environment:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Enter plugin directory
|
||||
cd fuel_plugin_name
|
||||
|
||||
# Change environment_config.yaml file
|
||||
|
||||
# Build a plugin
|
||||
fpb --build .
|
||||
|
||||
# Install plugin, use "--force" parameter to replace
|
||||
# the plugin if you have it installed
|
||||
fuel plugins --install fuel_plugin_name-1.0.0.fp --force
|
||||
|
||||
# Create new environment
|
||||
fuel env --create --release 1 --name test
|
||||
|
||||
# Check that UI correctly shows elements from environment_config.yaml file
|
||||
|
||||
|
||||
Debugging deployment
|
||||
++++++++++++++++++++
|
||||
|
||||
To show how it works, let's create a simple plug-in with an error in
|
||||
deployment script.
|
||||
|
||||
#. Create a plug-in:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
fpb --create fuel_plugin_name
|
||||
|
||||
#. Add an error in the default deployment script
|
||||
(*fuel_plugin_name/deployment_scripts/deploy.sh*):
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
#!/bin/bash
|
||||
|
||||
# It's a script which deploys your plugin
|
||||
echo fuel_plugin_name > /tmp/fuel_plugin_name
|
||||
|
||||
# Non-zero exit code means, that a script executed with error
|
||||
exit 1
|
||||
|
||||
|
||||
If you do not want to run plug-in build, but you want to check that
|
||||
plug-in format is correct, you can use *--check* parameter with
|
||||
the following command:
|
||||
|
||||
::
|
||||
|
||||
fpb --check fuel_plugin_name
|
||||
|
||||
|
||||
#. Build and install the plug-in:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
fpb --build fuel_plugin_name/
|
||||
fuel plugins --install fuel_plugin_name/fuel_plugin_name-1.0.0.fp
|
||||
|
||||
#. Use Fuel web UI or CLI to create an environment:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
fuel env create --name test --rel 1 --mode multinode --network-mode nova
|
||||
|
||||
#. Enable the plug-in on Fuel web UI **Settings** tab and then add several nodes.
|
||||
The first node has *Controller* role, the second node has *Cinder*
|
||||
and *Computes* roles.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
fuel node set --node 1 --env 1 --role controller
|
||||
fuel node set --node 2 --env 1 --role compute,cinder
|
||||
|
||||
#. Check that Nailgun generates correct configuration
|
||||
data that a user can set on Fuel web UI:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
fuel deployment --default --env 1
|
||||
cat deployment_1/controller_1.yaml
|
||||
...
|
||||
fuel_plugin_name:
|
||||
fuel_plugin_name_text: Set default value
|
||||
...
|
||||
|
||||
Now can see that the file for target node contains plug-in data.
|
||||
|
||||
.. note::
|
||||
|
||||
The command mentioned above is useful when you do not know how
|
||||
your configuration data
|
||||
from Fuel web UI **Settings** tab will look like in **/etc/astute.yaml** file on
|
||||
target nodes.
|
||||
|
||||
#. Perform provisioning without deployment for two nodes:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
fuel --env 1 node --provision --node 1,2
|
||||
|
||||
.. note::
|
||||
|
||||
To reduce the time required for testing, make a snapshot after nodes are provisioned.
|
||||
Note that if you use virtual machines, make snapshots of your target nodes.
|
||||
|
||||
#. Now you can run deployment:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
fuel --env 1 node --deploy --node 1,2
|
||||
|
||||
|
||||
#. The deployment fails with the following message:
|
||||
|
||||
::
|
||||
|
||||
Deployment has failed. Method deploy. Failed to deploy plugin fuel_plugin_name-1.0.0.
|
||||
|
||||
#. You can see an error in **/var/log/docker-logs/astute/astute.log** task executor logs:
|
||||
|
||||
::
|
||||
|
||||
[394] Shell command failed. Check debug output for details
|
||||
[394] 13edd324-6a11-4342-bc04-66c659e75e35: cmd: ./deploy.sh
|
||||
cwd: /etc/fuel/plugins/fuel_plugin_name-1.0.0/
|
||||
stdout:
|
||||
stderr:
|
||||
exit code: 1
|
||||
|
||||
#. It fails due to the changes in **deploy.sh** script that you made in
|
||||
step 2. Let's assume that we do not know what happened and try to debug the problem:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Go to the first node
|
||||
ssh node-1
|
||||
|
||||
#. All plug-in deployment scripts are copied to the separate directory on the
|
||||
target node; in this case, it is **/etc/fuel/plugins/fuel_plugin_name-1.0.0/**:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd /etc/fuel/plugins/fuel_plugin_name-1.0.0/
|
||||
# The directory contains our deploy.sh script, lets run it
|
||||
./deploy.sh
|
||||
# And check exit code
|
||||
echo $? # Returns 1
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
If you use puppet for your plug-in deployment,
|
||||
run the following command on the target node to
|
||||
check if your puppet manifests work correctly:
|
||||
|
||||
*puppet apply --debug --modulepath=/etc/fuel/plugins/fuel_plugin_name-1.0.0/modules /etc/fuel/plugins/fuel_plugin_name-1.0.0/manifests/site.pp*
|
||||
|
||||
#. Now we can see that deployment fails due to non-zero exit code error.
|
||||
To fix the problem and check that the proposed solution works,
|
||||
edit the */var/www/nailgun/plugins/fuel_plugin_name-1.0.0/deployment_scripts/deploy.sh* script
|
||||
on the Fuel Master node.
|
||||
Note that there is no need to rebuild and reinstall a plug-in:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
#!/bin/bash
|
||||
|
||||
# It's a script which deploys your plugin
|
||||
echo fuel_plugin_name > /tmp/fuel_plugin_name
|
||||
|
||||
# Now our deployment script returns 0 instead of 1
|
||||
exit 0
|
||||
|
||||
#. If you run the deployment again, it goes successfully:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
fuel --env 1 node --deploy --node 1,2
|
||||
|
||||
.. warning::
|
||||
|
||||
During the testing of your deployment scripts, make sure that
|
||||
your scripts are idempotent: they should work correctly when
|
||||
applied several times.
|
||||
Run environment deployment at least twice and check that
|
||||
your plug-in works properly. The reason for this workflow
|
||||
is the following:
|
||||
Fuel can run deployment of your plug-in several times in case
|
||||
the first deployment try failed. Also, your deployment scripts can be
|
||||
executed during OpenStack patching.
|
||||
|
||||
#. To make sure that plug-in works without errors, revert snapshots
|
||||
which you made in step 6, and run deployment again:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
fuel --env 1 node --deploy --node 1,2
|
||||
|
||||
In the same way with no plug-in reinstallation,
|
||||
you can edit */var/www/nailgun/plugins/<fuel_plugin_name>-1.0.0/tasks.yaml* file.
|
||||
Note that in this case to make sure that your tasks have a valid format, you should at least
|
||||
run the following command:
|
||||
|
||||
::
|
||||
|
||||
fpb --check /var/www/nailgun/plugins/fuel_plugin_name-1.0.0/
|
||||
|
||||
.. _puppet-fuel:
|
||||
|
||||
Puppet in Fuel
|
||||
--------------
|
||||
|
||||
Fuel does not use puppet master. Task executor copies manifest from
|
||||
the Fuel Master node and runs 'puppet apply' command on each target node.
|
||||
|
||||
It is recommended to use `puppet` tasks in your plug-in instead of running
|
||||
puppet in shell tasks.
|
||||
|
||||
Task executor has `code with special logic <https://github.com/stackforge/fuel-astute/blob/122cdaab/mcagents/puppetd.rb>`_ which handles errors, if **puppet apply**
|
||||
command returns zero/non-zero exit code.
|
||||
Note that it does not mean that command is
|
||||
succeed or failed. That means, it returns '2' if there were changes during the execution:
|
||||
task executor parses '/var/lib/puppet/state/last_run_summary.yaml' file to
|
||||
determine the status of puppet run.
|
||||
|
|
@ -0,0 +1,80 @@
|
|||
.. _fuel-plugin-dev-ui:
|
||||
|
||||
Fuel plug-in UI elements
|
||||
------------------------
|
||||
|
||||
Here is an example of the *environment_config.yaml* file that
|
||||
contains all possible Fuel web UI elements:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
attributes:
|
||||
|
||||
# Text field
|
||||
fuel_plugin_name_text:
|
||||
type: "text"
|
||||
weight: 10
|
||||
value: "Default text"
|
||||
label: "Text field label"
|
||||
description: "Field description"
|
||||
regex:
|
||||
source: '\S'
|
||||
error: "Error field cannot be empty"
|
||||
|
||||
# Dropdown
|
||||
fuel_plugin_name_dropdown:
|
||||
type: "dropdown"
|
||||
weight: 20
|
||||
value: "value2"
|
||||
label: "Dropdown label"
|
||||
description: "Dropdown description"
|
||||
values:
|
||||
- data: "value1"
|
||||
label: "Value 1 label"
|
||||
- data: "value2"
|
||||
label: "Value 2 label"
|
||||
- data: "value3"
|
||||
label: "Value 3 label"
|
||||
|
||||
# Checkbox
|
||||
fuel_plugin_name_checkbox:
|
||||
type: "checkbox"
|
||||
weight: 30
|
||||
value: false
|
||||
label: "Checkbox label"
|
||||
description: "Checkbox description"
|
||||
|
||||
# Radio button
|
||||
fuel_plugin_name_radio:
|
||||
type: "radio"
|
||||
weight: 40
|
||||
value: "disabled"
|
||||
label: "Radio buttons label"
|
||||
values:
|
||||
- data: "data1"
|
||||
label: "Label data1"
|
||||
description: "Description data1"
|
||||
- data: "data2"
|
||||
label: "Label data2"
|
||||
description: "Description data2"
|
||||
- data: "data3"
|
||||
label: "Label data3"
|
||||
description: "Description data3"
|
||||
|
||||
After plug-in is installed, additional elements appear on the *Settings* tab of the Fuel web UI:
|
||||
|
||||
.. image:: /_images/fuel_plugin_dev_ui_elements.png
|
||||
:width: 50%
|
||||
|
||||
When the user runs deployment, the plug-in deployment script can get the data
|
||||
from the */etc/astute.yaml* file; in this example, plug-in-specific data look like:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
...
|
||||
fuel_plugin_name:
|
||||
fuel_plugin_name_checkbox: false
|
||||
fuel_plugin_name_dropdown: value2
|
||||
fuel_plugin_name_radio: disabled
|
||||
fuel_plugin_name_text: Default text
|
||||
...
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
|
||||
.. _040-install-plugin:
|
||||
|
||||
Installing Fuel plug-ins
|
||||
========================
|
||||
|
||||
.. note:: Fuel plug-ins can be installed only before
|
||||
environment is configured and deployed.
|
||||
Otherwise, you will have to redeploy
|
||||
the environment to enable a plug-in.
|
||||
|
||||
Installation procedure is common for all plug-ins, but their requirements differ.
|
||||
|
||||
In current plug-ins implementation,
|
||||
it is impossible to uninstall the plug-in.
|
||||
You can use the following workaround to reinstall it:
|
||||
|
||||
::
|
||||
rm /var/www/nailgun/plugins/<plugin_name>
|
||||
fuel plugins --force --install <plugin_name>
|
||||
|
||||
#. Copy the plug-in on already installed Fuel Master node; ssh can be used for that.
|
||||
If you do not have the Fuel Master node yet, see :ref:`virtualbox`.
|
||||
|
||||
::
|
||||
|
||||
scp fuel_plugin_name-1.0.0.fp root@:master_node_ip:/tmp
|
||||
cd /tmp
|
||||
fuel plugins --install <fuel_plugin_name>-1.0.0.fp
|
||||
|
||||
#. After your environment is created, the checkbox will appear on Fuel web UI *Settings* tab.
|
||||
Use the *Settings* tab to enable and configure the plug-in and run the deployment.
|
||||
|
||||
.. include:: /pages/plugin-dev/041-fuel-plugin-core.rst
|
||||
.. include:: /pages/plugin-dev/042-fuel-plugin-other.rst
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
.. _041-fuel-plugin-core:
|
||||
|
||||
Certified plug-ins
|
||||
------------------
|
||||
|
||||
.. include:: /pages/plugin-dev/0412-plugin-lbaas.rst
|
||||
.. include:: /pages/plugin-dev/0411-plugin-gluster.rst
|
||||
|
|
@ -0,0 +1,59 @@
|
|||
.. _plugin-gluster:
|
||||
|
||||
GlusterFS
|
||||
+++++++++
|
||||
|
||||
This plug-in allows to use existing `GlusterFS <http://www.gluster.org/
|
||||
documentation/About_Gluster>`_ cluster as the Cinder backend.
|
||||
|
||||
**Requirements**
|
||||
|
||||
This plug-in is compatible with the following GlusterFS version:
|
||||
|
||||
+------------------------------------------------+------------------------------------+
|
||||
| Description |Ubuntu 14.04 LTS |
|
||||
+------------------------------------------------+------------------------------------+
|
||||
| Release |14.04 |
|
||||
+------------------------------------------------+------------------------------------+
|
||||
| Codename |trusty |
|
||||
+------------------------------------------------+------------------------------------+
|
||||
| glusterfs 3.4.2 built on Jan 14 2014 18:05:35 | |
|
||||
+------------------------------------------------+------------------------------------+
|
||||
|Repository revision |git://git.gluster.com/glusterfs.git |
|
||||
+------------------------------------------------+------------------------------------+
|
||||
|
||||
**Installation**
|
||||
|
||||
#. Download the plug-in from `<https://software.mirantis.com/fuel-plugins>`_.
|
||||
|
||||
#. Install GlusterFS plug-in. For instructions, see :ref:`040-install-plugin`.
|
||||
|
||||
#. After plug-in is installed, create an environment.
|
||||
|
||||
**Configuration**
|
||||
|
||||
#. Enable the plug-in on the *Settings* tab of the Fuel web UI.
|
||||
|
||||
.. image:: /_images/plugins/fuel_plugin_glusterfs_configuration.png
|
||||
|
||||
|
||||
#. After GlusterFS plug-in is installed and a volume is created,
|
||||
configure each Gluster volume to accept libgfapi connections.
|
||||
To do this, configure every Gluster volume to all insecure ports [1, 2]:
|
||||
|
||||
::
|
||||
|
||||
gluster volume set <volume_name> server.allow-insecure on
|
||||
gluster volume stop <volume_name>
|
||||
gluster volume start <volume_name>
|
||||
|
||||
#. Add to /etc/glusterfs/glusterd.vol the following option:
|
||||
|
||||
::
|
||||
|
||||
option rpc-auth-allow-insecure on
|
||||
|
||||
#. Restart glusterd daemon.
|
||||
|
||||
.. SeeAlso:: For more information on GlusterFS, see
|
||||
`Configure GlusterFS backend <http://docs.openstack.org/admin-guide-cloud/content/glusterfs_backend.html>`_ in the official OpenStack documentation.
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
.. _0412-plugin-lbaas:
|
||||
|
||||
Neutron LBaaS
|
||||
+++++++++++++
|
||||
|
||||
This plug-in provides `Neutron LBaaS <https://wiki.openstack.org/wiki/Neutron/LBaaS/
|
||||
PluginDrivers>`_ for a multinode mode.
|
||||
|
||||
**Requirements**
|
||||
|
||||
.. note:: Note that LBaaS plug-in can be enabled
|
||||
only in *multi-node* environments.
|
||||
|
||||
**Installation**
|
||||
|
||||
#. Download the plug-in from `<https://software.mirantis.com/fuel-plugins>`_.
|
||||
|
||||
#. Install LBaaS plug-in. For instructions, see :ref:`040-install-plugin`.
|
||||
|
||||
#. After plugin is installed, create a **multi-node**
|
||||
environment with Neutron.
|
||||
|
||||
**Configuration**
|
||||
|
||||
#. Enable the plugin on the *Settings* tab of the Fuel web UI.
|
||||
|
||||
.. image:: /_images/plugins/fuel_plugin_lbaas_configuration.png
|
||||
|
||||
#. For further steps, see
|
||||
`Configure Neutron LBaaS <https://wiki.openstack.org/wiki/Neutron/LBaaS/UI>`_ in the official OpenStack documentation.
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
.. _042-fuel-plugin-other:
|
||||
|
||||
Non-Certified plug-ins
|
||||
----------------------
|
||||
|
||||
Non-Certified plug-ins are created by Mirantis and third-party developers.
|
||||
When tested and checked for integration with Fuel, they are regarded as
|
||||
Certified.
|
||||
|
||||
.. include:: /pages/plugin-dev/0421-plugin-vpnaas.rst
|
||||
.. include:: /pages/plugin-dev/0422-plugin-netapp.rst
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
.. _0421-plugin-vpnaas:
|
||||
|
||||
Neutron VPNaaS
|
||||
++++++++++++++
|
||||
|
||||
VPNaaS is a Non-Certified plug-in that provides `Neutron VPNaaS <https://wiki.openstack.org/wiki/Neutron/VPNaaS>`__ functionality.
|
||||
|
||||
**Requirements**
|
||||
|
||||
VPNaaS plug-in is compatible with OpenStack Juno Release 2014.2.
|
||||
It also supports Ubuntu 14.04 LTS and CentOS 6.5.
|
||||
|
||||
**Installation**
|
||||
|
||||
#. Download the plug-in from `<https://software.mirantis.com/fuel-plugins>`_.
|
||||
|
||||
#. Move this file to the Fuel
|
||||
Master node and install it using the following command:
|
||||
|
||||
::
|
||||
|
||||
fuel plugins --install vpnaas-plugin-1.0.0.fp
|
||||
|
||||
#. After plug-in is installed, create an environment with Neutron.
|
||||
|
||||
**Configuration**
|
||||
|
||||
#. Enable the plug-in on the *Settings* tab of the Fuel web UI.
|
||||
|
||||
.. image:: _images/plugins/fuel_plugin_vpnaas_configuration.png
|
||||
|
||||
#. For further steps, see`
|
||||
Configure VPN-as-a-Service (VPNaaS) <https://www.mirantis.com/blog/mirantis-openstack-express-vpn-service-vpnaas-step-step/>`__ in the Mirantis blogpost.
|
||||
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
.. _0422-plugin-netapp:
|
||||
|
||||
NetApp
|
||||
++++++
|
||||
|
||||
NetApp plug-in will replace `Cinder LVM driver <http://docs.openstack.org/juno/config-reference/content/lvm-volume-driver.html>`_.
|
||||
|
||||
**Requirements**
|
||||
|
||||
To enable NetApp plug-in for Cinder, you should check the following:
|
||||
|
||||
* NetApp appliance is deployed and configured.
|
||||
|
||||
* NetApp appliance is reachable via one of the Mirantis OpenStack networks.
|
||||
|
||||
.. note:: Since only one Cinder node should be deployed,
|
||||
Cinder volume is **not** highly available.
|
||||
|
||||
**Installation**
|
||||
|
||||
#. Download the plug-in from `<https://software.mirantis.com/fuel-plugins>`_.
|
||||
|
||||
#. Move this file to the Fuel
|
||||
Master node and install it using the following command:
|
||||
|
||||
::
|
||||
|
||||
fuel plugins --install cinder_netapp-1.0.0.fp
|
||||
|
||||
#. After plug-in is installed, create an environment the default Cinder backend.
|
||||
|
||||
**Configuration**
|
||||
|
||||
#. Enable the plug-in on the *Settings* tab of the Fuel web UI.
|
||||
|
||||
.. image:: /_images/plugins/fuel_plugin_netapp_configuration.png
|
||||
|
||||
#. Configure the plug-in and assign Cinder role to one of the nodes.
|
||||
|
||||
#. For more information on accessing Cinder NetApp functionality,
|
||||
see `the Official OpenStack documentation <http://docs.openstack.org/juno/config-reference/content/netapp-volume-driver.html>`_.
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
.. _050-support:
|
||||
|
||||
Plug-ins support
|
||||
----------------
|
||||
|
||||
You should provide support contact and SLA information in case your expertise is needed to assist customers.
|
||||
|
|
@ -0,0 +1,180 @@
|
|||
.. _plugin-cert:
|
||||
|
||||
|
||||
Fuel plug-ins certification
|
||||
===========================
|
||||
|
||||
Certified and Non-Certified plug-ins
|
||||
------------------------------------
|
||||
|
||||
Plug-ins come into two categories: Certified and Non-Certified.
|
||||
|
||||
For information on Certified and Non-Certified plug-ins certification requirements,
|
||||
see :ref:`Plug-in certification requirements<plug-in-cert>`.
|
||||
|
||||
For instructions on creating your own plug-in, see :ref:`020-fuel-plugin-dev`.
|
||||
For instructions on installing a plug-in, see :ref:`040-install-plugin`.
|
||||
For instructions on building your plug-in, see :ref:`How To Build your Plug-in<create-build-plugin>`.
|
||||
|
||||
.. _plugins-storage:
|
||||
|
||||
Plug-ins storage
|
||||
----------------
|
||||
|
||||
Plug-ins are kept in a special file storage, so that
|
||||
you can download them from `<https://software.mirantis.com/fuel-plugins>`_
|
||||
and install.
|
||||
|
||||
Plug-ins development requirements
|
||||
---------------------------------
|
||||
|
||||
Plug-ins must meet a set of development requirements.
|
||||
Once a provided plug-in does not satisfy any of them,
|
||||
Mirantis cannot accept it and publish into the Catalog.
|
||||
|
||||
When you plan to develop a plug-in for Fuel,
|
||||
take the following requirements into consideration:
|
||||
|
||||
* Plug-in should be written on Python.
|
||||
|
||||
* Deb and rpm packages must contain their dependencies.
|
||||
For instructions on creating packages, see
|
||||
`Fedora project wiki <https://fedoraproject.org/wiki/How_to_create_an_RPM_package>`_
|
||||
and `Ubuntu Packaging Guide <http://packaging.ubuntu.com/html/>`_.
|
||||
|
||||
* Puppet manifests should be written
|
||||
according to the
|
||||
`Official OpenStack documentation <https://wiki.openstack.org/wiki/Puppet-openstack#Developer_documentation>`_.
|
||||
For good code examples and workflow,
|
||||
see `Puppet in OpenStack <https://wiki.openstack.org/wiki/Puppet-openstack>`_.
|
||||
|
||||
* It is strongly not recommended to use bash scripts.
|
||||
|
||||
.. _plug-in-cert:
|
||||
|
||||
Plug-ins certification requirements
|
||||
-----------------------------------
|
||||
|
||||
Certified and Non-Certified plug-ins have a set of requirements.
|
||||
|
||||
.. _non-certified:
|
||||
|
||||
Non-Certified
|
||||
+++++++++++++
|
||||
|
||||
Non-Certified plug-in should satisfy the following requirements:
|
||||
|
||||
* Built plug-in or download link is provided
|
||||
|
||||
* Plug-in purpose is specified: for example,
|
||||
Compute, Storage, Network, Operations
|
||||
|
||||
* Basic description of plug-in functionality (specification) is provided
|
||||
|
||||
* Plug-in developer contact information (company, support contacts) is provided
|
||||
|
||||
Non-Certified plug-in must also have the following set of documentation:
|
||||
|
||||
* Plug-in Installation Guide in .pdf format
|
||||
|
||||
* Plug-in User Guide in .pdf format (for templates, see :ref:`plugin-doc-template`)
|
||||
|
||||
* Test Plan and Test Report in .pdf format (for templates, see :ref:`test-plan-report`)
|
||||
|
||||
|
||||
.. _certified:
|
||||
|
||||
Certified
|
||||
+++++++++
|
||||
|
||||
Certified plug-ins are those that passed :ref:`Non-Certified<non-certified>` phase.
|
||||
|
||||
The main difference between Non-Certified and Certified plug-ins is that
|
||||
the latter are tested by the Fuel QA team more thoroughly to verify
|
||||
that plug-in can be enabled in Fuel without any harm.
|
||||
|
||||
If a Non-Certified plug-in susccessfully passes all tests,
|
||||
it is moved to the appropriate directory
|
||||
of the :ref:`Plug-ins storage<plugins-storage>` and signed by
|
||||
Mirantis `GPG <https://www.gnupg.org/index.html>`_ key.
|
||||
|
||||
.. include:: pages/plugin-dev/plugin-doc-template.rst
|
||||
.. include:: pages/plugin-dev/test-plan-report.rst
|
||||
|
||||
.. _how-to-push:
|
||||
|
||||
How to upload your plug-in into Mirantis OpenStack Catalog
|
||||
==========================================================
|
||||
|
||||
It is not important where to host the plug-in code.
|
||||
Nevertheless, to enable CI tests it is recommended to
|
||||
publish plug-ins into separate repositories of the
|
||||
`Stackforge <https://github.com/stackforge>`_
|
||||
project.
|
||||
|
||||
Currently, plug-ins created by Mirantis developers are kept
|
||||
in the following repos:
|
||||
|
||||
* `Stackforge plug-ins <https://github.com/stackforge/fuel-plugins>`_ - used for plug-ins developed by Fuel Core team.
|
||||
|
||||
* `Mirantis plug-ins <https://github.com/mirantis/fuel-plugins>`_ - used for plug-ins developed by Partner Integrations and MOS teams.
|
||||
|
||||
Note that the plug-ins will also be moved to separate repos in Stackforge.
|
||||
|
||||
A contributor should only build the plug-in as described in :ref:`instructions on building a plug-in<create-build-plugin>` and
|
||||
send it to *fuel-plugin@mirantis.com*.
|
||||
|
||||
The email should contain the following information:
|
||||
|
||||
* Type of the plug-in
|
||||
|
||||
* Set of required documents, described in
|
||||
:ref:`Non-Certified<non-certified>` and :ref:`Certified<certified>` sections.
|
||||
|
||||
After receiving the email, Partner Integration team starts
|
||||
:ref:`Plug-in acceptance workflow<plug-in-accept-workflow>`.
|
||||
|
||||
.. _plug-in-accept-workflow:
|
||||
|
||||
Plug-in acceptance workflow
|
||||
---------------------------
|
||||
|
||||
.. _non-certified-plug-in-workflow:
|
||||
|
||||
Non-Certified plug-in acceptance workflow
|
||||
+++++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
The workflow for Non-Certified plug-ins consists of the following steps:
|
||||
|
||||
#. Plug-in that satisfies :ref:`Non-Certified<non-certified>`
|
||||
plug-ins certification requirements,
|
||||
goes through a set of tests. Fuel QA team confirms it.
|
||||
|
||||
#. Fuel Documentation team verifies that all necessary documents are provided
|
||||
according to :ref:`Documentation template<plugin-doc-template>`.
|
||||
|
||||
#. After Fuel QA and Documentation teams provide their confirmation,
|
||||
responsible person from Partner Integration team adds or replaces the plug-in
|
||||
with its User Guide into Non-Certified plug-ins directory of the :ref:`Plug-ins storage<plugins-storage>`.
|
||||
|
||||
.. _certified-plug-in-workflow:
|
||||
|
||||
Certified plug-ins acceptance workflow
|
||||
++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
The workflow for plug-ins certification consists of the following steps:
|
||||
|
||||
#. A plug-in should pass :ref:`Non-Certified plug-in acceptance workflow<non-certified-plug-in-workflow>`.
|
||||
|
||||
#. Fuel Core, PI and MOS teams developers review the code,
|
||||
try to check architecture, security and performance issues of the provided plug-in.
|
||||
|
||||
#. Fuel QA team tests plug-in according to the extended test cases.
|
||||
Additional test cases should be provided in the contributor's testing
|
||||
instruction.
|
||||
|
||||
#. After Fuel QA, Core, MOS and Documentation teams confirm that plug-in
|
||||
can be moved to Verified, responsible person from Partner Integration team pushes
|
||||
the plug-in with its documentation into the Certified directory of the :ref:`Plug-ins storage<plugins-storage>`.
|
||||
|
||||
.. include:: pages/plugin-dev/050-support.rst
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
.. _plugin-doc-template:
|
||||
|
||||
Documentation templates
|
||||
-----------------------
|
||||
|
||||
Fuel plug-in developer must provide Installation and User Guides.
|
||||
|
||||
Plug-in User Guide
|
||||
++++++++++++++++++
|
||||
|
||||
User Guide must contain the following information:
|
||||
|
||||
#. Full plug-in name with the description and functionality
|
||||
|
||||
#. Requirements, limitations and prerequisites for plug-in usage
|
||||
|
||||
#. Instructions for using already installed plug-in
|
||||
|
||||
#. API usage examples (if required)
|
||||
|
||||
#. UI configuration (if required)
|
||||
|
||||
|
||||
Plug-in Installation Guide
|
||||
++++++++++++++++++++++++++
|
||||
|
||||
Plug-in Installation Guide must contain the following information:
|
||||
|
||||
#. Full plug-in name with the description and functionality
|
||||
|
||||
#. Requirements, limitations and prerequisites for plug-in installation
|
||||
|
||||
#. Compatibility with a specific Mirantis OpenStack releases
|
||||
|
||||
#. Configuration instructions
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
.. _test-plan-report:
|
||||
|
||||
|
||||
Template for Test Plan
|
||||
++++++++++++++++++++++
|
||||
|
||||
.. note:: Fuel plug-ins are certified for the whole Mirantis OpenStack
|
||||
release series.
|
||||
|
||||
Test Plan for the Fuel plug-in must contain the following information:
|
||||
|
||||
#. Common plug-in description
|
||||
|
||||
#. Requirements, limitations and prerequisites for plug-in installation
|
||||
|
||||
#. Developer's specification (see `the template <https://github.com/stackforge/fuel-specs/blob/master/specs/template.rst>`_)
|
||||
|
||||
#. Functional testing results (it is recommended to provide
|
||||
scripts for checking a specific functionality)
|
||||
|
||||
#. Non-functional testing results for performance and security.
|
||||
Fuel QA team runs security testing, but OpenStack base system
|
||||
testing results should be provided
|
||||
|
||||
#. The Fuel Master node upgrade testing. Since plug-ins
|
||||
are certified for the whole release series, the Fuel Master node
|
||||
must also be verified for successful upgrade
|
||||
|
||||
#. Instructions on deploying a specific environment (if required)
|
||||
|
||||
#. Instructions on accessing the developer's lab (if a plug-in
|
||||
is hardware-specific)
|
||||
|
||||
When a Non-Certified plug-in candidate is checked,
|
||||
Fuel QA team reviews developer's specification to understand
|
||||
if the Test Plan covers all the functionality.
|
||||
|
||||
When a Certified plug-in candidate is checked,
|
||||
Fuel QA team runs test cases from the Test Plan and compares
|
||||
the obtained results with the ones described in the Test Report.
|
||||
|
||||
|
||||
|
||||
|
|
@ -25,5 +25,6 @@ pdf_documents = [
|
|||
('pdf/pdf_reference', u'Mirantis-OpenStack-6.0-ReferenceArchitecture', u'Reference Architecture', u'2014, Mirantis Inc.'),
|
||||
('pdf/pdf_terminology', u'Mirantis-OpenStack-6.0-Terminology-Reference', u'Terminology Reference', u'2014, Mirantis Inc.'),
|
||||
('pdf/pdf_file-ref', u'Mirantis-OpenStack-6.0-File-Reference', u'File Reference', u'2014, Mirantis Inc.'),
|
||||
('pdf/pdf_plugin-dev', u'Mirantis-OpenStack-6.0-FuelPlug-inGuide', u'Fuel Plug-in Guide', u'2014, Mirantis Inc.'),
|
||||
('pdf/pdf_relnotes', u'Mirantis-OpenStack-6.0-RelNotes', u'Release Notes', u'2014, Mirantis Inc.', {'pdf_use_toc': False}),
|
||||
]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,31 @@
|
|||
.. header::
|
||||
|
||||
.. cssclass:: header-table
|
||||
|
||||
+-------------------------------------+-----------------------------------+
|
||||
| Mirantis OpenStack v6.0 | .. cssclass:: right|
|
||||
| | |
|
||||
| Fuel Plug-in Guide | ###Section### |
|
||||
+-------------------------------------+-----------------------------------+
|
||||
|
||||
.. footer::
|
||||
|
||||
.. cssclass:: footer-table
|
||||
|
||||
+--------------------------+----------------------+
|
||||
| | .. cssclass:: right|
|
||||
| | |
|
||||
| ©2014, Mirantis Inc. | Page ###Page### |
|
||||
+--------------------------+----------------------+
|
||||
|
||||
.. raw:: pdf
|
||||
|
||||
PageBreak oneColumn
|
||||
|
||||
.. toctree::
|
||||
|
||||
.. include:: /pages/preface/preface.rst
|
||||
|
||||
.. _plugin-dev:
|
||||
|
||||
.. include:: /contents/contents-plugin-dev.rst
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
.. index:: Fuel Plug-in Guide
|
||||
|
||||
.. _plugin-dev:
|
||||
|
||||
==================
|
||||
Fuel Plug-in Guide
|
||||
==================
|
||||
|
||||
.. contents:: :local:
|
||||
|
||||
.. include:: /contents/contents-plugin-dev.rst
|
||||
Loading…
Reference in New Issue