From 5e83b6d369f63b64467ff97aa7be8dcdd2715ba6 Mon Sep 17 00:00:00 2001
From: Steven Dake <stdake@cisco.com>
Date: Thu, 17 Sep 2015 10:51:28 -0700
Subject: [PATCH] Add a customize deployment document
Explain how to customize the deployment with an example and rationale
that is anti-templating :)
Change-Id: I148c89b0608211864d18b60ed7c7082c0b468931
---
doc/customize-deployment.rst | 70 ++++++++++++++++++++++++++++++++++++
doc/index.rst | 1 +
2 files changed, 71 insertions(+)
create mode 100644 doc/customize-deployment.rst
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
=================
--
GitLab