cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge pull request #1518 from emonty/openstack-module-docs

Browse source 
Add developer docs for the OpenStack modules
This commit is contained in:
Brian Coca 2015-06-15 09:11:50 -04:00
commit b69fb1ac3a
1 changed files with 49 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

49
cloud/openstack/README.md Normal file
View file

@ -0,0 +1,49 @@
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.
Naming
------
* All modules should start with os_
* If the module is one that a cloud consumer would expect to use, it should be
named after the logical resource it manages. Thus, os\_server not os\_nova.
The reasoning for this is that there are more than one resource that are
managed by more than one service and which one manages it is a deployment
detail. A good example of this are floating IPs, which can come from either
Nova or Neutron, but which one they come from is immaterial to an end user.
* If the module is one that a cloud admin would expect to use, it should be
be named with the service and the resouce, such as os\_keystone\_domain.
* If the module is one that a cloud admin and a cloud consumer could both use,
the cloud consumer rules apply.
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 extends\_documentation\_fragment: openstack to go along
with openstack\_full\_argument\_spec.
* All complex cloud interaction or interoperability code should be housed in
the [shade](http://git.openstack.org/cgit/openstack-infra/shade) library.
* All OpenStack API interactions should happen via shade 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. The
python-openstacksdk is the future there, and shade will migrate to it when
its ready in a manner that is not noticable to ansible users.