From 59a483f8bdaab090baf7f98fd0090b4ef0608bb4 Mon Sep 17 00:00:00 2001
From: Thierry Carrez <thierry@openstack.org>
Date: Wed, 8 Feb 2017 15:19:49 +0100
Subject: [PATCH] Document current base services

Introduce the concept of "base services" (external services that
OpenStack components can assume will be present in any OpenStack
installation) and list current base services.

This is intended to reflect the current situation. Changes to the
list should be proposed as subsequent patches.

You can find a more detailed analysis and rationale for this change
in the Architecture WG analysis:

http://git.openstack.org/cgit/openstack/arch-wg/tree/active/base-services.rst

Change-Id: I77ffc000d895c3d8eb27b3b821c6c63f9dd2f675
---
 reference/base-services.rst | 51 +++++++++++++++++++++++++++++++++++++
 reference/index.rst         |  1 +
 2 files changed, 52 insertions(+)
 create mode 100644 reference/base-services.rst

diff --git a/reference/base-services.rst b/reference/base-services.rst
new file mode 100644
index 000000000..2b063d006
--- /dev/null
+++ b/reference/base-services.rst
@@ -0,0 +1,51 @@
+=============
+Base services
+=============
+
+Definition
+==========
+
+Base services are services that OpenStack components can assume will be
+present in any OpenStack deployment. OpenStack components *may* therefore
+leverage advanced features exposed by those base services without fear of
+increasing the overall operational complexity for OpenStack deployers.
+
+
+Current list of base services
+=============================
+
+**An oslo.db-compatible database**
+  OpenStack components store data in a database, using oslo.db as an
+  indirection layer. While most OpenStack deployments use MySQL, other
+  databases are supported.
+
+**An oslo.messaging-compatible message queue**
+  Some inter-process and inter-service communication in OpenStack
+  components is accomplished using message queues, through oslo.messaging
+  as an indirection layer. While most OpenStack deployments use RabbitMQ,
+  other message queues are supported.
+
+**Keystone**
+  Keystone handles AuthN/AuthZ for OpenStack components.
+  Deployments can assume that Keystone will be present to perform that role.
+
+
+Process for addition or removal
+===============================
+
+Leveraging features from a base service (rather than working around
+limitations or badly reinventing the wheel) is key to reaching acceptable
+levels of stability, performance and scaling. However, since they will likely
+have to be deployed in most OpenStack deployments, base services increase the
+operational complexity of running OpenStack. It is therefore very important
+to balance those two sides and conservatively consider proposed additions to
+the base services list, especially when those additions introduce a whole new
+class of operational challenges.
+
+Once services start to make use of advanced features in a base service, it
+is difficult to remove it from the list and make it a specific dependency
+instead. Removals from the base service list should therefore be a rare and
+carefully considered event.
+
+Proposed modifications to this document require a formal vote from the
+Technical Committee membership.
diff --git a/reference/index.rst b/reference/index.rst
index f35596a2c..f4716cfd9 100644
--- a/reference/index.rst
+++ b/reference/index.rst
@@ -14,6 +14,7 @@ Reference documents which need to be revised over time.
    new-projects-requirements
    new-language-requirements
    licensing
+   base-services
    service-project-naming
    project-testing-interface
    irc