From 343b085d5bf06341291aa8f3cca4b989bf832846 Mon Sep 17 00:00:00 2001 From: Alex Kavanagh Date: Thu, 23 Feb 2017 09:14:25 -0500 Subject: [PATCH] Add manila plugin template documentation This patchset adds "how to do a manila plugin" documentation to the charm guide. Change-Id: I02146aeed69691b0dd3c55169eea56705c7621a2 --- doc/source/creating-charms.rst | 3 +- doc/source/new-manila-charm.rst | 292 ++++++++++++++++++++++++++++++++ doc/source/openstack-on-lxd.rst | 1 + 3 files changed, 295 insertions(+), 1 deletion(-) create mode 100644 doc/source/new-manila-charm.rst diff --git a/doc/source/creating-charms.rst b/doc/source/creating-charms.rst index f991e7d9..9e8677a4 100644 --- a/doc/source/creating-charms.rst +++ b/doc/source/creating-charms.rst @@ -5,8 +5,9 @@ Create A Charm .. toctree:: :maxdepth: 1 - :hidden: charm-anatomy new-sdn-charm new-api-charm + new-manila-charm + diff --git a/doc/source/new-manila-charm.rst b/doc/source/new-manila-charm.rst new file mode 100644 index 00000000..38e4bd4f --- /dev/null +++ b/doc/source/new-manila-charm.rst @@ -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. diff --git a/doc/source/openstack-on-lxd.rst b/doc/source/openstack-on-lxd.rst index bd9d701a..53fe2351 100644 --- a/doc/source/openstack-on-lxd.rst +++ b/doc/source/openstack-on-lxd.rst @@ -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