Add a customize deployment document

Explain how to customize the deployment with an example and rationale
that is anti-templating :)

Change-Id: I148c89b0608211864d18b60ed7c7082c0b468931

2 files changed, 71 insertions, 0 deletions

diff --git a/doc/customize-deployment.rst b/doc/customize-deployment.rst
new file mode 100644
index 000000000..f5f38939c
--- /dev/null
+++ b/doc/customize-deployment.rst
@@ -0,0 +1,70 @@
+Customize an OpenStack Deployment
+=================================
+
+Kolla's Philosphy on Deployment
+-------------------------------
+
+Kolla has an objective to replace the inflexible, painful, resource intensive
+deployment process of OpenStack with a flexible, painless, inexpensive
+deployment process.  Often to deploy OpenStack at one-hundred node scale that
+a small business may require means building a team of OpenStack professionals
+to maintain and manage the OpenStack deployment.  Finding people experienced
+in OpenStack deployment is very difficult and expensive, resulting in a big
+barrier for OpenStack adoption.  Kolla seeks to remedy this set of problems by
+simplifying the deployment process but enabling flexible deployment models.
+
+Kolla is a highly opinionated deployment tool out of the box.  This permits
+Kolla to be deployable with configuration of three key/value pairs.  As an
+operator's experience with OpenStack grows and the desire to customize
+OpenStack services increases, Kolla offers full capability to override every
+OpenStack service configuration option in the deployment.
+
+The Kolla upstream community does not want to place key/value pairs in the
+Ansible playbook configuration options that are not essential to obtaining
+a functional deployment.  If the Kolla upstream starts down the path of
+templating configuration options, the Ansible configuration could conceivably
+grow to hundreds of configuration key/value pairs which is unmanageable.
+Further, as new versions of Kolla are released, there would be independent
+customization available for different versions creating an unsupportable and
+difficult to document environment.  Finally, adding key/value pairs for
+configuration options creates a situation in which a development and release
+cycle is required in order to successfully add a new customization.
+Essentially templating in configuration options is not a scalable solution
+and would result in an inability of the project to execute its mission.
+
+
+Kolla's Solution to Customization
+---------------------------------
+
+Rather then deal with the customization madness of templating configuration
+options in Kolla's Ansible playbooks, Kolla eliminates all the inefficiencies
+of existing deployment tools through a tidy simple design.
+
+During deployment of an OpenStack service, a basic set of default configuration
+options are merged with and overridden by custom ini configuration sections.
+Kolla deployment customization is that simple!  This does create a situation
+in which the Operator references the upstream documentation if a customization
+is desired in the OpenStack deployment.  Fortunately the configuration options
+documentation is extremely mature and well-formulated.
+
+As an example, consider running Kolla in a virtual machine.  In order to
+launch virtual machines from Nova in a virtual environment, it is necessary
+to use the QEMU hypervisor, rather then the KVM hypervisor.  To achieve this
+result, simply modify the file `/etc/kolla/config/nova/nova-compute.conf` and
+add the contents::
+
+    [libvirt]
+    virt_type=qemu
+
+After this change Kolla will use an emulated hypervisor with lower performance.
+Kolla could have templated this commonly modified configuraiton option.  If
+Kolla starts down this path, the Kolla project could end with hundreds of
+config options all of which would have to be subjectively evaluated for
+inclusion or exclusion in the source tree.
+
+Kolla's approach yields a solution which enables complete customization without
+any upstream mainteance burden.  Operators don't have to rely on a subjective
+approval process for configuration options nor rely on a
+developement/test/release cycle to obtain a desired customization.  Instead
+operators have ultimate freedom to make desired deployment choices immediately
+without the approval of a third party.
diff --git a/doc/index.rst b/doc/index.rst
index 984aa911e..3904caaaf 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -35,6 +35,7 @@ Deployment Information
    devenv-heat
    image-building
    deploy-all-in-one-node
+   customize-deployment
 
 Services in Kolla
 =================