Add manila plugin template documentation
This patchset adds "how to do a manila plugin" documentation to the charm guide. Change-Id: I02146aeed69691b0dd3c55169eea56705c7621a2
This commit is contained in:
Alex Kavanagh
parent
d21cd92d61
commit
343b085d5b
|
|
@ -5,8 +5,9 @@ Create A Charm
|
|||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:hidden:
|
||||
|
||||
charm-anatomy
|
||||
new-sdn-charm
|
||||
new-api-charm
|
||||
new-manila-charm
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,292 @@
|
|||
.. _new_manila_charm:
|
||||
|
||||
=====================================
|
||||
New Manila Plugin Configuration Charm
|
||||
=====================================
|
||||
|
||||
Typically, a Manila backend configuration simply needs to provide one or more
|
||||
configuration sections to the ``manila.conf`` file. It might also need to
|
||||
install some additional software to the node that manila is running on. (Note
|
||||
that, at present, all the manila services run on the same machine unit.)
|
||||
|
||||
In order to make it easier to write a configuration charm for a backend, a
|
||||
template has been provided to bootstrap the process. This example shows how to
|
||||
get started and provides pointers to help understand what to do next.
|
||||
|
||||
In the example below we will assume that a new charm provides a simple
|
||||
configuration to the manila charm.
|
||||
|
||||
Prerequisites
|
||||
=============
|
||||
|
||||
(Note. This will change once the OpenStack templates are on pypi)
|
||||
|
||||
In order get the OpenStack charm templates installed into the ``charm create``
|
||||
command, the ``charm-templates-openstack`` module needs to be installed
|
||||
alongside the ``charm-tools`` module. The code assumes that the
|
||||
``charm-tools`` module is already installed.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
mkdir working
|
||||
cd working
|
||||
git clone git@github.com:openstack-charmers/charm-templates-openstack.git
|
||||
cd charm_templates_openstack
|
||||
sudo ./setup.py install
|
||||
|
||||
Create Charm
|
||||
============
|
||||
|
||||
Charm tools provides a utility for building an initial charm from a template.
|
||||
During the charm generation charm tools asks a few questions about the charm.
|
||||
|
||||
Note that the charm created from the template is **not** functional and needs
|
||||
further editing to produce the functional charm needed.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cd path.to.working
|
||||
charm-create -t openstack-manila-plugin new-manila-plugin
|
||||
INFO: Generating charm for new-manila-plugin in ./new-manila-plugin
|
||||
INFO: No new-manila-plugin in apt cache; creating an empty charm instead.
|
||||
What is the earliest OpenStack release this charm will support? mitaka
|
||||
What packages should this charm install (space seperated list)?
|
||||
What is the package to take the version from (manila-api is probably ok)?
|
||||
|
||||
Three questions are asked:
|
||||
|
||||
1. The first is about the earliest version of OpenStack that is supported. The
|
||||
``src/metadata.yaml`` file **must** also be checked/changed to support the
|
||||
versions of Ubuntu that the charm will support (e.g. xenial, yakkety, etc.)
|
||||
|
||||
2. The second is whether any additional packages (over and above the manila
|
||||
packages) should be installed. Normally, this is just left empty.
|
||||
|
||||
3. The third is about where the charm should try and obtain the version from
|
||||
(this is the package). Normally, the driver version will be the same as the
|
||||
manila version, and therefore the default is acceptable. If the driver
|
||||
installs further packages, then the version should probably be from one of
|
||||
those packages.
|
||||
|
||||
Exploring the skeleton charm
|
||||
============================
|
||||
|
||||
The files that the template creates is:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
tree
|
||||
.
|
||||
├── LICENSE
|
||||
├── requirements.txt
|
||||
├── src
|
||||
│ ├── config.yaml
|
||||
│ ├── copyright
|
||||
│ ├── icon.svg
|
||||
│ ├── layer.yaml
|
||||
│ ├── lib
|
||||
│ │ └── charm
|
||||
│ │ └── openstack
|
||||
│ │ ├── __init__.py
|
||||
│ │ └── new_manila_plugin.py
|
||||
│ ├── metadata.yaml
|
||||
│ ├── reactive
|
||||
│ │ └── new_manila_plugin_handlers.py
|
||||
│ ├── README.md
|
||||
│ ├── templates
|
||||
│ │ └── mitaka
|
||||
│ │ └── manila.conf
|
||||
│ ├── tests
|
||||
│ │ ├── basic_deployment.py
|
||||
│ │ ├── gate-basic-trusty-icehouse
|
||||
│ │ ├── gate-basic-trusty-liberty
|
||||
│ │ ├── gate-basic-trusty-mitaka
|
||||
│ │ ├── gate-basic-xenial-mitaka
|
||||
│ │ ├── README.md
|
||||
│ │ └── tests.yaml
|
||||
│ └── tox.ini
|
||||
├── test-requirements.txt
|
||||
└── unit_tests
|
||||
├── __init__.py
|
||||
├── test_lib_new_manila_plugin_handlers.py
|
||||
└── test_new_manila_plugin_handlers.py
|
||||
|
||||
This is a reactive source charm layer that is used to build the final charm.
|
||||
The files in the template are:
|
||||
|
||||
src/
|
||||
The source layer for the charm. This layer is compiled with other layers to
|
||||
build the full charm.
|
||||
|
||||
src/config.yaml
|
||||
This is the config for the charm. This will almost certainly need to be
|
||||
extended to support the configuration options that the backend provider needs
|
||||
to set in the config for ``manila.conf``.
|
||||
|
||||
src/layer.yaml
|
||||
The ``layer.yaml`` describes the reactive layers that are used to create the
|
||||
charm. Unless the charm needs to relate to something else in addition to the
|
||||
manila charm, then this file doesn't need to be altered.
|
||||
|
||||
src/metadata.yaml
|
||||
The ``metadata.yaml`` file describes the relations to other charms. This
|
||||
file won't need changing unless additional relations are needed for the charm
|
||||
(e.g. a connection to a master controller charm or something similar).
|
||||
|
||||
src/tox.ini
|
||||
The ``tox.ini`` file contains the configuration for ``tox`` to unittest, lint
|
||||
and build a charm. This file shouldn't need changing.
|
||||
|
||||
src/reactive/{package}_handlers.py
|
||||
This file contains the reactive handlers for the charm. If the default
|
||||
behavior of the charm needs to be altered then this is the starting point
|
||||
for that change.
|
||||
|
||||
src/lib/charm/openstack/{package}.py
|
||||
This file contains the charm definition and logic to determine if the
|
||||
configuration is complete and to generate the configuration for the manila
|
||||
charm. **This file will need editing**.
|
||||
|
||||
src/templates/{release}/manila.conf
|
||||
The template file makes it easier to write out the configuration section that
|
||||
will be supplied to the ``manila.conf`` file in the manila charm. **This
|
||||
file will need editing**. If the earliest release is something other than
|
||||
mitaka, then the folder name will need to be renamed to the earliest release.
|
||||
|
||||
src/tests/*
|
||||
These are the functional tests that can be run on the charm to demonstrate
|
||||
that it is functionally correct. The version in the template checks that the
|
||||
configuration gets written. However, it will probably have to be edited to
|
||||
provide sufficient config to the plugin charm so that it will not be blocked.
|
||||
|
||||
unit_tests/*
|
||||
The unit_tests files may be used to demonstrate that the functions used
|
||||
within the charm layer are correct, which is especially useful for reducing
|
||||
regression tests. It is recommended that the unit_tests files are inspected
|
||||
and altered to be test any functionality that is included in the charm.
|
||||
|
||||
|
||||
How the subordinate charm updates the manila.conf file
|
||||
======================================================
|
||||
|
||||
The basic theory of operation of a manila configuration plugin charm is to use
|
||||
the config that is presented to the charm to write a configuration section for
|
||||
a backend for manila. The charm may also need to install software, and the
|
||||
charm can be altered to do this, but normally the manila software comes with
|
||||
all of the supported drivers as part of the code base. Here only the
|
||||
configuration is considered.
|
||||
|
||||
The plugin charm has access to the same authentication credentials as the
|
||||
manila charm if it needs to configure OpenStack services or needs to write
|
||||
authentication credentials to other configuration files. The manila-generic
|
||||
charm needs to configure [nova], [neutron] and [glance] sections and uses the
|
||||
authentication data to do so.
|
||||
|
||||
1. The charm author should first modify the
|
||||
``src/templates/mitaka/manila.conf`` file which contains the section that
|
||||
will be used to configure the backend.
|
||||
|
||||
2. Then the charm author will modify the
|
||||
``src/lib/charm/openstack/{pacakge}.py`` file.
|
||||
|
||||
Configuration Options
|
||||
---------------------
|
||||
|
||||
It is probably that the configuration charm will use config parameters as part
|
||||
of the template. This are exposed via the ``config.`` option in the template,
|
||||
and on the ``options`` member in the charm instance. It is sometimes useful to
|
||||
compute a configuration option that can be used in the template or charm (e.g.
|
||||
a boolean to say that the config is available).
|
||||
|
||||
A computed config option is done as:
|
||||
|
||||
.. code:: python
|
||||
|
||||
@charms_openstack.adapters.config_property
|
||||
def is_config_okay(config):
|
||||
if config.something and config.something_else > 10:
|
||||
return True
|
||||
return False
|
||||
|
||||
This can then be used as ``{{ config.is_config_okay}}`` in a template or in the
|
||||
charm instance as:
|
||||
|
||||
.. code:: python
|
||||
|
||||
def some_method(self):
|
||||
if self.options.is_config_okay:
|
||||
do_something_if_the_config_is_okay()
|
||||
else:
|
||||
do_something_else()
|
||||
|
||||
|
||||
Generating the configuration section
|
||||
------------------------------------
|
||||
|
||||
The configuration for ``manila.conf`` is generated in the
|
||||
``get_config_for_principal()`` method in the charm class defined in the
|
||||
``src/lib/charm/openstack`` directory. The key steps to be aware of are:
|
||||
|
||||
1. If the configuration is not complete or can't be generated for the backend
|
||||
then the function should return an empty dictionary: {}
|
||||
|
||||
2. The default template only assumes that the ``manila-plugin.available`` state
|
||||
is required to render the config. If your interfaces (via states) are
|
||||
needed then they should be added as appropriate.
|
||||
|
||||
PEP8 the charm
|
||||
==============
|
||||
|
||||
It's useful to verify that the charm code is valid Python code and that all the
|
||||
imports needed are met and other *linting* issues. With ``tox`` installed,
|
||||
this can easily be done by:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
tox -e pep8
|
||||
|
||||
|
||||
Build Charm
|
||||
===========
|
||||
|
||||
The charm now needs to be built to pull down all the interfaces and layers the
|
||||
charm depends on and rolled into the built charm which can be deployed.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
tox -e build
|
||||
|
||||
Deploy/Test Charm
|
||||
=================
|
||||
|
||||
Testing/deploying the charm can only be really done with a fragment of an
|
||||
OpenStack system and the tox ``func27-smoke`` target gives an easy method to
|
||||
deploy and verify the small system. Note that once it is deployed, if there
|
||||
are errors then they can be modified and the charm rebuilt and re-deployed. A
|
||||
test session might look something like:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cd build/builds/{package-name}
|
||||
tox -e func27-smoke # this will run the gate-basic-xenial-mitaka
|
||||
|
||||
This will get an OpenStack fragment running. The gate-basic-xenial-mitaka may
|
||||
need to be changed if that target is not supported by the charm.
|
||||
|
||||
|
||||
Then if there are errors:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
cd {package-name}
|
||||
# make changes
|
||||
tox -e build
|
||||
juju remove-relation manila {package-name}
|
||||
# wait until the subordinate is removed/and or destroy the manila unit.
|
||||
# If destroying the manila unit, then remember to redploy it
|
||||
juju upgrade-charm --path=build/builds/{package-name} {package-name}
|
||||
juju add-relation manila {package-name}
|
||||
|
||||
This will re-install the subordinate charm which may show further errors, etc.
|
||||
|
||||
``juju status`` will now show both charms deployed.
|
||||
|
|
@ -242,6 +242,7 @@ Create Flavors
|
|||
It's safe to skip this for Mitaka. For Newton and later, there are no pre-populated flavors. Check if flavors exist, and if not, create them:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
openstack flavor list
|
||||
|
||||
.. code:: bash
|
||||
|
|
|
|||
Loading…
Reference in New Issue