openstack-helm/doc/source/specs/multi-os.rst

Multi-OS Support

Include the URL of your Storyboard RFE:

https://storyboard.openstack.org/#!/story/2005130

Problem Description

Our 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:

1. Helm charts for which we use official upstream images. (Called further Category A helm charts)
2. 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:

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:

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.

1. 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.
2. 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.
3. 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