ffcb93e03b
Add simple script to setup mysql and postgresql databases, this script can be run by users during testing and will be run by CI systems for specific setup before running unit tests. This is exactly what is currently done by OpenStack CI in project-config. This allows to change in project-config the python-db jobs to python-jobs since python-jobs will call this script initially. See also http://lists.openstack.org/pipermail/openstack-dev/2016-November/107784.html Update CONTRIBUTING for this. Change-Id: Ifc16055770e7bf765630814981e3d273876907a7 Needed-By: Icc2a8115cd0b5de165cab2076dbed890f28de172
261 lines
9.5 KiB
ReStructuredText
261 lines
9.5 KiB
ReStructuredText
=================
|
|
How To Contribute
|
|
=================
|
|
|
|
Basics
|
|
~~~~~~
|
|
|
|
* Our source code is hosted on `OpenStack GitHub`_, but please do not send pull
|
|
requests there.
|
|
|
|
* Please follow usual OpenStack `Gerrit Workflow`_ to submit a patch.
|
|
|
|
* Update change log in README.rst on any significant change.
|
|
|
|
* It goes without saying that any code change should by accompanied by unit
|
|
tests.
|
|
|
|
* Note the branch you're proposing changes to. ``master`` is the current focus
|
|
of development, use ``stable/VERSION`` for proposing an urgent fix, where
|
|
``VERSION`` is the current stable series. E.g. at the moment of writing the
|
|
stable branch is ``stable/1.0``.
|
|
|
|
* Please file a launchpad_ blueprint for any significant code change and a bug
|
|
for any significant bug fix.
|
|
|
|
.. _OpenStack GitHub: https://github.com/openstack/ironic-inspector
|
|
.. _Gerrit Workflow: http://docs.openstack.org/infra/manual/developers.html#development-workflow
|
|
.. _launchpad: https://bugs.launchpad.net/ironic-inspector
|
|
|
|
Development Environment
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
First of all, install *tox* utility. It's likely to be in your distribution
|
|
repositories under name of ``python-tox``. Alternatively, you can install it
|
|
from PyPI.
|
|
|
|
Next checkout and create environments::
|
|
|
|
git clone https://github.com/openstack/ironic-inspector.git
|
|
cd ironic-inspector
|
|
tox
|
|
|
|
Repeat *tox* command each time you need to run tests. If you don't have Python
|
|
interpreter of one of supported versions (currently 2.7 and 3.4), use
|
|
``-e`` flag to select only some environments, e.g.
|
|
|
|
::
|
|
|
|
tox -e py27
|
|
|
|
.. note::
|
|
Support for Python 3 is highly experimental, stay with Python 2 for the
|
|
production environment for now.
|
|
|
|
.. note::
|
|
This command also runs tests for database migrations. By default the sqlite
|
|
backend is used. For testing with mysql or postgresql, you need to set up
|
|
a db named 'openstack_citest' with user 'openstack_citest' and password
|
|
'openstack_citest' on localhost. Use the script
|
|
``tools/test_setup.sh`` to set the database up the same way as
|
|
done in the OpenStack CI environment.
|
|
|
|
.. note::
|
|
Users of Fedora <= 23 will need to run "sudo dnf --releasever=24 update
|
|
python-virtualenv" to run unit tests
|
|
|
|
To run the functional tests, use::
|
|
|
|
tox -e func
|
|
|
|
Run the service with::
|
|
|
|
.tox/py27/bin/ironic-inspector --config-file example.conf
|
|
|
|
Of course you may have to modify ``example.conf`` to match your OpenStack
|
|
environment.
|
|
|
|
You can develop and test **ironic-inspector** using DevStack - see
|
|
`DevStack Support`_ for the current status.
|
|
|
|
DevStack Support
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
`DevStack <http://docs.openstack.org/developer/devstack/>`_ provides a way to
|
|
quickly build full OpenStack development environment with requested
|
|
components. There is a plugin for installing **ironic-inspector** on DevStack.
|
|
|
|
Example local.conf
|
|
------------------
|
|
|
|
.. literalinclude:: ../../devstack/example.local.conf
|
|
|
|
|
|
Notes
|
|
-----
|
|
|
|
* Set IRONIC_INSPECTOR_BUILD_RAMDISK to True if you want to build ramdisk.
|
|
Default value is False and ramdisk will be downloaded instead of building.
|
|
|
|
* 1024 MiB of RAM is a minimum required for the default build of IPA based on
|
|
CoreOS. If you plan to use another operating system and build IPA with
|
|
diskimage-builder 2048 MiB is recommended.
|
|
|
|
* Network configuration is pretty sensitive, better not to touch it
|
|
without deep understanding.
|
|
|
|
* This configuration disables Heat and Cinder, adjust it if you need these
|
|
services.
|
|
|
|
Usage
|
|
-----
|
|
|
|
Start introspection for a node manually::
|
|
|
|
source devstack/openrc admin admin
|
|
openstack baremetal introspection start <UUID>
|
|
|
|
Then check status via API::
|
|
|
|
openstack baremetal introspection status <UUID>
|
|
|
|
Writing a Plugin
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
* **ironic-inspector** allows you to hook code into the data processing chain
|
|
after introspection. Inherit ``ProcessingHook`` class defined in
|
|
ironic_inspector.plugins.base_ module and overwrite any or both of
|
|
the following methods:
|
|
|
|
``before_processing(introspection_data,**)``
|
|
called before any data processing, providing the raw data. Each plugin in
|
|
the chain can modify the data, so order in which plugins are loaded
|
|
matters here. Returns nothing.
|
|
``before_update(introspection_data,node_info,**)``
|
|
called after node is found and ports are created, but before data is
|
|
updated on a node. Please refer to the docstring for details
|
|
and examples.
|
|
|
|
Make your plugin a setuptools entry point under
|
|
``ironic_inspector.hooks.processing`` namespace and enable it in the
|
|
configuration file (``processing.processing_hooks`` option).
|
|
|
|
* **ironic-inspector** allows plugins to override the action when node is not
|
|
found in node cache. Write a callable with the following signature:
|
|
|
|
``(introspection_data,**)``
|
|
called when node is not found in cache, providing the processed data.
|
|
Should return a ``NodeInfo`` class instance.
|
|
|
|
Make your plugin a setuptools entry point under
|
|
``ironic_inspector.hooks.node_not_found`` namespace and enable it in the
|
|
configuration file (``processing.node_not_found_hook`` option).
|
|
|
|
* **ironic-inspector** allows more condition types to be added for
|
|
`Introspection Rules`_. Inherit ``RuleConditionPlugin`` class defined in
|
|
ironic_inspector.plugins.base_ module and overwrite at least the following
|
|
method:
|
|
|
|
``check(node_info,field,params,**)``
|
|
called to check that condition holds for a given field. Field value is
|
|
provided as ``field`` argument, ``params`` is a dictionary defined
|
|
at the time of condition creation. Returns boolean value.
|
|
|
|
The following methods and attributes may also be overridden:
|
|
|
|
``validate(params,**)``
|
|
called to validate parameters provided during condition creating.
|
|
Default implementation requires keys listed in ``REQUIRED_PARAMS`` (and
|
|
only them).
|
|
|
|
``REQUIRED_PARAMS``
|
|
contains set of required parameters used in the default implementation
|
|
of ``validate`` method, defaults to ``value`` parameter.
|
|
|
|
``ALLOW_NONE``
|
|
if it's set to ``True``, missing fields will be passed as ``None``
|
|
values instead of failing the condition. Defaults to ``False``.
|
|
|
|
Make your plugin a setuptools entry point under
|
|
``ironic_inspector.rules.conditions`` namespace.
|
|
|
|
* **ironic-inspector** allows more action types to be added for `Introspection
|
|
Rules`_. Inherit ``RuleActionPlugin`` class defined in
|
|
ironic_inspector.plugins.base_ module and overwrite at least the following
|
|
method:
|
|
|
|
``apply(node_info,params,**)``
|
|
called to apply the action.
|
|
|
|
The following methods and attributes may also be overridden:
|
|
|
|
``validate(params,**)``
|
|
called to validate parameters provided during actions creating.
|
|
Default implementation requires keys listed in ``REQUIRED_PARAMS`` (and
|
|
only them).
|
|
|
|
``REQUIRED_PARAMS``
|
|
contains set of required parameters used in the default implementation
|
|
of ``validate`` method, defaults to no parameters.
|
|
|
|
Make your plugin a setuptools entry point under
|
|
``ironic_inspector.rules.conditions`` namespace.
|
|
|
|
.. note::
|
|
``**`` argument is needed so that we can add optional arguments without
|
|
breaking out-of-tree plugins. Please make sure to include and ignore it.
|
|
|
|
.. _ironic_inspector.plugins.base: http://docs.openstack.org/developer/ironic-inspector/api/ironic_inspector.plugins.base.html
|
|
.. _Introspection Rules: http://docs.openstack.org/developer/ironic-inspector/usage.html#introspection-rules
|
|
|
|
Making changes to the database
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
In order to make a change to the ironic-inspector database you must update the
|
|
database models found in ironic_inspector.db_ and then create a migration to
|
|
reflect that change.
|
|
|
|
There are two ways to create a migration which are described below, both of
|
|
these generate a new migration file. In this file there are two functions:
|
|
|
|
* upgrade - The upgrade function is run when
|
|
``ironic-inspector-dbsync upgrade`` is run, and should be populated with
|
|
code to bring the database up to its new state from the state it was in
|
|
after the last migration.
|
|
|
|
* downgrade - The downgrade function should have code to undo the actions which
|
|
upgrade performs, returning the database to the state it would have been in
|
|
before the migration ran.
|
|
|
|
For further information on creating a migration, refer to
|
|
`Create a Migration Script`_ from the alembic documentation.
|
|
|
|
Autogenerate
|
|
------------
|
|
|
|
This is the simplest way to create a migration. Alembic will compare the models
|
|
to an up to date database, and then attempt to write a migration based on the
|
|
differences. This should generate correct migrations in most cases however
|
|
there are some cases when it can not detect some changes and may require
|
|
manual modification, see `What does Autogenerate Detect (and what does it not
|
|
detect?)`_ from the alembic documentation.
|
|
|
|
::
|
|
|
|
ironic-inspector-dbsync upgrade
|
|
ironic-inspector-dbsync revision -m "A short description" --autogenerate
|
|
|
|
Manual
|
|
------
|
|
|
|
This will generate an empty migration file, with the correct revision
|
|
information already included. However upgrade and downgrade are left empty and
|
|
must be manually populated in order to perform the correct actions on the
|
|
database::
|
|
|
|
ironic-inspector-dbsync revision -m "A short description"
|
|
|
|
.. _Create a Migration Script: https://alembic.readthedocs.org/en/latest/tutorial.html#create-a-migration-script
|
|
.. _ironic_inspector.db: http://docs.openstack.org/developer/ironic-inspector/api/ironic_inspector.db.html
|
|
.. _What does Autogenerate Detect (and what does it not detect?): http://alembic.readthedocs.org/en/latest/autogenerate.html#what-does-autogenerate-detect-and-what-does-it-not-detect
|