helmspray

README

Helm Spray

What is Helm Spray?

This is a Helm plugin to install or upgrade sub-charts one by one from an umbrella chart.

It works like helm upgrade --install, except that it upgrades or installs each sub-charts according to a weight (>=0) set on each sub-chart. All sub-charts of weight 0 are processed first, then sub-charts of weight 1, etc. Chart weight shall be specified using the <chart name>.weight value.

Each sub-chart is deployed under a specific Release named <chart name or alias>, enabling a later individual upgrade targeting this sub-chart only. All global or individual upgrade should still be done on the umbrella chart.

Continuous Integration & Delivery

Helm Spray is building and delivering under Travis.

Usage

  $ helm spray [flags] CHART

Helm Spray shall always be called on the umbrella chart, whatever it is for upgrading the full set of charts, or for upgrading individual sub-charts (using the --target option). For a proper usage of helm spray, the umbrella chart shall have a requirement.yaml file listing all the sub-charts to be deployed (under the dependencies element). Sub-charts may have an alias element and the condition element shall be set to the value <chart name or alias>.enabled. Here is an example of requirement.yaml file for an umbrella chart having three sub-charts, one of them having an alias:

dependencies:
- name: micro-service-1
  version: ~1.2
  repository: http://chart-museum/charts
  condition: micro-service-1.enabled
- name: micro-service-2
  version: ~2.3
  repository: http://chart-museum/charts
  condition: micro-service-2.enabled
- name: micro-service-3
  alias: ms3
  version: ~1.1
  repository: http://chart-museum/charts
  condition: ms3.enabled

A "values" file shall also be set with the weight it be applied to each individual sub-chart. This weight shall be set in the <chart name or alias>.weight element. A good practice is that thei weigths are statically set in the default values.yaml file of the umbrella chart (and not in a yaml file provided using the -f option), as sub-chart's weight is not likely to change over time. As an example corresponding to the above requirement.yaml file, the values.yaml file of the umbrella chart might be:

micro-service-1:
  weight: 0

micro-service-2:
  weight: 1

ms3:
  weight: 2

Several sub-charts may have the same weight, meaning that they will be upgraded together. Upgrade of sub-charts of weight n+1 will only be triggered when upgrade of sub-charts of weight n is completed.

Helm Spray creates one helm Release per sub-chart. Releases are individually upgraded when running the helm spray process, in particular when using the --target option. The name and version of the umbrella chart is set as the Chart name for all the Revisions.

NAME            REVISION        UPDATED                         STATUS          CHART           APP VERSION     NAMESPACE
micro-service-1 12              Wed Jan 30 17:19:15 2019        DEPLOYED        solution-0.1    0.1             default
micro-service-2 21              Wed Jan 30 17:18:55 2019        DEPLOYED        solution-0.1    0.1             default
ms3             7               Wed Jan 30 17:18:45 2019        DEPLOYED        solution-0.1    0.1             default

Note: if an alias is set for a sub-chart, then this is this alias that should be used with the --target optioni, not the sub-chart name.

Values:

The umbrella chart gathers several components or micro-services into a single solution. Values can then be set at many different places:

• At micro-service level, inside the values.yaml file of each micro-service chart: these are common defaults values set by the micro-service developer, independently from the deployment context and location of the micro-service
• At the solution level, inside the values.yaml file of the umbrella chart: these are values complementing or overwriting default values of the micro-services sub-charts, usually formalizing the deployment topology of the solution and giving the standard configuration of the underlying micro-services for any deployments of cwthis specific solution
• At deployment time, using the --values/-f or --set flags: this is the placeholder for giving the deployment-dependent values, specifying for example the exact database url for this deployment, the exact password value for this deployment, the targeted remote server url for this deployment, etc. These values usually change from one deployment of the solution to another.

Within the micro-services paradigm, decoupling between micro-services is one of the most important criteria to respect. While values con be provided in a per-micro-service basis for the first and last places mentioned above, Helm only allows one single values.yaml file in the umbrella chart. All solution-level values should then be gathered into a single file, while it would have been better to provide values in several files, on a one-file-per-micro-service basis (to ensure decoupling of the micro-services configuration, even at solution level). Helm Spray is consequently adding this capability to have several values file in the umbrella chart and to include them into the single values.yaml file using the #! {{ .File.Get <file name> }} directive.

• The file to be included shall be a valid yaml file.
• It is possible to only include a sub-part of the yaml content by picking an element of the File.Get, specifying the path to be extracted and included: #! {{ pick (.File.Get <file name>) for.bar }}. Only paths targeting a Yaml element or a leaf value can be provided. Paths targeted lists are not supported.
• It is possible to indent the included content using the indent directive: #! {{ .File.Get <file name> | indent 2 }}, `#! {{ pick (.File.Get ) for.bar | indent 4 }}

Note: The {{ .File.Get ... }} directive shall be prefixed by #! as the values.yaml file is parsed both with and without the included content. When parsed without the included content, it shall still be a valid yaml file, thus mandating the usage of a comment to specify the {{ .File.Get ... }} clause that is by default supported by neither yaml nor Helm in default values files of charts. Usage of #! (with a bang '!') allows differentiating the include clauses from regular comments. Note also that when Helm is parsing the values.yaml file without the included content, some warning may be raised by helm if yaml elements are nil or empty (while they are not with the included content). A typical warning could be: 'Warning: Merging destination map for chart 'my-solution'. The destination item 'bar' is a table and ignoring the source 'bar' as it has a non-table value of: '

Example of values.yaml:

micro-service-1:
  weight: 0
#! {{ .File.Get ms1.yaml }}

micro-service-2:
  weight: 1
#! {{ pick (.File.Get ms2.yaml) foo | indent 2 }}

ms3:
  weight: 2
  bar:
#! {{ pick (.File.Get ms3.yaml) bar.baz | indent 4 }}
# To prevent from having a warning when the file is processed by Helm, a fake content may be set here.
# Format of the added dummy elements fully depends on the application's values structure
    dummy:
      dummy: "just here to prevent from a warning"

Flags:

      --debug                            enable helm debug output (also include spray verbose output)
      --dry-run                          simulate a spray
      --force                            force resource update through delete/recreate if needed
  -h, --help                             help for helm
  -n, --namespace string                 namespace to spray the chart into. (default "default")
      --prefix-releases string           prefix the releases by the given string, resulting into releases names formats:
                                             "<prefix>-<chart name or alias>"
                                         Allowed characters are a-z A-Z 0-9 and -
      --prefix-releases-with-namespace   prefix the releases by the name of the namespace, resulting into releases names formats:
                                             "<namespace>-<chart name or alias>"
      --reset-values                     when upgrading, reset the values to the ones built into the chart
      --reuse-values                     when upgrading, reuse the last release's values and merge in any overrides from the command line via '--set' and '-f'.
                                         If '--reset-values' is specified, this is ignored.
      --set string                       set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)
  -t, --target strings                   specify the subchart to target (can specify multiple). If '--target' is not specified, all subcharts are targeted
  -f, --values strings                   specify values in a YAML file or a URL (can specify multiple)
      --verbose                          enable spray verbose output
      --version string                   specify the exact chart version to install. If this is not specified, the latest version is installed

Install

  $ helm plugin install https://github.com/gemalto/helm-spray

The above will fetch the latest binary release of helm spray and install it.

Developer (From Source) Install

If you would like to handle the build yourself, instead of fetching a binary, this is how recommend doing it.

First, set up your environment:

• You need to have Go installed. Make sure to set $GOPATH
• If you don't have Glide installed, this will install it into $GOPATH/bin for you.

Clone this repo into your $GOPATH. You can use go get -d github.com/gemalto/helm-spray for that.

$ cd $GOPATH/src/github.com/gemalto/helm-spray
$ make bootstrap build
$ SKIP_BIN_INSTALL=1 helm plugin install $GOPATH/src/github.com/gemalto/helm-spray

That last command will skip fetching the binary install and use the one you built.

Documentation

Overview

(c) Copyright 2018, Gemalto. All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.