.. _OpenStack_module_development: OpenStack Ansible Modules ========================= The OpenStack collection (on `Galaxy `_, source code `repository `_) 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 `_ 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 `_ * Testing in openstacksdk produces an obvious chicken-and-egg scenario. Work is under way to trigger from and report on PRs directly.