From 28b80a08cf843f509346bfb67d732c605540d4f6 Mon Sep 17 00:00:00 2001 From: Steven Dake Date: Mon, 12 Sep 2016 12:12:34 -0700 Subject: Revert "Build a more organized doc structure" Our philosophy document is one of our most important documents in he documentation repository. I appreciate in general the notion of reorganizing many of our docs, but this one should be left alone and possibly protected by a roll-call vote in the future. This reverts commit aa517c4bf965f06dc9bcb20220d675ff6e77e94c. Change-Id: Ic17861e823095a1891ac25ddaf429b66e352e30e --- doc/deployment-philosophy.rst | 76 ++++++++++++++++++++++ .../deployment-philosophy.rst | 40 ------------ .../templating-and-customization.rst | 0 doc/deployment-philosophy/templating.rst | 58 ----------------- doc/index.rst | 6 +- 5 files changed, 79 insertions(+), 101 deletions(-) create mode 100644 doc/deployment-philosophy.rst delete mode 100644 doc/deployment-philosophy/deployment-philosophy.rst delete mode 100644 doc/deployment-philosophy/templating-and-customization.rst delete mode 100644 doc/deployment-philosophy/templating.rst diff --git a/doc/deployment-philosophy.rst b/doc/deployment-philosophy.rst new file mode 100644 index 000000000..6711d34f0 --- /dev/null +++ b/doc/deployment-philosophy.rst @@ -0,0 +1,76 @@ +.. _deployment-philosophy: + +============================= +Kolla's Deployment Philosophy +============================= + +Overview +======== + +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 the 100+ node scale small +businesses 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 while enabling flexible deployment models. + +Kolla is a highly opinionated deployment tool out of the box. This permits +Kolla to be deployable with the simple 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. + +Why not Template Customization? +=============================== + +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 development and release +cycles are required in order to successfully add new customizations. +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 than 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 simple, tidy design: custom +configuration sections. + +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 must reference 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 than 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 configuration 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 maintenance burden. Operators don't have to rely on a subjective +approval process for configuration options nor rely on a +development/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/deployment-philosophy/deployment-philosophy.rst b/doc/deployment-philosophy/deployment-philosophy.rst deleted file mode 100644 index 00cbfea26..000000000 --- a/doc/deployment-philosophy/deployment-philosophy.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _deployment-philosophy: - -============================= -Kolla's Deployment Philosophy -============================= - -Overview -======== - -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 the 100+ node scale small -businesses 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 the simple 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. - -Templating and Customization Philosophy -======================================= - -To read up on the Kolla communities template philosphy go to the -:doc:`templating` doc. - -Architecture -============ - -#TODO: Link an image showing the architecture - - -.. toctree:: - :hidden: - - templating diff --git a/doc/deployment-philosophy/templating-and-customization.rst b/doc/deployment-philosophy/templating-and-customization.rst deleted file mode 100644 index e69de29bb..000000000 diff --git a/doc/deployment-philosophy/templating.rst b/doc/deployment-philosophy/templating.rst deleted file mode 100644 index c0511c7a2..000000000 --- a/doc/deployment-philosophy/templating.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. _templating: - -================ -Kolla Templating -================ - -Why not Template Customization? -=============================== - -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 development and release -cycles are required in order to successfully add new customizations. -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 than 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 simple, tidy design: custom -configuration sections. - -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 must reference 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 than 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 configuration 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 maintenance burden. Operators don't have to rely on a subjective -approval process for configuration options nor rely on a -development/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 a5a10b7c7..ae313d412 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -34,14 +34,14 @@ Kolla Overview ============== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - deployment-philosophy/deployment-philosophy - architecture-guide + deployment-philosophy quickstart multinode image-building advanced-configuration + architecture-guide operating-kolla security -- cgit v1.2.3