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.

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.