Helm is a package manager for Kubernetes. Helm uses a packaging format called charts, which include all of the Kubernetes resources that are required to deploy an application, such as deployments, services, ingress, and so on. Helm charts are very useful for installing applications and performing upgrades on a Kubernetes cluster.
In chapter 3 of my e-book Getting GitOps: A Practical Platform with OpenShift, Argo CD, and Tekton, I discuss the basics of creating and using Helm charts. I also dig into the the use case of creating a post-install and post-upgrade job.
However, that chapter provided a very basic example that focused only on what's necessary to create and deploy a Helm chart. This article will demonstrate some more advanced techniques to create a chart that could be installed more than once in the same namespace. It also shows how you could easily install a dependent database with your chart.
The source code for this example can be found in the GitHub repository that accompanies my book.
The use case: How to install a dependent database with a Helm chart
Chapter 1 of my book outlines the Quarkus-based person-service, a simple REST API service that reads and writes personal data from and into a PostgreSQL database. A Helm chart packages this service, and needs to provide all the dependencies necessary to successfully install it. As discussed in that chapter, you have three options to achieve that goal:
- Use the corresponding OpenShift template to install the necessary PostgreSQL database
- Use the CrunchyData Postgres Operator (or any other Operator-defined PostgreSQL database extension) for the database
- Install a dependent Helm chart, such as the PostgreSQL chart by Bitnami, with your chart
No matter which route you take, however, you also need to ensure that your chart can be installed multiple times on each namespace. So let's tackle that task first.
Make the chart installable multiple times in the same namespace
The most crucial step for making your chart installable multiple times in the same namespace is to use generated names for all the manifest files. Therefore, you need an object called Release with the following properties:
Name: The name of the release
Namespace: Where you are going to install the chart
Revision: The revision number of this release (starts at 1 on install, and each update increments it by one)
IsInstall: true if it's an installation process
IsUpgrade: true if it's an upgrade process
If you want to make sure that your chart installation won't conflict with any other installations in the same namespace, do the following:
apiVersion: v1
kind: ConfigMap
metadata:
name: {{ .Release.Name }}-config
labels:
app.kubernetes.io/part-of: {{ .Release.Name }}-chart
data:
APP_GREETING: |-
{{ .Values.config.greeting | default "Yeah, it's openshift time" }}
This creates a ConfigMap with the name of the release, followed by a dash, followed by config. Of course, you now need to make sure that the ConfigMap is being read by the deployment accordingly:
- image: "{{ .Values.deployment.image }}:{{ .Values.deployment.version }}"
envFrom:
- configMapRef:
name: {{ .Release.Name }}-config
[...]
If you are updating all the other manifest files in your Helm's templates folder, you can install your chart multiple times.
$ helm install person-service1 <path to chart>
$ helm install person-service2 <path to chart>
With that task out of the way, we can now consider each of the three potential approaches outlined above in turn.
Install the database via an existing OpenShift template
By far easiest way to install a PostgreSQL database in an OpenShift namespace is by using an OpenShift template. We did it several times in my book. The call is simple:
$ oc new-app postgresql-persistent \
-p POSTGRESQL_USER=wanja \
-p POSTGRESQL_PASSWORD=wanja \
-p POSTGRESQL_DATABASE=wanjadb \
-p DATABASE_SERVICE_NAME=wanjaserver
But how could you automate this process? There is no way to execute this call from within a Helm chart installation. (Well, you could do it by using a pre-install hook, but that would be quite ugly.)
Fortunately, the OpenShift client has a function called process that processes a template. The result of this call is a list of YAML objects that can then be installed into OpenShift.
$ oc process postgresql-persistent -n openshift -o yaml
If you're piping the result into a new file, you would get something like this:
apiVersion: v1
kind: List
items:
- apiVersion: v1
kind: Secret
metadata:
labels:
template: postgresql-persistent-template
name: postgresql
stringData:
database-name: sampledb
database-password: KSurRUMyFI2fiVpx
database-user: user0U4
- apiVersion: v1
kind: Service
[...]
If you're not happy with the default parameters for username, password, and database name, call the process function with the -p PARAM=VALUE option:
$ oc process postgresql-persistent -n openshift -o yaml \
-p POSTGRESQL_USER=wanja \
-p POSTGRESQL_PASSWORD=wanja \
-p POSTGRESQL_DATABASE=wanjadb \
-p DATABASE_SERVICE_NAME=wanjaserver
Place the resulting file into your chart's templates folder, and it will be used to install the database. If you have a closer look at the file, you can see that it's using DATABASE_SERVICE_NAME as manifest names for its Service, Secret, and DeploymentConfig objects, which would make it impossible to install your resulting chart more than once into any namespace.
If you're providing the string -p DATABASE_SERVICE_NAME='pg-{{ .Release.Name }}' instead of the fixed string wanjaserver, then this will be used as the object name for these manifest files. However, if you try to install your Helm chart now, you'll get some verification error messages. This is because oc process generates some top-level status fields that the Helm parser does not understand, so you need to remove them.
The only thing you now need to do is to connect your person-service deployment with the corresponding database instance. Simply add the following entries to the env section of your Deployment.yaml file:
[...]
env:
- name: DB_host
value: pg-{{ .Release.Name }}.{{ .Release.Namespace }}.svc
- name: DB_dbname
valueFrom:
secretKeyRef:
name: pg-{{ .Release.Name }}
key: database-name
- name: DB_user
valueFrom:
secretKeyRef:
name: pg-{{ .Release.Name }}
key: database-user
- name: DB_password
valueFrom:
secretKeyRef:
name: pg-{{ .Release.Name }}
key: database-password
[...]
Your Helm chart is now ready to be packaged and installed:
$ helm package better-helm/with-templ
$ helm upgrade --install ps1 person-service-templ-0.0.10.tgz
Unfortunately, one of the resulting manifest files is a DeploymentConfig, which would only work on Red Hat OpenShift. As a result, this chart can't be installed on any other Kubernetes distribution. So let's discuss other options.
Install a Kubernetes Operator with your chart
Another way to install a dependent database with your Helm chart is to look for a Kubernetes Operator on OperatorHub. If your cluster already has an Operator Lifecycle Manager (OLM) installed (as all OpenShift clusters do), then the only thing you need to do is create a Subscription that describes your desire to install an Operator.
For example, to install the community operator by CrunchyData into OpenShift, you would need to create the following file:
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
name: postgresql-operator
namespace: openshift-operators
spec:
channel: v5
name: postgresql
source: community-operators
sourceNamespace: openshift-marketplace
If you put this file into the crds folder of your Helm chart, Helm takes care of installing the Operator before it processes the template files of the chart. Please note, however, that Helm will never uninstall the custom resource definitions, so the Operator will stay on the Kubernetes cluster.
If you place the following file into the templates folder of the chart, your PostgreSQL database instance will be ready to use:
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: {{ .Release.Name }}-db
labels:
app.kubernetes.io/part-of: {{ .Release.Name }}-chart
spec:
image: registry.developers.crunchydata.com/crunchydata/crunchy-postgres:centos8-13.5-0
postgresVersion: 13
instances:
- name: instance1
dataVolumeClaimSpec:
accessModes:
- "ReadWriteOnce"
resources:
requests:
storage: 1Gi
backups:
pgbackrest:
image: registry.developers.crunchydata.com/crunchydata/crunchy-pgbackrest:centos8-2.36-0
repos:
- name: repo1
volume:
volumeClaimSpec:
accessModes:
- "ReadWriteOnce"
resources:
requests:
storage: 1Gi
Of course, you now need to make sure that your person-service is able to connect to this PostgreSQL instance. Simply add a secretRef to the deployment file with the following content:
[...]
envFrom:
- secretRef:
name: {{ .Release.Name }}-db-pguser-{{ .Release.Name }}-db
prefix: DB_
[...]
This will map all values of the PostgresCluster secret to your deployment with a prefix of DB_, which is exactly what you need.
Now your chart is ready to be packaged and can be installed in any OpenShift namespace:
$ helm package with-crds
$ helm install ps1 person-service-crd-0.0.10.tgz
$ helm uninstall ps1
Install the database by adding a subchart dependency
The last option is to use a subchart within your chart. For this scenario, Helm has a dependency management system that makes it easier for you as a chart developer to use third-party charts. The example that follows makes use of the Bitnami PostgreSQL chart, which you can find on ArtifactHub.
To start, you have to change the Chart.yaml file to add the external dependency. With the following lines, you can add the dependency to the Bitnami PostgreSQL database with the version 11.1.3.
dependencies:
- name: postgresql
repository: https://charts.bitnami.com/bitnami
version: 11.1.3
If you want to define properties from within your values.yaml file, you simply need to use the name of the chart as the first parameter in the tree; in this case, it is postgresql. You can then add all necessary parameters below that key:
postgresql:
auth:
username: wanja
[...]
Next, you need to have a look at the documentation of the Bitnami chart to understand how to use it in your target environment (OpenShift, in this case). Unfortunately, as of the time of this writing, the current documentation is a bit outdated, so you would not be able to install your chart without digging further into the values.yaml file Bitnami supplies to see which security settings you have to set in order to use it with OpenShift's strong enterprise security.
To save you the trouble, I've put together this minimum list of settings you would need to use:
postgresql:
auth:
username: wanja
password: wanja
database: wanjadb
primary:
podSecurityContext:
enabled: false
fsGroup: ""
containerSecurityContext:
enabled: false
runAsUser: "auto"
readReplicas:
podSecurityContext:
enabled: false
fsGroup: ""
containerSecurityContext:
enabled: false
runAsUser: "auto"
volumePermissions:
enabled: false
securityContext:
runAsUser: "auto"
The final step is to make sure that your deployment is able to connect to this database.
[...]
env:
- name: DB_user
value: wanja
- name: DB_password
valueFrom:
secretKeyRef:
name: {{ .Release.Name }}-postgresql
key: password
- name: DB_dbname
value: wanjadb
- name: DB_host
value: {{ .Release.Name }}-postgresql.{{ .Release.Namespace }}.svc
[...]
Now you need to package your chart. Because you're depending on a third-party chart, you need to use the -u option, which downloads the dependencies into the charts folder of your Helm chart.
$ helm package -u better-helm/with-subchart
$ helm install ps1 person-service-sub.0.0.11.tgz
Conclusion
Using Helm charts for your own projects is quite easy, even if you need to make sure certain dependencies are being installed as well. Thanks to Helm's dependency management, you can easily use subcharts with your charts. And thanks to the flexibility of Helm, you can also either use a (processed) template or quickly install a Kubernetes Operator before proceeding.
Check out these articles to learn more about Helm:
And for a more in-depth look at the example explored here, check out my e-book, Getting GitOps: A Practical Platform with OpenShift, Argo CD and Tekton.
Last updated: January 5, 2023