Section 3.2 - Setting up the Helm Chart Repository

Overview

To achieve disaster recovery, auditability, rollbacks, and infrastructure as code, the OpenShift library deploys applications using Helm from a chart stored in a GitHub repository.

Helm is a tool for templating and managing Kubernetes configuration files and, by extension, OpenShift configuration files. Any element in OpenShift can be expressed as as yaml or JSON. Helm lets you take that yaml and organize it, turn them into a template, and, through tiller, use them to deploy to your cluster.

This Helm chart repository is what the OpenShift SDP library will use to deploy your application to OpenShift. In it, you should create a Helm chart that defines the various DeploymentConfigs, Services, Routes, and other objects your application needs to function.

Create a Repository

Use an SCM like GitHub to create a repository to store your Helm chart. This way you can access, share and maintain the Helm chart like any other piece of code. Name it whatever you like, but helm-configuration-repository makes sense. It can be public or private, so long as the GitHub account Jenkins is using can read from it and write back to it.

Initialize The Helm Repository

Assuming you’ve created an empty GitHub repository for your helm chart, you can run:

helm create <repo_name>
cd <repo_name>
git remote add origin <helm repo url>
git add --all
git commit -m "initializing chart repo"
git push -u origin master

Once that’s done you should

Delete the yaml files that were automatically created when helm create was called. These are example helm templates, and we don’t need them.
Delete the contents of templates/_helpers.tpl and templates/NOTES.txt. We want to keep those files, but provide our own content.
Update Chart.yaml to properly describe your new chart.

For more information on Helm charts, check out the [Helm documentation].

SDP Helm Conventions

SDP pushes and pulls to this chart repository to keep it up to date with the image tags of deployed containers.

For each application repository that SDP will be building, add a key under image_shas in values.yaml. If there is no image_shas key, create one.

As an example, if there was a repository called sample-app, your values.yaml would include:

image_shas:
    sample_app:

Because YAML key’s cannot contain hyphens, the openshift converts them to underscores and expects that value under image_shas

Your template would then be able to specify the image for a deployment via:

image: docker-registry.default.svc:5000/demo/sample-app:{{ .Values.image_shas.sample_app }}

At this point, you should take some time to finish fleshing out your Helm chart to reflect how you wish to deploy your app.

Information on Writing Templates

The Helm documentation on writing charts and templates is a good place to start learning how to create your helm chart. There are a few additional tips that are useful for writing charts and templates for OpenShift.

The first useful tip is that it’s possible to create objects in OpenShift using the web console, and then view its corresponding yaml file either by using the "edit YAML" option or using the OpenShift CLI. The challenge is identifying and deleting fields that are automatically generated by the cluster or added by default. This removes unnecessary clutter from the template and, in the case of automatically generated fields such as the resourceVersion, prevents errors in the cluster.

$ oc get all -o yaml

The second useful tip, which mostly applies if you are copying YAML files from OpenShift, is that the apiVersion field for OpenShift-exclusive object types need to be modified for Helm to process the template correctly. Refer to the table in this OpenShift blog post mapping the object types, Kind, to the appropriate apiVersion.

The third tip is knowing that each container being deployed likely needs at least three things: a DeploymentConfig, a Service, and a Route. The DeploymentConfig manages creating and running the container, the Service makes it possible to connect to that container within the cluster, and the Route exposes that service so it can be connected to from outside the cluster. You can see example templates for each of these in the sdp-helm-chart repository, which is itself a Helm chart.

Add The Values Files

In addition to the values.yaml file created when helm create was run, you need a values.<APP_ENV>.yaml file for each application environment you created when running provision_app_envs.sh. Be sure to substitute <APP_ENV> with the "short_name" of the application environment. For example, if you created a dev and prod environment, you might create those files with the command:

cp values.yaml values.prod.yaml]

The purpose of these separate files is so that you can provide separate configurations (database URLs, names, etc.) for different environments. Now, whenever you use the deploy_to dev step in your pipeline, it will deploy a helm chart using values.dev.yaml.

The SDP will automatically update the image sha value discussed earlier, but you should now modify the different values files with their environment-specifc variables.

Updating the Pipeline Configuration

If you recall from earlier in this guide, in the page on the Pipeline Configuration Repository, there were some settings for the OpenShift SDP library that may not have been clear before this point in the guide.

libraries{
  //...
  openshift{
    url = "https://my-openshift-cluster.ocp.example.com:8443"
    helm_configuration_repository = "https://github.com/kottoson-bah/sdp-example-helm-config.git"
    helm_configuration_repository_credential = github
    tiller_namespace = my-app-tiller
    tiller_credential = my-app-tiller-credential
  }
}

Here’s what you should now put for each of these settings

Table 1. Provisioned OpenShift Infrastructure
Setting	Description
url	The master URL of your OpenShift cluster i.e. the one you use to log in
helm_configuration_repository	The URL for your helm configuration repository i.e. the one you use to clone it using https
helm_configuration_repository_credential	The ID of the username/password credential in Jenkins that can be used to read to and write from your helm repository
tiller_namespace	The OpenShift namespace/project hosting the tiller server (e.g. demo-tiller)
tiller_credential	The credential for the tiller server you created in the previous section (e.g. demo-tiller)

Also, if you haven’t already, update the application environments in your pipeline config file to reflect the application environments you have just deployed.

Closing Summary

In order to enable automatic deployments to OpenShift, this guide covered the following:

Setting up Application Environments on OpenShift using provision_app_envs.sh
Creating a Helm chart repository that defines how to deploy your application
Modifying Jenkins and the pipeline config file to use the helm chart repository and the provisioned application environments

Next Steps

Section 3.1 - Creating the Application Environments