I recently found myself writing instructions on how to deploy an application to several Kubernetes platform and ended up writing a different Kubernetes manifests for each platform. 95% of the content was the same with just a few different directives based on how the particular platform handles ingress, or if we needed a Registry secret or a TLS certificate.
Kubernetes manifests are very declarative and don’t offer any way to put conditionals or variables that could be set in them. This is both a good and a bad thing. Enter Helm a Package Manager for Kubernetes. Helm allows you to package up your Kubernetes application as a package that can be deployed easily to Kubernetes, One of its features (and the one that interested me) the ability to template out your Kubernetes manifests.
If you already have a Kubernetes manifest its very easy to turn it into a Helm Chart that you can then iterate over and improve as you need to add more flexibility to it. In fact your first iteration of a Helm chart can be as simple as moving your manifests into a new directory and adding a few lines to a Chart.yaml file.
You’ll need the following installed to follow along with this tutorial:
Bring up a test Kubernetes environment using Minikube:
$ minikube start
Starting local Kubernetes v1.7.5 cluster...
Starting VM...
Getting VM IP address...
Moving files into cluster...
Setting up certs...
Connecting to cluster...
Setting up kubeconfig...
Starting cluster components...
Kubectl is now configured to use the cluster.
Wait a minute or so and install Helm’s tiller service to Kubernetes:
$ helm init
$HELM_HOME has been configured at /home/pczarkowski/.helm.
Tiller (the Helm server-side component) has been installed into your Kubernetes Cluster.
Happy Helming!
Create a path to work in:
$ mkdir -p ~/development/my-first-helm-chart
$ cd ~/development/my-first-helm-chart
If it fails out you may need to wait a few more minutes for minikube to become accessible.
Writing a Helm Chart is easier when you’re starting with an existing set of Kubernetes manifests. One of the easiest ways to get a basic working manifest is to ask Kubernetes to run something and then fetch the manifest.
$ mkdir manifests
$ kubectl run example --image=nginx:1.13.5-alpine \
-o yaml > manifests/deployment.yaml
$ kubectl expose deployment example --port=80 --type=NodePort \
-o yaml > manifests/service.yaml
$ minikube service example --url
http://192.168.99.100:30254
All going well you should be able to hit the provided URL and get the “Welcome to nginx!” page. You’ll see you now have two Kubernetes manifests saved. We can use these to bootstrap our helm charts:
$ tree manifests
manifests
├── deployment.yaml
└── service.yaml
0 directories, 2 files
Before we move on we should clean up our environment. We can use the newly created manifests to help:
$ kubectl delete -f manifests
deployment "example" deleted
service "example" deleted
Helm has some tooling to create the scaffolding needed to start developing a
new Helm Chart. We’ll create it with a placeholder name of helm:
$ helm create helm
Creating helm
tree helm
helm
├── charts
├── Chart.yaml
├── templates
│ ├── deployment.yaml
│ ├── _helpers.tpl
│ ├── ingress.yaml
│ ├── NOTES.txt
│ └── service.yaml
└── values.yaml
2 directories, 7 files
Helm will have created a number of files and directories.
Chart.yaml - the metadata for your Helm Chart.values.yaml - values that can be used as variables in your templates.templates/*.yaml - Example Kubernetes manifests._helpers.tpl - helper functions that can be used inside the templates.templates/NOTES.txt - templated notes that are displayed on Chart install.Edit Chart.yaml so that it looks like this:
apiVersion: v1
description: My First Helm Chart - NGINX Example
name: my-first-helm-chart
version: 0.1.0
Copy our example Kubernetes manifests over the provided templates and remove the
currently unused ingress.yaml and NOTES.txt.
$ cp manifests/* helm/templates/
$ rm helm/templates/ingress.yaml
$ rm helm/templates/NOTES.txt
Next we should be able to install our helm chart which will deploy our application to Kubernetes:
$ helm install -n my-first-helm-chart helm
NAME: my-first-helm-chart
LAST DEPLOYED: Tue Oct 3 10:20:57 2017
NAMESPACE: default
STATUS: DEPLOYED
RESOURCES:
==> v1/Service
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
example 10.0.0.210 <nodes> 80:30254/TCP 0s
==> v1beta1/Deployment
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
example 1 1 1 0 0s
Like before we can use minikube to get the URL:
$ minikube service example --url
http://192.168.99.100:30254
Again accessing that URL via your we browser should get you the default NGINX welcome page.
Congratulations! You’ve just created and deployed your first Helm chart. However we’re not quite done yet. use Helm to delete your deployment and then lets move on to customizing the Helm Chart with variables and values:
$ helm del --purge my-first-helm-chart
release "my-first-helm-chart" deleted
Check out helm/values.yaml and you’ll see there’s a lot of variables already
defined by the example that helm provided when you created the helm chart. You’ll
notice that it is has values for nginx in there. This is because Helm also uses
nginx as their example. We can re-use some of the values provided but we should clean
it up a bit.
Edit helm/values.yaml to look like this:
replicaCount: 1
image:
repository: nginx
tag: 1.13.5-alpine
pullPolicy: IfNotPresent
pullSecret:
service:
type: NodePort
We can access any of these values in our templates using the golang templating
engine. For example accessing replicaCount would be written as {{ .Values.replicaCount }}.
Helm also provides information about the Chart and Release which we’ll also utilize.
Update your helm/templates/deployment.yaml to utilize our values:
apiVersion: apps/v1beta1
kind: Deployment
metadata:
creationTimestamp: 2017-10-03T15:03:17Z
generation: 1
labels:
run: "{{ .Release.Name }}"
chart: "{{ .Chart.Name }}-{{ .Chart.Version }}"
release: "{{ .Release.Name }}"
heritage: "{{ .Release.Service }}"
name: "{{ .Release.Name }}"
namespace: default
resourceVersion: "3030"
selfLink: /apis/extensions/v1beta1/namespaces/default/deployments/example
uid: fd03ac95-a84b-11e7-a417-0800277e13b3
spec:
replicas: {{ .Values.replicaCount }}
selector:
matchLabels:
run: "{{ .Release.Name }}"
strategy:
rollingUpdate:
maxSurge: 1
maxUnavailable: 1
type: RollingUpdate
template:
metadata:
creationTimestamp: null
labels:
run: "{{ .Release.Name }}"
spec:
{{- if .Values.image.pullSecret }}
imagePullSecrets:
- name: "{{ .Values.image.pullSecret }}"
{{- end }}
containers:
- image: {{ .Values.image.repository }}:{{ .Values.image.tag }}
imagePullPolicy: {{ .Values.image.pullPolicy }}
name: example
resources: {}
terminationMessagePath: /dev/termination-log
terminationMessagePolicy: File
dnsPolicy: ClusterFirst
restartPolicy: Always
schedulerName: default-scheduler
securityContext: {}
terminationGracePeriodSeconds: 30
status: {}
Note the use of the if statement around image.pullSecret being set. This
sort of conditional becomes very important when making your Helm Chart portable across
different Kubernetes platforms.
Next edit your helm/templates/service.yaml to look like:
apiVersion: v1
kind: Service
metadata:
creationTimestamp: 2017-10-03T15:03:30Z
labels:
run: "{{ .Release.Name }}"
chart: "{{ .Chart.Name }}-{{ .Chart.Version }}"
release: "{{ .Release.Name }}"
heritage: "{{ .Release.Service }}"
name: "{{ .Release.Name }}"
namespace: default
resourceVersion: "3066"
selfLink: /api/v1/namespaces/default/services/example
uid: 044d2b7e-a84c-11e7-a417-0800277e13b3
spec:
clusterIP:
externalTrafficPolicy: Cluster
ports:
- nodePort: 30254
port: 80
protocol: TCP
targetPort: 80
selector:
run: "{{ .Release.Name }}"
sessionAffinity: None
type: "{{ .Values.service.type }}"
status:
loadBalancer: {}
Once your files are written out you should be able to install the Helm Chart:
$ helm install -n second helm
NAME: second
LAST DEPLOYED: Tue Oct 3 10:59:41 2017
NAMESPACE: default
STATUS: DEPLOYED
RESOURCES:
==> v1/Service
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
second 10.0.0.160 <nodes> 80:30254/TCP 1s
==> v1beta1/Deployment
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
second 1 1 1 0 1s
Next use minikube to get the URL of the service, but since we templated the service name to match the release you’ll want to use this new name:
$ minikube service second --url
http://192.168.99.100:30254
Now lets try something fun. Change the image we’re using by upgrading the helm release and overriding some values on the command line:
$ helm upgrade --set image.repository=httpd --set image.tag=2.2.34-alpine second helm
Release "second" has been upgraded. Happy Helming!
LAST DEPLOYED: Tue Oct 3 11:09:30 2017
NAMESPACE: default
STATUS: DEPLOYED
RESOURCES:
==> v1/Service
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
second 10.0.0.160 <nodes> 80:30254/TCP 9m
==> v1beta1/Deployment
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
second 1 1 1 0 9m
Then go to our minikube provided URL and you’ll see a different message It works!.
use minikube delete to clean up your environment:
minikube delete
Deleting local Kubernetes cluster...
Machine deleted.
Helm is a very powerful way to package up your Kubernetes manifests to make them extensible and portable. While it is quite complicated its fairly easy to get started with it and if you’re like me you’ll find yourself replacing the Kubernetes manifests in your code repos with Helm Charts.
There’s a lot more you can do with Helm, we’ve just scratched the surface. Enjoy using and learning more about them!