From 574bcac277b4b69015aee21e920b47cb10516aaa Mon Sep 17 00:00:00 2001 From: Monty Taylor Date: Thu, 11 Jun 2015 02:29:28 +0200 Subject: [PATCH] Add developer docs for the OpenStack modules --- lib/ansible/modules/cloud/openstack/README.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 lib/ansible/modules/cloud/openstack/README.md diff --git a/lib/ansible/modules/cloud/openstack/README.md b/lib/ansible/modules/cloud/openstack/README.md new file mode 100644 index 0000000000..a9b22234ad --- /dev/null +++ b/lib/ansible/modules/cloud/openstack/README.md @@ -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.