Part 2: Creating Your First Chart

Series Navigation: ← Part 1: Introduction and Installation | Back to Series Overview | Part 3: Advanced Templates and Values →

Introduction

In Part 1, we installed Helm and explored existing Charts. Now it's time to create our own. In this article, I'll walk you through building a Helm Chart for a TypeScript Node.js API—the kind of application I deploy regularly.

Creating your first Chart might seem daunting, but I've learned that starting with a simple structure and iterating is the best approach. We'll build a complete Chart for a REST API, including Deployment, Service, ConfigMap, and basic health checks.

The TypeScript Application

Let me show you the application we'll be deploying. This is a simple Express API I use as a template for microservices:

Project Structure

typescript-api/
├── src/
│   ├── server.ts
│   ├── routes/
│   │   └── health.ts
│   └── config/
│       └── index.ts
├── package.json
├── tsconfig.json
├── Dockerfile
└── helm-chart/          # We'll create this

The Application Code

src/server.ts:

import express, { Application } from 'express';
import { healthRouter } from './routes/health';
import config from './config';

const app: Application = express();

app.use(express.json());
app.use('/health', healthRouter);

app.get('/', (req, res) => {
  res.json({ 
    message: 'TypeScript API',
    version: config.version,
    environment: config.environment
  });
});

const PORT = config.port;

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
  console.log(`Environment: ${config.environment}`);
});

src/routes/health.ts:

import { Router, Request, Response } from 'express';

export const healthRouter = Router();

healthRouter.get('/live', (req: Request, res: Response) => {
  res.status(200).json({ status: 'alive' });
});

healthRouter.get('/ready', (req: Request, res: Response) => {
  // Check database connections, dependencies, etc.
  const isReady = true; // Simplified
  
  if (isReady) {
    res.status(200).json({ status: 'ready' });
  } else {
    res.status(503).json({ status: 'not ready' });
  }
});

src/config/index.ts:

export default {
  port: parseInt(process.env.PORT || '3000', 10),
  environment: process.env.NODE_ENV || 'development',
  version: process.env.APP_VERSION || '1.0.0',
  logLevel: process.env.LOG_LEVEL || 'info'
};

Dockerfile:

FROM node:18-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY tsconfig.json ./
COPY src ./src
RUN npm run build

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY --from=builder /app/dist ./dist

ENV NODE_ENV=production
ENV PORT=3000

EXPOSE 3000

USER node

CMD ["node", "dist/server.js"]

Creating the Chart

Now let's create a Helm Chart for this application.

Initialize Chart Structure

# Navigate to your project
cd typescript-api

# Create chart directory
helm create helm-chart

# Or create manually
mkdir -p helm-chart/templates

Helm's create command generates a complete Chart, but I prefer starting minimal and adding what I need. Let me show you my approach.

Chart.yaml - Chart Metadata

helm-chart/Chart.yaml:

apiVersion: v2
name: typescript-api
description: A TypeScript Express API application
type: application

# Chart version - increment when chart changes
version: 0.1.0

# Application version - the version of the app
appVersion: "1.0.0"

keywords:
  - typescript
  - nodejs
  - api
  - express

maintainers:
  - name: Your Name
    email: [email protected]

# Minimum Kubernetes version
kubeVersion: ">=1.24.0"

Key points from my experience:

• version: Chart version - increment when you change templates

• appVersion: Application version - update when you release new code

• type: Use application for deployable apps, library for shared templates

• kubeVersion: Helps prevent deployment to incompatible clusters

values.yaml - Default Configuration

helm-chart/values.yaml:

# Number of replicas
replicaCount: 2

# Container image configuration
image:
  repository: your-registry/typescript-api
  tag: ""  # Defaults to appVersion from Chart.yaml
  pullPolicy: IfNotPresent

# Image pull secrets for private registries
imagePullSecrets: []

# Override the name
nameOverride: ""
fullnameOverride: ""

# Service account
serviceAccount:
  create: true
  annotations: {}
  name: ""

# Pod annotations
podAnnotations: {}

# Pod security context
podSecurityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 1000

# Container security context
securityContext:
  allowPrivilegeEscalation: false
  capabilities:
    drop:
      - ALL
  readOnlyRootFilesystem: true

# Service configuration
service:
  type: ClusterIP
  port: 80
  targetPort: 3000
  annotations: {}

# Resource limits and requests
resources:
  limits:
    cpu: 200m
    memory: 256Mi
  requests:
    cpu: 100m
    memory: 128Mi

# Autoscaling
autoscaling:
  enabled: false
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80
  targetMemoryUtilizationPercentage: 80

# Health check configuration
livenessProbe:
  httpGet:
    path: /health/live
    port: http
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /health/ready
    port: http
  initialDelaySeconds: 10
  periodSeconds: 5
  timeoutSeconds: 3
  failureThreshold: 3

# Node selection
nodeSelector: {}

# Tolerations
tolerations: []

# Affinity rules
affinity: {}

# Environment variables
env:
  - name: NODE_ENV
    value: "production"
  - name: LOG_LEVEL
    value: "info"

# ConfigMap data
config:
  APP_NAME: "typescript-api"
  FEATURE_FLAG_A: "true"

# Ingress configuration
ingress:
  enabled: false
  className: "nginx"
  annotations: {}
    # cert-manager.io/cluster-issuer: "letsencrypt-prod"
  hosts:
    - host: api.example.com
      paths:
        - path: /
          pathType: Prefix
  tls: []
    # - secretName: api-tls
    #   hosts:
    #     - api.example.com

This values file includes everything I typically need. You can start simpler and add sections as needed.

Template Helpers

helm-chart/templates/_helpers.tpl:

{{/*
Expand the name of the chart.
*/}}
{{- define "typescript-api.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}

{{/*
Create a default fully qualified app name.
*/}}
{{- define "typescript-api.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- if contains $name .Release.Name }}
{{- .Release.Name | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}
{{- end }}

{{/*
Create chart name and version as used by the chart label.
*/}}
{{- define "typescript-api.chart" -}}
{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
{{- end }}

{{/*
Common labels
*/}}
{{- define "typescript-api.labels" -}}
helm.sh/chart: {{ include "typescript-api.chart" . }}
{{ include "typescript-api.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{/*
Selector labels
*/}}
{{- define "typescript-api.selectorLabels" -}}
app.kubernetes.io/name: {{ include "typescript-api.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

{{/*
Create the name of the service account
*/}}
{{- define "typescript-api.serviceAccountName" -}}
{{- if .Values.serviceAccount.create }}
{{- default (include "typescript-api.fullname" .) .Values.serviceAccount.name }}
{{- else }}
{{- default "default" .Values.serviceAccount.name }}
{{- end }}
{{- end }}

{{/*
Image tag
*/}}
{{- define "typescript-api.imageTag" -}}
{{- .Values.image.tag | default .Chart.AppVersion }}
{{- end }}

Helper templates reduce repetition and make charts maintainable. I use these patterns in every Chart I create.

Deployment Template

helm-chart/templates/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "typescript-api.fullname" . }}
  labels:
    {{- include "typescript-api.labels" . | nindent 4 }}
spec:
  {{- if not .Values.autoscaling.enabled }}
  replicas: {{ .Values.replicaCount }}
  {{- end }}
  selector:
    matchLabels:
      {{- include "typescript-api.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      annotations:
        checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
        {{- with .Values.podAnnotations }}
        {{- toYaml . | nindent 8 }}
        {{- end }}
      labels:
        {{- include "typescript-api.selectorLabels" . | nindent 8 }}
    spec:
      {{- with .Values.imagePullSecrets }}
      imagePullSecrets:
        {{- toYaml . | nindent 8 }}
      {{- end }}
      serviceAccountName: {{ include "typescript-api.serviceAccountName" . }}
      securityContext:
        {{- toYaml .Values.podSecurityContext | nindent 8 }}
      containers:
      - name: {{ .Chart.Name }}
        securityContext:
          {{- toYaml .Values.securityContext | nindent 12 }}
        image: "{{ .Values.image.repository }}:{{ include "typescript-api.imageTag" . }}"
        imagePullPolicy: {{ .Values.image.pullPolicy }}
        ports:
        - name: http
          containerPort: {{ .Values.service.targetPort }}
          protocol: TCP
        livenessProbe:
          {{- toYaml .Values.livenessProbe | nindent 12 }}
        readinessProbe:
          {{- toYaml .Values.readinessProbe | nindent 12 }}
        env:
        {{- range .Values.env }}
        - name: {{ .name }}
          value: {{ .value | quote }}
        {{- end }}
        - name: APP_VERSION
          value: {{ .Chart.AppVersion | quote }}
        - name: PORT
          value: {{ .Values.service.targetPort | quote }}
        envFrom:
        - configMapRef:
            name: {{ include "typescript-api.fullname" . }}-config
        resources:
          {{- toYaml .Values.resources | nindent 12 }}
        volumeMounts:
        - name: tmp
          mountPath: /tmp
      volumes:
      - name: tmp
        emptyDir: {}
      {{- with .Values.nodeSelector }}
      nodeSelector:
        {{- toYaml . | nindent 8 }}
      {{- end }}
      {{- with .Values.affinity }}
      affinity:
        {{- toYaml . | nindent 8 }}
      {{- end }}
      {{- with .Values.tolerations }}
      tolerations:
        {{- toYaml . | nindent 8 }}
      {{- end }}

Key features I always include:

• ConfigMap checksum annotation to trigger rolling updates on config changes

• Separate security contexts for pod and container

• Health probes using the /health endpoints

• Volume mount for /tmp since we use read-only root filesystem

• Environment variables from both values and ConfigMap

Service Template

helm-chart/templates/service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: {{ include "typescript-api.fullname" . }}
  labels:
    {{- include "typescript-api.labels" . | nindent 4 }}
  {{- with .Values.service.annotations }}
  annotations:
    {{- toYaml . | nindent 4 }}
  {{- end }}
spec:
  type: {{ .Values.service.type }}
  ports:
    - port: {{ .Values.service.port }}
      targetPort: http
      protocol: TCP
      name: http
  selector:
    {{- include "typescript-api.selectorLabels" . | nindent 4 }}

Simple and straightforward—exposes the Deployment on the specified port.

ConfigMap Template

helm-chart/templates/configmap.yaml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "typescript-api.fullname" . }}-config
  labels:
    {{- include "typescript-api.labels" . | nindent 4 }}
data:
  {{- range $key, $value := .Values.config }}
  {{ $key }}: {{ $value | quote }}
  {{- end }}

This ConfigMap allows injecting configuration without rebuilding the image.

ServiceAccount Template

helm-chart/templates/serviceaccount.yaml:

{{- if .Values.serviceAccount.create -}}
apiVersion: v1
kind: ServiceAccount
metadata:
  name: {{ include "typescript-api.serviceAccountName" . }}
  labels:
    {{- include "typescript-api.labels" . | nindent 4 }}
  {{- with .Values.serviceAccount.annotations }}
  annotations:
    {{- toYaml . | nindent 4 }}
  {{- end }}
{{- end }}

Ingress Template (Optional)

helm-chart/templates/ingress.yaml:

{{- if .Values.ingress.enabled -}}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ include "typescript-api.fullname" . }}
  labels:
    {{- include "typescript-api.labels" . | nindent 4 }}
  {{- with .Values.ingress.annotations }}
  annotations:
    {{- toYaml . | nindent 4 }}
  {{- end }}
spec:
  {{- if .Values.ingress.className }}
  ingressClassName: {{ .Values.ingress.className }}
  {{- end }}
  {{- if .Values.ingress.tls }}
  tls:
    {{- range .Values.ingress.tls }}
    - hosts:
        {{- range .hosts }}
        - {{ . | quote }}
        {{- end }}
      secretName: {{ .secretName }}
    {{- end }}
  {{- end }}
  rules:
    {{- range .Values.ingress.hosts }}
    - host: {{ .host | quote }}
      http:
        paths:
          {{- range .paths }}
          - path: {{ .path }}
            pathType: {{ .pathType }}
            backend:
              service:
                name: {{ include "typescript-api.fullname" $ }}
                port:
                  number: {{ $.Values.service.port }}
          {{- end }}
    {{- end }}
{{- end }}

HorizontalPodAutoscaler Template (Optional)

helm-chart/templates/hpa.yaml:

{{- if .Values.autoscaling.enabled }}
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: {{ include "typescript-api.fullname" . }}
  labels:
    {{- include "typescript-api.labels" . | nindent 4 }}
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: {{ include "typescript-api.fullname" . }}
  minReplicas: {{ .Values.autoscaling.minReplicas }}
  maxReplicas: {{ .Values.autoscaling.maxReplicas }}
  metrics:
    {{- if .Values.autoscaling.targetCPUUtilizationPercentage }}
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: {{ .Values.autoscaling.targetCPUUtilizationPercentage }}
    {{- end }}
    {{- if .Values.autoscaling.targetMemoryUtilizationPercentage }}
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: {{ .Values.autoscaling.targetMemoryUtilizationPercentage }}
    {{- end }}
{{- end }}

NOTES.txt - Post-Install Instructions

helm-chart/templates/NOTES.txt:

Thank you for installing {{ .Chart.Name }}!

Your release is named {{ .Release.Name }}.

To learn more about the release, try:

  $ helm status {{ .Release.Name }}
  $ helm get all {{ .Release.Name }}

To access the application:

{{- if .Values.ingress.enabled }}
  The application will be available at:
  {{- range .Values.ingress.hosts }}
  - http{{ if $.Values.ingress.tls }}s{{ end }}://{{ .host }}
  {{- end }}
{{- else if contains "NodePort" .Values.service.type }}
  export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "typescript-api.fullname" . }})
  export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}")
  echo "Visit http://$NODE_IP:$NODE_PORT"
{{- else if contains "LoadBalancer" .Values.service.type }}
  export SERVICE_IP=$(kubectl get svc --namespace {{ .Release.Namespace }} {{ include "typescript-api.fullname" . }} --template "{{"{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}"}}")
  echo "Visit http://$SERVICE_IP:{{ .Values.service.port }}"
{{- else if contains "ClusterIP" .Values.service.type }}
  export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "typescript-api.name" . }},app.kubernetes.io/instance={{ .Release.Name }}" -o jsonpath="{.items[0].metadata.name}")
  export CONTAINER_PORT=$(kubectl get pod --namespace {{ .Release.Namespace }} $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
  echo "Visit http://127.0.0.1:8080"
  kubectl --namespace {{ .Release.Namespace }} port-forward $POD_NAME 8080:$CONTAINER_PORT
{{- end }}

This displays helpful information after installation.

Testing the Chart

Now let's validate and test our Chart.

Lint the Chart

# Check for errors
helm lint helm-chart/

# Expected output
==> Linting helm-chart/
[INFO] Chart.yaml: icon is recommended
1 chart(s) linted, 0 chart(s) failed

Dry Run Installation

# See what would be installed without actually installing
helm install my-api helm-chart/ --dry-run --debug

# Or with custom values
helm install my-api helm-chart/ \
  --dry-run \
  --debug \
  --set image.repository=my-registry/typescript-api \
  --set image.tag=1.0.0

This shows the rendered Kubernetes manifests without applying them.

Template Rendering

# Render templates locally
helm template my-api helm-chart/

# Save rendered templates to file
helm template my-api helm-chart/ > rendered.yaml

# Render with specific values
helm template my-api helm-chart/ \
  --set replicaCount=3 \
  --set image.tag=2.0.0

Install the Chart

# Install to your Kubernetes cluster
helm install my-api helm-chart/

# Install with custom values
helm install my-api helm-chart/ \
  --set image.repository=your-registry/typescript-api \
  --set image.tag=1.0.0 \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=api.example.com

# Install with values file
helm install my-api helm-chart/ -f custom-values.yaml

# Install to specific namespace
helm install my-api helm-chart/ --namespace production --create-namespace

Verify Installation

# Check release status
helm status my-api

# List all releases
helm list

# Get deployed manifests
helm get manifest my-api

# Get values used
helm get values my-api

# Check Kubernetes resources
kubectl get all -l app.kubernetes.io/instance=my-api

# Check pods
kubectl get pods -l app.kubernetes.io/instance=my-api

# View logs
kubectl logs -l app.kubernetes.io/instance=my-api --tail=50

Environment-Specific Values

I maintain separate values files for each environment:

values-dev.yaml:

replicaCount: 1

image:
  repository: localhost:5000/typescript-api
  tag: dev
  pullPolicy: Always

resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 50m
    memory: 64Mi

env:
  - name: NODE_ENV
    value: "development"
  - name: LOG_LEVEL
    value: "debug"

config:
  FEATURE_FLAG_A: "true"
  DEBUG_MODE: "true"

values-prod.yaml:

replicaCount: 3

image:
  repository: registry.example.com/typescript-api
  tag: ""  # Will use appVersion

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 200m
    memory: 256Mi

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

env:
  - name: NODE_ENV
    value: "production"
  - name: LOG_LEVEL
    value: "warn"

config:
  FEATURE_FLAG_A: "false"

ingress:
  enabled: true
  className: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
  hosts:
    - host: api.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: api-tls
      hosts:
        - api.example.com

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
    - weight: 100
      podAffinityTerm:
        labelSelector:
          matchExpressions:
          - key: app.kubernetes.io/name
            operator: In
            values:
            - typescript-api
        topologyKey: kubernetes.io/hostname

Deploy with environment-specific values:

# Development
helm install my-api helm-chart/ -f helm-chart/values-dev.yaml

# Production
helm install my-api helm-chart/ -f helm-chart/values-prod.yaml --namespace production

Upgrading and Rolling Back

Upgrade a Release

# Upgrade with new image tag
helm upgrade my-api helm-chart/ --set image.tag=1.1.0

# Upgrade with values file
helm upgrade my-api helm-chart/ -f values-prod.yaml

# Upgrade and wait for completion
helm upgrade my-api helm-chart/ --wait --timeout 5m

# See what would change
helm upgrade my-api helm-chart/ --dry-run --debug

Rollback a Release

# View release history
helm history my-api

# Rollback to previous version
helm rollback my-api

# Rollback to specific revision
helm rollback my-api 2

# Rollback with wait
helm rollback my-api --wait

Debugging Chart Issues

Common issues I've encountered and how to debug them:

Templates Not Rendering

# Check template syntax
helm template my-api helm-chart/ --debug

# Validate against Kubernetes
helm template my-api helm-chart/ | kubectl apply --dry-run=client -f -

Failed Installation

# Get detailed status
helm status my-api

# View events
kubectl get events --sort-by='.lastTimestamp'

# Check pod logs
kubectl logs -l app.kubernetes.io/instance=my-api

# Describe pods
kubectl describe pods -l app.kubernetes.io/instance=my-api

Value Not Applied

# Check what values were used
helm get values my-api

# Check rendered manifest
helm get manifest my-api | grep -A 5 -B 5 "your-value"

Best Practices from Experience

Here are patterns I follow for every Chart:

1. Always use helper templates for names and labels—ensures consistency

2. Include health probes—critical for zero-downtime deployments

3. Set resource limits—prevents resource exhaustion

4. Use security contexts—follow security best practices

5. ConfigMap checksums—trigger pod restarts on config changes

6. Separate environment values—maintain clarity between dev/staging/prod

7. Document with NOTES.txt—help users access the application

8. Test with helm lint and helm template—catch errors early

9. Version your charts—increment Chart version with each change

10. Use .helmignore—exclude unnecessary files from packaged charts

What's Next?

We've created a complete, production-ready Helm Chart for a TypeScript application. In Part 3, we'll dive deeper into advanced templating:

• Template functions and pipelines

• Complex conditional logic

• Named templates and includes

• Range loops and data structures

• Advanced value manipulation

• Creating reusable chart libraries

---

Series Navigation: ← Part 1: Introduction and Installation | Back to Series Overview | Part 3: Advanced Templates and Values →

Key Takeaways

• ✅ Charts follow a standard structure with templates, values, and helpers

• ✅ Helper templates reduce repetition and ensure consistency

• ✅ ConfigMap checksums trigger rolling updates on config changes

• ✅ Always include health probes and security contexts

• ✅ Environment-specific values files enable multi-environment deployments

• ✅ Testing with lint, template, and dry-run catches errors before deployment

• ✅ Helm makes upgrades and rollbacks simple and reliable