118cf3ece6
* Moves developer docs for AWS, ovirt, and openstack modules out of lib/ansible/, integrates them with dev_guide, with abadger's fix to make python snippets pass rstcheck
60 lines
2.6 KiB
ReStructuredText
60 lines
2.6 KiB
ReStructuredText
.. _OpenStack_module_development:
|
|
|
|
OpenStack Ansible Modules
|
|
=========================
|
|
|
|
These are a set of modules for interacting with OpenStack as either an admin
|
|
or an end user. If the module does not begin with ``os_``, it's either deprecated
|
|
or soon to be. This document serves as developer coding guidelines for
|
|
modules intended to be here.
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
Naming
|
|
------
|
|
|
|
* All module names should start with ``os_``
|
|
* Name any module that a cloud consumer would expect to use after the logical resource it manages: ``os_server`` not ``os_nova``. This naming convention acknowledges that the end user does not care which service manages the resource - that is a deployment detail. For example cloud consumers may not know whether their floating IPs are managed by Nova or Neutron.
|
|
* Name any module that a cloud admin would expect to use with the service and the resource: ``os_keystone_domain``.
|
|
* If the module is one that a cloud admin and a cloud consumer could both use,
|
|
the cloud consumer rules apply.
|
|
|
|
Interface
|
|
---------
|
|
|
|
* If the resource being managed has an id, it should be returned.
|
|
* If the resource being managed has an associated object more complex than
|
|
an id, it should also be returned.
|
|
|
|
Interoperability
|
|
----------------
|
|
|
|
* It should be assumed that the cloud consumer does not know a bazillion
|
|
details about the deployment choices their cloud provider made, and a best
|
|
effort should be made to present one sane interface to the Ansible user
|
|
regardless of deployer insanity.
|
|
* All modules should work appropriately against all existing known public
|
|
OpenStack clouds.
|
|
* It should be assumed that a user may have more than one cloud account that
|
|
they wish to combine as part of a single Ansible-managed infrastructure.
|
|
|
|
Libraries
|
|
---------
|
|
|
|
* All modules should use ``openstack_full_argument_spec`` to pick up the
|
|
standard input such as auth and ssl support.
|
|
* All modules should include ``extends_documentation_fragment: openstack``.
|
|
* All complex cloud interaction or interoperability code should be housed in
|
|
the `openstacksdk <http://git.openstack.org/cgit/openstack/openstacksdk>`_
|
|
library.
|
|
* All OpenStack API interactions should happen via the openstacksdk and not via
|
|
OpenStack Client libraries. The OpenStack Client libraries do no have end
|
|
users as a primary audience, they are for intra-server communication.
|
|
|
|
Testing
|
|
-------
|
|
|
|
* Integration testing is currently done in `OpenStack's CI system <https://git.openstack.org/cgit/openstack/openstacksdk/tree/openstack/tests/ansible>`_
|
|
* Testing in openstacksdk produces an obvious chicken-and-egg scenario. Work is under
|
|
way to trigger from and report on PRs directly.
|