1af7c6c003
* Feature freeze date has been merged with Ansible-2.10.0beta1 (#71494) (cherry picked from commitc586d436fa) * Add --allow-disabled to sanity docs (#71524) (cherry picked from commitbc6461432e) * Update intro_patterns.rst (#71542) Call out the trailing comma when specifying a single host. Small snag that took me a while to notice. (cherry picked from commitec3920cef1) * ansible-vault: Fix typo in help message (#71485) (cherry picked from commit215eb730e1) * update install for 2.10 (#71543) * update install for 2.10 (cherry picked from commitf75223d2c6) * User guide overhaul, Table of Contents (#71553) (cherry picked from commitb694dbadfe) * update backport instructions for 2.11 (#71567) * update backport instructions in docs/docsite/rst/community/development_process.rst Co-authored-by: Matt Martz <matt@sivel.net> (cherry picked from commit7f9258b024) * More docs updates to reflect collections ecosystem (#71597) (cherry picked from commit96aee766f4) * DOCS: Mentions ansible-base, adds collections pointers to Community and Dev Guides (#71480) (cherry picked from commit29b20bd1b1) Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Amin Vakil <info@aminvakil.com> Co-authored-by: Matt Deacalion <matt@dirtymonkey.co.uk> Co-authored-by: Fabien Malfoy <fabien.malfoy@laposte.net> Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
58 lines
2.8 KiB
ReStructuredText
58 lines
2.8 KiB
ReStructuredText
.. _OpenStack_module_development:
|
|
|
|
OpenStack Ansible Modules
|
|
=========================
|
|
|
|
The OpenStack collection (on `Galaxy <https://galaxy.ansible.com/openstack/cloud>`_, source code `repository <https://opendev.org/openstack/ansible-collections-openstack.git>`_) contains modules for interacting with OpenStack as either an admin or an end user. If the module does not begin with ``os_``, it is either deprecated or soon to be deprecated. This document serves as developer coding guidelines for modules in this collection.
|
|
|
|
.. 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 <https://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.
|