4.2. Custom Chart

In this lab, you package the message board from 3.1 as a chart of its own, connect it to the database from 4.1 and install it with Helm.

Step 1: Create the Chart

Create the directories of the chart and change into the directory of this lab:

mkdir -p ~/labs/4.2/messages/templates
cd ~/labs/4.2

Create the file Chart.yaml in ~/labs/4.2/messages with the description of the chart:

apiVersion: v2
name: messages
description: The message board from chapter 3
version: 0.1.0
appVersion: "1.0"

Copy the manifests of the backend and the frontend from 3.1 into the directory templates:

cp ~/labs/3.1/backend.yaml ~/labs/3.1/frontend.yaml messages/templates/

Explanation

A chart is a directory. Chart.yaml names and describes it: apiVersion: v2 is the version of the chart format, not a Kubernetes API version. version is the version of the chart, appVersion the version of the application it installs. Every manifest in templates becomes part of a release.

The manifest of PostgreSQL stays out of the chart: the message board uses the database you installed in 4.1.


Step 2: Make the Chart Configurable

Create the file values.yaml in ~/labs/4.2/messages with the defaults of the settings that may differ between installations:

backend:
  image: messages-backend:1.0
  replicas: 2
frontend:
  image: messages-frontend:1.0
  nodePort: 30088
postgres:
  host: postgresql
  user: messages
  password: ""
  database: messages

Create the file values.dev.yaml in ~/labs/4.2 with the settings of your dev environment (the connection to the database from 4.1):

postgres:
  host: postgresql.postgresql-dev
  password: s3cr3t

Create the file secret.yaml in ~/labs/4.2/messages/templates with the user, password and database for the backend:

apiVersion: v1
kind: Secret
metadata:
  name: postgres
stringData:
  POSTGRES_USER: {{ .Values.postgres.user }}
  POSTGRES_PASSWORD: {{ .Values.postgres.password }}
  POSTGRES_DB: {{ .Values.postgres.database }}

Replace the fixed values in the other templates with placeholders. In backend.yaml, the number of replicas, the image and the address of the database:

  replicas: {{ .Values.backend.replicas }}
          image: {{ .Values.backend.image }}
              value: {{ .Values.postgres.host }}

In frontend.yaml, the image and the NodePort:

          image: {{ .Values.frontend.image }}
      nodePort: {{ .Values.frontend.nodePort }}

Explanation

Helm replaces every {{ ... }} when it renders the chart. .Values.backend.replicas is the path to a setting in values.yaml: the key replicas below backend. This file belongs to the chart and holds the defaults. values.dev.yaml lies outside the chart and overrides them for one environment, as your values did with the Bitnami chart in 4.1. This way, the password of your environment never ends up in the chart.

postgresql.postgresql-dev is the Service postgresql in the namespace postgresql-dev: a Pod reaches a Service in another namespace by adding the namespace to its name. The backend still reads the Secret postgres, which now holds the user messages that the Bitnami chart created.

The names of the resources stay fixed, because the frontend image contains the address http://backend:8000. That’s why this chart can only be installed once per namespace.


Step 3: Check and Render the Chart

Check the chart for errors:

helm lint ./messages
==> Linting ./messages
[INFO] Chart.yaml: icon is recommended

1 chart(s) linted, 0 chart(s) failed

Render one template with the defaults and your dev values, without installing anything:

helm template messages ./messages -f values.dev.yaml --show-only templates/backend.yaml
---
# Source: messages/templates/backend.yaml
apiVersion: v1
kind: Service
metadata:
  name: backend
spec:
  selector:
    app: backend
  ports:
    - port: 8000
      targetPort: 8000


---
# Source: messages/templates/backend.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
spec:
  replicas: 2
  selector:
    matchLabels:
      app: backend
  template:
    metadata:
      labels:
        app: backend
    spec:
      containers:
        - name: backend
          image: messages-backend:1.0
          env:
            - name: POSTGRES_HOST
              value: postgresql.postgresql-dev
          envFrom:
            - secretRef:
                name: postgres
          readinessProbe:
            httpGet:
              path: /health
              port: 8000
            periodSeconds: 5

Render it once more and override a value on the command line:

helm template messages ./messages --show-only templates/backend.yaml --set backend.replicas=3 | grep replicas
  replicas: 3

Explanation

helm lint checks the structure and the templates of the chart. The [INFO] about an icon is only a hint for published charts. helm template shows exactly the manifests that Helm would apply, with the placeholders replaced by the values. As with helm install in 4.1, the first argument is the name of the release and the second is the chart: ./messages, the path to your chart directory. Helm sorts the manifests by kind, so the Service comes before the Deployment. -f puts the values of a file on top of the defaults, --set a single value. Both apply only to this one command.


Step 4: Install the Message Board

Install the chart as the release messages into the new namespace messages-dev:

helm install messages ./messages -n messages-dev --create-namespace -f values.dev.yaml
NAME: messages
LAST DEPLOYED: Tue Oct 13 16:44:51 2026
NAMESPACE: messages-dev
STATUS: deployed
REVISION: 1
DESCRIPTION: Install complete
TEST SUITE: None

Wait about 10 seconds and list the Pods:

kubectl get pods -n messages-dev
NAME                        READY   STATUS    RESTARTS   AGE
backend-59d46555fc-nf4jk    1/1     Running   0          8s
backend-59d46555fc-p4m88    1/1     Running   0          8s
frontend-6564d96887-b8md8   1/1     Running   0          8s

If not all Pods are 1/1 yet, wait a moment and repeat the command. If the backend Pods stay 0/1 or restart, they can’t reach the database: check with kubectl get pods -n postgresql-dev that postgresql-0 from 4.1 is 1/1.

Open http://localhost:30088 in your browser and post the message Hello Helm. Then look for it in the database from 4.1: psql, the client of PostgreSQL, runs in the database Pod. -U and -d select the user and the database, env PGPASSWORD=s3cr3t passes the password as an environment variable, and -c runs one SQL query:

kubectl exec postgresql-0 -n postgresql-dev -- env PGPASSWORD=s3cr3t psql -U messages -d messages -c "select * from messages"
 id |          created_at           |    text
----+-------------------------------+------------
  1 | 2026-10-13 16:45:00.858198+00 | Hello Helm
(1 row)

Explanation

One command installed the backend and the frontend into the namespace messages-dev. The message you posted ended up in the database in postgresql-dev: the application and its database are separate releases in separate namespaces, so you can update, roll back or scale each of them on its own.


Step 5: Upgrade the Release

Raise the number of backend replicas of your dev environment to 3. Add the setting to values.dev.yaml:

backend:
  replicas: 3
postgres:
  host: postgresql.postgresql-dev
  password: s3cr3t

Upgrade the release:

helm upgrade messages ./messages -n messages-dev -f values.dev.yaml
Release "messages" has been upgraded. Happy Helming!
NAME: messages
...
REVISION: 2
...

List the Pods and the history of the release:

kubectl get pods -n messages-dev
NAME                        READY   STATUS    RESTARTS   AGE
backend-59d46555fc-k8jtz    1/1     Running   0          6s
backend-59d46555fc-nf4jk    1/1     Running   0          16s
backend-59d46555fc-p4m88    1/1     Running   0          16s
frontend-6564d96887-b8md8   1/1     Running   0          16s

If the new backend Pod isn’t 1/1 yet, wait a moment and repeat the command.

helm history messages -n messages-dev
REVISION   UPDATED                    STATUS       CHART            APP VERSION   DESCRIPTION
1          Tue Oct 13 16:44:51 2026   superseded   messages-0.1.0   1.0           Install complete
2          Tue Oct 13 16:45:01 2026   deployed     messages-0.1.0   1.0           Upgrade complete

Keep both releases running. The next chapter makes the message board reachable through an Ingress.

Explanation

Helm compared the new manifests with the running release and changed only what was different: the replicas of the Deployment backend. It started one more Pod in the same ReplicaSet: the hash 59d46555fc in the Pod names didn’t change. The frontend kept running. From now on, values.dev.yaml describes your dev installation, as the manifests did in 3.1. Pass it with -f to every helm upgrade, so that your settings come from the file.


Optional Tasks

Finished early? Try these tasks. The following labs don’t depend on them. Each task lists the commands you need. Open the solution if you get stuck.

Task 1: Break It

Remove one of the closing braces from the placeholder {{ .Values.backend.replicas }} in backend.yaml. What does helm lint report? Restore the brace afterwards.

You know all the commands you need.

Solution

With {{ .Values.backend.replicas } in the template, check the chart:

helm lint ./messages
==> Linting ./messages
[INFO] Chart.yaml: icon is recommended
[ERROR] templates/: parse error at (messages/templates/backend.yaml:6): unexpected "}" in operand

Error: 1 chart(s) linted, 1 chart(s) failed

The message names the file and the line of the error. Restore the brace and run helm lint again. It reports 0 chart(s) failed.

Task 2: Two Environments

Create a second values file values.prod.yaml in ~/labs/4.2 for a production environment with 4 backend replicas. Render the backend with it. Which image does it use?

You know all the commands you need.

Solution

Create values.prod.yaml:

backend:
  replicas: 4

Render the backend with it:

helm template messages ./messages -f values.prod.yaml --show-only templates/backend.yaml | grep -E "replicas|image"
  replicas: 4
          image: messages-backend:1.0

Helm merges the files: values.prod.yaml overrides only the replicas, the image still comes from the values.yaml of the chart. You have one chart and one small file per environment: values.dev.yaml and values.prod.yaml. A real production installation would also need its own database and, in this cluster, another frontend.nodePort: a NodePort can be used only once per cluster.

Task 3: Ship It

Package the chart into a single file, the way charts are published in a repository, and list its content.

CommandEffect
helm package <chart>Packs the chart directory into a .tgz file
tar tzf <file>Lists the files in a .tgz file
Solution

Package the chart:

helm package ./messages
Successfully packaged chart and saved it to: /home/ubuntu/labs/4.2/messages-0.1.0.tgz

On your machine, the path starts with your own home directory. List the content of the package:

tar tzf messages-0.1.0.tgz
messages/Chart.yaml
messages/values.yaml
messages/templates/backend.yaml
messages/templates/frontend.yaml
messages/templates/secret.yaml

The file name contains the version from Chart.yaml. Repositories distribute exactly such files, and helm install accepts one in place of the chart directory.


Complete files

~/labs/4.2/messages/Chart.yaml:

apiVersion: v2
name: messages
description: The message board from chapter 3
version: 0.1.0
appVersion: "1.0"

~/labs/4.2/messages/values.yaml:

backend:
  image: messages-backend:1.0
  replicas: 2
frontend:
  image: messages-frontend:1.0
  nodePort: 30088
postgres:
  host: postgresql
  user: messages
  password: ""
  database: messages

~/labs/4.2/values.dev.yaml:

backend:
  replicas: 3
postgres:
  host: postgresql.postgresql-dev
  password: s3cr3t

~/labs/4.2/messages/templates/secret.yaml:

apiVersion: v1
kind: Secret
metadata:
  name: postgres
stringData:
  POSTGRES_USER: {{ .Values.postgres.user }}
  POSTGRES_PASSWORD: {{ .Values.postgres.password }}
  POSTGRES_DB: {{ .Values.postgres.database }}

~/labs/4.2/messages/templates/backend.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
spec:
  replicas: {{ .Values.backend.replicas }}
  selector:
    matchLabels:
      app: backend
  template:
    metadata:
      labels:
        app: backend
    spec:
      containers:
        - name: backend
          image: {{ .Values.backend.image }}
          env:
            - name: POSTGRES_HOST
              value: {{ .Values.postgres.host }}
          envFrom:
            - secretRef:
                name: postgres
          readinessProbe:
            httpGet:
              path: /health
              port: 8000
            periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: backend
spec:
  selector:
    app: backend
  ports:
    - port: 8000
      targetPort: 8000

~/labs/4.2/messages/templates/frontend.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
spec:
  replicas: 1
  selector:
    matchLabels:
      app: frontend
  template:
    metadata:
      labels:
        app: frontend
    spec:
      containers:
        - name: frontend
          image: {{ .Values.frontend.image }}
---
apiVersion: v1
kind: Service
metadata:
  name: frontend
spec:
  type: NodePort
  selector:
    app: frontend
  ports:
    - port: 80
      targetPort: 80
      nodePort: {{ .Values.frontend.nodePort }}