Adding or configuration apps and charts

Jenkins X 3.x supports the helmfile.yaml file format from the helmfile project that can be used to define the Helm charts you wish to install and their namespace.

Adding Charts

You can then add any charts you wish into the helmfile.yaml file in the releases: section as follows:

- chart: jetstack/cert-manager 
- chart: flagger/flagger

The namespace and version properties of the charts get resolved during deployment via the version stream or you can specify them explicitly.

The prefix of the chart name is the chart repository name. There are a few chart repository names already defined in the helmfile.yaml in the repositories: section. You can add any number of chart repositories to the helmfile.yaml that you need.

We are trying to increase consistency and use canonical names in helmfile.yaml files for chart repositories. You can see the default chart repository names and URLs in this file. Feel free to use any name and URL you like.

Using the CLI

There is also a simple CLI command jx gitops helmfile add to add charts into the helmfile.yaml but its just as easy to do by hand really.

Adding resources

If you want to create one or more kubernetes resources that are not already packaged as a helm chart you can easily add these into your cluster git repository using the local chart layout.

  • create a directory called charts/myname/templates
  • add whatever kubernetes resources you need into charts/myname/templates/myresource.yaml.
    • Use as many files as you wish, just makes sure you use the .yaml extension
  • create a charts/myname/Chart.yaml file and populate the default helm metadata like this example Chart.yaml
  • now reference the charts/myname directory in your helmfile.yaml file in the releases: section via…
- chart: ./charts/myname

Create a Pull Request. You should see the effective kubernetes resources show up as a commit on your Pull Request

Customising charts

You can add a custom values.yaml file to any chart and reference it in the values: section of the helmfile.yaml file.

e.g. to customise a chart such as nginx-ingress you can create a file at charts/nginx-ingress/values.yaml. You can then reference the file in the helmfile.yaml file:

- chart: stable/nginx-ingress
  version: 1.39.1
  name: nginx-ingress
  namespace: nginx
  - versionStream/charts/stable/nginx-ingress/values.yaml.gotmpl
  - charts/nginx-ingress/values.yaml

In the above example we added charts/nginx-ingress/values.yaml after the version stream configuration thats automatically added for you.

You can also use a file called values.yaml.gotmpl if you wish to use go templating of the values file. For example this lets you reference properties from the jx-requirements.yml file via expressions like {{ .Values.jxRequirements.ingress.domain }}.

To see an example of this in action check out the charts/jenkins-x/tekton/values.yaml.gotmpl file in the version stream.

Note that many apps are already configured to make use of the jx-requirements.yml settings via the version stream - but you are free to add your own custom configuration.

Using requirements in charts

The jx-requirements.yml file gets converted to a namespace specific set of values, jx-values.yaml in each namespace so it can be easily consumed in the namespace specific helmfile in helmfiles/$namespace/helmefile.yaml.

If your chart wishes to reuse some of the configuration from the requirements, you can add a reference to the jx-values.yaml file in your chart in the helmfiles/$namespace/helmefile.yaml for your namespace:

- chart: jenkins-x/bucketrepo
  version: 0.1.47
  name: bucketrepo
  # reuse the standard jx values for ingress domain and so forth:
  - jx-values.yaml

There is also a file called jx-global-values.yaml which can include various global values like jx.imagePullSecrets. You can add your own global values into that file if you wish; it will be replicated into the helmfiles/*/jx-values.yaml files so they can be easily consumed in a chart.

Version Stream folder

You may have noticed there is a folder called versionStream inside your clusters git repository. The version stream is used to provide shared configuration such as:

  • the verified versions of charts, images and git repositories which have been tested to work together
  • the default namespace and configuration of charts.

This means we can share canonical files and metadata across clusters and git repositories.

Keeping the version stream in sync

When you upgrade your cluster the local versionStream folder will be upgraded to the latest upstream version stream contents.

We mentioned above how you can cusomize charts. Please try keep as many of your customizations as you can outside of the versionStream folder as you can so that there’s no risk of your configurations getting overridden or causing merge conflicts with upstream version stream changes.

Any changes in the local helmfile.yaml or charts folder are excluded by the upgrade mechanism and so are totally safe.

Last modified February 23, 2021: fix: better layout (1cb365945b)