diff --git a/doc/source/devref/images.rst b/doc/source/devref/images.rst index 42ffb0d2fa..1730458f39 100644 --- a/doc/source/devref/images.rst +++ b/doc/source/devref/images.rst @@ -1,3 +1,5 @@ +.. _images documentation: + Images ------ diff --git a/doc/source/specs/multi-os.rst b/doc/source/specs/multi-os.rst new file mode 100644 index 0000000000..3b53d78fc5 --- /dev/null +++ b/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