Multi OS Spec

This adds an explanation on how to do multi-OS across the
OSH charts.

Change-Id: If8a7fc2a9a1ed99ca8c73009ed0225c11e32e317

doc/source/devref/images.rst

@@ -1,3 +1,5 @@
+.. _images documentation:
+
 Images
 ------
 

doc/source/specs/multi-os.rst

@@ -0,0 +1,212 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+..
+
+================
+Multi-OS Support
+================
+
+Include the URL of your Storyboard RFE:
+
+https://storyboard.openstack.org/#!/story/2005130
+
+Problem Description
+===================
+
+Our :ref:`images documentation` documentation claims to be independent
+of the image. However, some helm charts hard code paths of binaries,
+executables' runtime configurations, etc. Therefore, the image agnostic
+promise is broken.
+
+We need to adapt all the helm charts to remove the hard-coded bits,
+be image agnostic, to allow users to bring their own images.
+
+Use cases
+---------
+
+Allow the usage of multiple base images in OSH.
+
+Proposed Change
+===============
+
+Edit all helm charts to remove possible references to image specific elements,
+replacing them with values overrides or conditionals.
+
+It is important to notice that the helm charts can be split in two categories
+for now:
+
+#. Helm charts for which we use official upstream images.
+   (Called further ``Category A`` helm charts)
+#. Helm charts for which we are building images in osh-images.
+   (Called further ``Category B`` helm charts)
+
+For the ``Category B`` helm charts, an informal testing has been done in the
+past to ensure image independence.
+However, there is nothing exercising this independence in gates. Due to that,
+code of the helm charts might or might not require adapting.
+
+In all cases, we will need to provide different ``profiles``
+(in other words, overrides), to test different image providers use cases in CI.
+
+The ``profiles`` yaml files (for example ``centos_7``, ``opensuse_15``)
+will be provided in each chart's ``example_values/`` directory.
+This folder will be masked to helm through a helmignore file.
+Its content is only for user consumption, not for inclusion in helm charts
+through the File directive.
+In other words, this is a user interface given for convenience merely using
+the abilities of the existing helm charts.
+
+The default ``values.yaml`` need to expose those abilities, by adding a new
+series of keys/values to add the necessary features.
+
+The existing schema for images is the following:
+
+.. code-block:: yaml
+
+   images:
+     tags:
+       imagename1: imagelocation:version-distro
+       imagename2: imagelocation:version-distro
+     pull_policy:
+     local_registry:
+
+For this spec, we assume ``imagename1`` and ``imagename2`` are similarly built.
+This means we do not require any override per image. Instead we require a
+generic kind of override, per application, usable by all charts.
+
+I propose to extend the conf schema with generic software information.
+For example, for apache2:
+
+.. code-block:: yaml
+
+   conf:
+     software:
+       apache2:
+         #the apache2 binary location
+         binary: apache2
+         start_args: -DFOREGROUND
+         stop_args: -k graceful-stop
+         #directory where to drop the config files for apache vhosts
+         conf_dir: /etc/apache2/conf-enabled
+         sites_dir: /etc/apache2/sites-enabled
+
+
+When possible, ``values_overrides/`` will refer to existing
+``helm-toolkit`` functions to avoid repeating ourselves.
+
+This approach:
+
+* Proposes a common approach to software configuration, describing the
+  distro/image specific differences for applications.
+* Exposes security/configuration features of software, allowing deployers to
+  configure software to their needs.
+* Allows different profiles of apache, should some charts require different
+  args for example for the same kind of images, by using yaml dict merges
+  features.
+
+Security Impact
+---------------
+
+No direct impact, as there is no change in the current software/configuration
+location, merely a templating change.
+
+Performance Impact
+------------------
+
+No benchmark was done to evaluate:
+
+* the impact of exposing extra key/values in the helm chart ``values.yaml``
+  file (could possibly have a deployment speed/ram usage increase).
+* the impact of adding functionality in the ``helm-toolkit`` to deal with a
+  common multi-distro aspect (could possibly increase helm chart rendering time)
+* the impact of adding extra conditionals in the helm charts, to deal with
+  multi-distro aspect (if not using the approach above, or when using an
+  alternative approach)
+
+The performance aspect of these point are restricted to deployment, and have
+no performance impact on operations.
+
+Alternatives
+------------
+
+* Not providing a support of multiple images. This leads to ease of
+  maintainance and reduced gate impact, with the risk of having
+  less contributors. For available overrides, users would have to provide
+  many overrides themselves, while this spec proposes a common community
+  approach.
+
+* Create conditionals in the helm charts. This is problematic, as the amount
+  of conditionals will increase and will be harder to maintain.
+  Overrides files are easy to sync between charts.
+
+* Only provide one way to configure software, and expect to always have the
+  same versions. This is further away from the "image independent" contract,
+  with extra burden: We will need to maintain a curated list of versions,
+  deal with the differences of the defaults (selinux/apparmor profiles come to
+  mind as path sensitive for example), and different expectations for
+  operational teams ("The code is not where I expect it to be in the image").
+  Embracing difference could even allow deployers to have different
+  expectations for images, for example: apache+mod_wsgi vs uwsgi standalone
+  or uwsgi + nginx.
+
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  - evrardjp
+
+Work Items
+----------
+
+This spec will be worked helm chart by helm chart, starting with keystone.
+
+A few areas have been identified on changes required.
+Each of them will be a work item.
+
+#.  Make webserver binary path/arguments templated using ``values.yaml``.
+    As expressed above, this allows us to provide different overrides per
+    image/distribution to automatically wire things.
+#.  Dynamically alter webserver environment conditionally in the helm chart.
+    For example, for apache, ensure the necessary modules to run openstack
+    are available and loaded at helm chart deploy time. This will leverage
+    the binaries listed in ``values.yaml``.
+    These series of commands are distribution/image dependent,
+    as commands to list modules to load might differ.
+    However with a few parameters, we can get a very distro independent
+    process which would allow us to load all the required apache modules.
+#.  Alter webserver configuration per distro. Different distros have different
+    expectations in terms of path (including a different series of files
+    required), and it would make the operators' life easier by using their
+    expected distro paths.
+
+Testing
+=======
+
+No change in testing is required, *per se*.
+It is expected the new software configuration would be tested with the
+current practices.
+
+On top of that, the newly provided `example_values/` must
+aim for being tested **as soon as possible upon delivery**. Without tests,
+those examples will decrepit. The changes in CI pipelines for making use
+of `example_values` is outside the scope of this spec.
+
+Documentation Impact
+====================
+
+None more than this spec, as it should be relatively transparent for the
+user. However, extra documentation to explain the usage of ``value_overrides``
+would be welcomed.
+
+References
+==========
+
+None