From 31b113d402a0b5e23113e8ac972785fc36c03cb8 Mon Sep 17 00:00:00 2001 From: Sagi Shnaidman Date: Tue, 28 Jan 2020 14:48:21 +0200 Subject: [PATCH] Add Openstack guidelines spec from Ansible These may not be 100% perfect, but they are a good starting place and we can improve them over time. Change-Id: Ifb21554d67863b4e4e964f3e98263c3dafcb607f --- docs/openstack_guidelines.rst | 70 +++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 docs/openstack_guidelines.rst diff --git a/docs/openstack_guidelines.rst b/docs/openstack_guidelines.rst new file mode 100644 index 00000000..d4811970 --- /dev/null +++ b/docs/openstack_guidelines.rst @@ -0,0 +1,70 @@ +.. _OpenStack_module_development: + +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. + +.. 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 + details about the deployment choices their cloud provider made. A best + effort should be made to present one sane interface to the Ansible user + regardless of deployer choices. +* 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. +* All modules should work appropriately against all existing versions of + OpenStack regardless of upstream EOL status. The reason for this is that + the Ansible modules are for consumers of cloud APIs who are not in a + position to impact what version of OpenStack their cloud provider is + running. It is known that there are OpenStack Public Clouds running rather + old versions of OpenStack, but from a user point of view the Ansible + modules can still support these users without impacting use of more + modern versions. + +Libraries +--------- + +* All modules should use ``OpenStackModule`` from + ``ansible_collections.openstack.cloud.plugins.module_utils.openstack`` + as their base class. +* 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 + `