1# Helm Charts
2 
3## Chart Structure
4 
5```
6mychart/
7├── Chart.yaml              # Chart metadata
8├── values.yaml             # Default values
9├── values.schema.json      # Values validation schema
10├── charts/                 # Dependency charts
11├── templates/              # Template files
12│   ├── NOTES.txt          # Post-install notes
13│   ├── _helpers.tpl       # Template helpers
14│   ├── deployment.yaml
15│   ├── service.yaml
16│   ├── ingress.yaml
17│   ├── configmap.yaml
18│   ├── secret.yaml
19│   ├── serviceaccount.yaml
20│   ├── hpa.yaml
21│   └── tests/
22│       └── test-connection.yaml
23├── .helmignore            # Ignore patterns
24└── README.md              # Chart documentation
25```
26 
27## Chart.yaml
28 
29```yaml
30apiVersion: v2
31name: myapp
32description: A Helm chart for MyApp on Kubernetes
33type: application
34version: 1.2.0
35appVersion: "2.5.0"
36 
37keywords:
38  - web
39  - application
40  - microservice
41 
42home: https://example.com
43sources:
44  - https://github.com/example/myapp
45 
46maintainers:
47  - name: DevOps Team
48    email: [email protected]
49    url: https://example.com/team
50 
51icon: https://example.com/logo.png
52 
53dependencies:
54  - name: postgresql
55    version: "12.x.x"
56    repository: https://charts.bitnami.com/bitnami
57    condition: postgresql.enabled
58    tags:
59      - database
60 
61  - name: redis
62    version: "17.x.x"
63    repository: https://charts.bitnami.com/bitnami
64    condition: redis.enabled
65    tags:
66      - cache
67 
68annotations:
69  category: Application
70```
71 
72## values.yaml
73 
74```yaml
75# Default values for myapp
76replicaCount: 3
77 
78image:
79  repository: myregistry.io/myapp
80  pullPolicy: IfNotPresent
81  tag: ""  # Overrides the image tag (default is .Chart.AppVersion)
82 
83imagePullSecrets:
84  - name: registry-credentials
85 
86nameOverride: ""
87fullnameOverride: ""
88 
89serviceAccount:
90  create: true
91  annotations: {}
92  name: ""
93 
94podAnnotations:
95  prometheus.io/scrape: "true"
96  prometheus.io/port: "8080"
97 
98podSecurityContext:
99  runAsNonRoot: true
100  runAsUser: 1000
101  fsGroup: 2000
102  seccompProfile:
103    type: RuntimeDefault
104 
105securityContext:
106  allowPrivilegeEscalation: false
107  capabilities:
108    drop:
109    - ALL
110  readOnlyRootFilesystem: true
111 
112service:
113  type: ClusterIP
114  port: 80
115  targetPort: 8080
116  annotations: {}
117 
118ingress:
119  enabled: true
120  className: "nginx"
121  annotations:
122    cert-manager.io/cluster-issuer: "letsencrypt-prod"
123    nginx.ingress.kubernetes.io/ssl-redirect: "true"
124  hosts:
125    - host: myapp.example.com
126      paths:
127        - path: /
128          pathType: Prefix
129  tls:
130    - secretName: myapp-tls
131      hosts:
132        - myapp.example.com
133 
134resources:
135  limits:
136    cpu: 500m
137    memory: 512Mi
138  requests:
139    cpu: 100m
140    memory: 128Mi
141 
142autoscaling:
143  enabled: true
144  minReplicas: 3
145  maxReplicas: 10
146  targetCPUUtilizationPercentage: 80
147  targetMemoryUtilizationPercentage: 80
148 
149nodeSelector: {}
150 
151tolerations: []
152 
153affinity:
154  podAntiAffinity:
155    preferredDuringSchedulingIgnoredDuringExecution:
156      - weight: 100
157        podAffinityTerm:
158          labelSelector:
159            matchExpressions:
160              - key: app.kubernetes.io/name
161                operator: In
162                values:
163                  - myapp
164          topologyKey: kubernetes.io/hostname
165 
166livenessProbe:
167  httpGet:
168    path: /health
169    port: http
170  initialDelaySeconds: 30
171  periodSeconds: 10
172  timeoutSeconds: 5
173  failureThreshold: 3
174 
175readinessProbe:
176  httpGet:
177    path: /ready
178    port: http
179  initialDelaySeconds: 10
180  periodSeconds: 5
181  timeoutSeconds: 3
182  failureThreshold: 2
183 
184env:
185  - name: ENVIRONMENT
186    value: production
187  - name: LOG_LEVEL
188    value: info
189 
190envFrom: []
191 
192volumeMounts: []
193volumes: []
194 
195# PostgreSQL dependency
196postgresql:
197  enabled: true
198  auth:
199    username: myapp
200    password: ""  # Set via --set or separate secret
201    database: myapp
202  primary:
203    persistence:
204      enabled: true
205      size: 10Gi
206 
207# Redis dependency
208redis:
209  enabled: true
210  architecture: standalone
211  auth:
212    enabled: true
213    password: ""
214  master:
215    persistence:
216      enabled: true
217      size: 5Gi
218```
219 
220## templates/_helpers.tpl
221 
222```yaml
223{{/*
224Expand the name of the chart.
225*/}}
226{{- define "myapp.name" -}}
227{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
228{{- end }}
229 
230{{/*
231Create a default fully qualified app name.
232*/}}
233{{- define "myapp.fullname" -}}
234{{- if .Values.fullnameOverride }}
235{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
236{{- else }}
237{{- $name := default .Chart.Name .Values.nameOverride }}
238{{- if contains $name .Release.Name }}
239{{- .Release.Name | trunc 63 | trimSuffix "-" }}
240{{- else }}
241{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
242{{- end }}
243{{- end }}
244{{- end }}
245 
246{{/*
247Create chart name and version as used by the chart label.
248*/}}
249{{- define "myapp.chart" -}}
250{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
251{{- end }}
252 
253{{/*
254Common labels
255*/}}
256{{- define "myapp.labels" -}}
257helm.sh/chart: {{ include "myapp.chart" . }}
258{{ include "myapp.selectorLabels" . }}
259{{- if .Chart.AppVersion }}
260app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
261{{- end }}
262app.kubernetes.io/managed-by: {{ .Release.Service }}
263{{- end }}
264 
265{{/*
266Selector labels
267*/}}
268{{- define "myapp.selectorLabels" -}}
269app.kubernetes.io/name: {{ include "myapp.name" . }}
270app.kubernetes.io/instance: {{ .Release.Name }}
271{{- end }}
272 
273{{/*
274Create the name of the service account to use
275*/}}
276{{- define "myapp.serviceAccountName" -}}
277{{- if .Values.serviceAccount.create }}
278{{- default (include "myapp.fullname" .) .Values.serviceAccount.name }}
279{{- else }}
280{{- default "default" .Values.serviceAccount.name }}
281{{- end }}
282{{- end }}
283```
284 
285## templates/deployment.yaml
286 
287```yaml
288apiVersion: apps/v1
289kind: Deployment
290metadata:
291  name: {{ include "myapp.fullname" . }}
292  labels:
293    {{- include "myapp.labels" . | nindent 4 }}
294spec:
295  {{- if not .Values.autoscaling.enabled }}
296  replicas: {{ .Values.replicaCount }}
297  {{- end }}
298  selector:
299    matchLabels:
300      {{- include "myapp.selectorLabels" . | nindent 6 }}
301  template:
302    metadata:
303      annotations:
304        checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
305        {{- with .Values.podAnnotations }}
306        {{- toYaml . | nindent 8 }}
307        {{- end }}
308      labels:
309        {{- include "myapp.selectorLabels" . | nindent 8 }}
310    spec:
311      {{- with .Values.imagePullSecrets }}
312      imagePullSecrets:
313        {{- toYaml . | nindent 8 }}
314      {{- end }}
315      serviceAccountName: {{ include "myapp.serviceAccountName" . }}
316      securityContext:
317        {{- toYaml .Values.podSecurityContext | nindent 8 }}
318      containers:
319      - name: {{ .Chart.Name }}
320        securityContext:
321          {{- toYaml .Values.securityContext | nindent 12 }}
322        image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
323        imagePullPolicy: {{ .Values.image.pullPolicy }}
324        ports:
325        - name: http
326          containerPort: {{ .Values.service.targetPort }}
327          protocol: TCP
328        {{- with .Values.env }}
329        env:
330          {{- toYaml . | nindent 12 }}
331        {{- end }}
332        {{- with .Values.envFrom }}
333        envFrom:
334          {{- toYaml . | nindent 12 }}
335        {{- end }}
336        livenessProbe:
337          {{- toYaml .Values.livenessProbe | nindent 12 }}
338        readinessProbe:
339          {{- toYaml .Values.readinessProbe | nindent 12 }}
340        resources:
341          {{- toYaml .Values.resources | nindent 12 }}
342        {{- with .Values.volumeMounts }}
343        volumeMounts:
344          {{- toYaml . | nindent 12 }}
345        {{- end }}
346      {{- with .Values.volumes }}
347      volumes:
348        {{- toYaml . | nindent 8 }}
349      {{- end }}
350      {{- with .Values.nodeSelector }}
351      nodeSelector:
352        {{- toYaml . | nindent 8 }}
353      {{- end }}
354      {{- with .Values.affinity }}
355      affinity:
356        {{- toYaml . | nindent 8 }}
357      {{- end }}
358      {{- with .Values.tolerations }}
359      tolerations:
360        {{- toYaml . | nindent 8 }}
361      {{- end }}
362```
363 
364## templates/hpa.yaml
365 
366```yaml
367{{- if .Values.autoscaling.enabled }}
368apiVersion: autoscaling/v2
369kind: HorizontalPodAutoscaler
370metadata:
371  name: {{ include "myapp.fullname" . }}
372  labels:
373    {{- include "myapp.labels" . | nindent 4 }}
374spec:
375  scaleTargetRef:
376    apiVersion: apps/v1
377    kind: Deployment
378    name: {{ include "myapp.fullname" . }}
379  minReplicas: {{ .Values.autoscaling.minReplicas }}
380  maxReplicas: {{ .Values.autoscaling.maxReplicas }}
381  metrics:
382  {{- if .Values.autoscaling.targetCPUUtilizationPercentage }}
383  - type: Resource
384    resource:
385      name: cpu
386      target:
387        type: Utilization
388        averageUtilization: {{ .Values.autoscaling.targetCPUUtilizationPercentage }}
389  {{- end }}
390  {{- if .Values.autoscaling.targetMemoryUtilizationPercentage }}
391  - type: Resource
392    resource:
393      name: memory
394      target:
395        type: Utilization
396        averageUtilization: {{ .Values.autoscaling.targetMemoryUtilizationPercentage }}
397  {{- end }}
398{{- end }}
399```
400 
401## Helm Hooks
402 
403### Pre-Install Hook (Database Migration)
404 
405```yaml
406apiVersion: batch/v1
407kind: Job
408metadata:
409  name: {{ include "myapp.fullname" . }}-migration
410  labels:
411    {{- include "myapp.labels" . | nindent 4 }}
412  annotations:
413    "helm.sh/hook": pre-install,pre-upgrade
414    "helm.sh/hook-weight": "0"
415    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
416spec:
417  backoffLimit: 3
418  template:
419    metadata:
420      labels:
421        app: migration
422    spec:
423      restartPolicy: Never
424      containers:
425      - name: migrate
426        image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
427        command: ["/app/migrate", "up"]
428        env:
429        - name: DATABASE_URL
430          valueFrom:
431            secretKeyRef:
432              name: {{ include "myapp.fullname" . }}-secrets
433              key: database-url
434```
435 
436### Post-Install Hook (Test)
437 
438```yaml
439apiVersion: v1
440kind: Pod
441metadata:
442  name: {{ include "myapp.fullname" . }}-test
443  labels:
444    {{- include "myapp.labels" . | nindent 4 }}
445  annotations:
446    "helm.sh/hook": test
447    "helm.sh/hook-weight": "0"
448    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
449spec:
450  restartPolicy: Never
451  containers:
452  - name: test
453    image: curlimages/curl:latest
454    command: ['sh', '-c']
455    args:
456    - |
457      curl -f http://{{ include "myapp.fullname" . }}:{{ .Values.service.port }}/health || exit 1
458```
459 
460## Helm Commands
461 
462```bash
463# Create new chart
464helm create myapp
465 
466# Lint chart
467helm lint myapp/
468 
469# Template rendering (dry-run)
470helm template myapp ./myapp -f values-prod.yaml
471 
472# Install chart
473helm install myapp ./myapp \
474  --namespace production \
475  --create-namespace \
476  --values values-prod.yaml \
477  --set image.tag=v1.2.0
478 
479# Upgrade chart
480helm upgrade myapp ./myapp \
481  --namespace production \
482  --values values-prod.yaml \
483  --set image.tag=v1.3.0 \
484  --atomic \
485  --timeout 5m
486 
487# Rollback
488helm rollback myapp 1 --namespace production
489 
490# List releases
491helm list --namespace production
492 
493# Get values
494helm get values myapp --namespace production
495 
496# Get manifest
497helm get manifest myapp --namespace production
498 
499# Uninstall
500helm uninstall myapp --namespace production
501 
502# Test
503helm test myapp --namespace production
504 
505# Package chart
506helm package myapp/ --version 1.2.0
507 
508# Dependency update
509helm dependency update myapp/
510```
511 
512## values-prod.yaml (Environment Override)
513 
514```yaml
515replicaCount: 5
516 
517image:
518  tag: v1.2.0
519 
520resources:
521  limits:
522    cpu: 1000m
523    memory: 1Gi
524  requests:
525    cpu: 250m
526    memory: 256Mi
527 
528autoscaling:
529  enabled: true
530  minReplicas: 5
531  maxReplicas: 20
532 
533ingress:
534  hosts:
535    - host: app.production.example.com
536      paths:
537        - path: /
538          pathType: Prefix
539 
540postgresql:
541  enabled: true
542  primary:
543    persistence:
544      size: 100Gi
545    resources:
546      limits:
547        cpu: 2000m
548        memory: 4Gi
549      requests:
550        cpu: 500m
551        memory: 1Gi
552 
553redis:
554  enabled: true
555  master:
556    persistence:
557      size: 20Gi
558```
559 
560## Chart Testing
561 
562### Helm Test Command
563 
564```bash
565# Run chart tests after installation
566helm test myapp --namespace production
567 
568# Run tests with logs
569helm test myapp --namespace production --logs
570 
571# Run tests with timeout
572helm test myapp --namespace production --timeout 5m
573```
574 
575### Chart Testing Tool (ct)
576 
577```bash
578# Install chart-testing
579brew install chart-testing
580 
581# Lint charts
582ct lint --config ct.yaml
583 
584# Lint and install (CI/CD)
585ct lint-and-install --config ct.yaml
586 
587# Test changed charts only
588ct lint-and-install --target-branch main --config ct.yaml
589```
590 
591```yaml
592# ct.yaml - Chart Testing configuration
593remote: origin
594target-branch: main
595chart-dirs:
596  - charts
597chart-repos:
598  - bitnami=https://charts.bitnami.com/bitnami
599helm-extra-args: --timeout 600s
600validate-maintainers: true
601check-version-increment: true
602```
603 
604### Unit Testing with helm-unittest
605 
606```bash
607# Install plugin
608helm plugin install https://github.com/helm-unittest/helm-unittest
609 
610# Run tests
611helm unittest ./mychart
612```
613 
614```yaml
615# tests/deployment_test.yaml
616suite: deployment tests
617templates:
618  - templates/deployment.yaml
619tests:
620  - it: should create deployment with correct replicas
621    set:
622      replicaCount: 5
623    asserts:
624      - isKind:
625          of: Deployment
626      - equal:
627          path: spec.replicas
628          value: 5
629 
630  - it: should set resource limits
631    set:
632      resources:
633        limits:
634          cpu: 500m
635          memory: 256Mi
636    asserts:
637      - equal:
638          path: spec.template.spec.containers[0].resources.limits.cpu
639          value: 500m
640 
641  - it: should not create HPA when autoscaling disabled
642    set:
643      autoscaling:
644        enabled: false
645    template: templates/hpa.yaml
646    asserts:
647      - hasDocuments:
648          count: 0
649```
650 
651## Values Schema Validation
652 
653```json
654{
655  "$schema": "https://json-schema.org/draft-07/schema#",
656  "type": "object",
657  "required": ["image", "service"],
658  "properties": {
659    "replicaCount": {
660      "type": "integer",
661      "minimum": 1,
662      "maximum": 100,
663      "default": 1
664    },
665    "image": {
666      "type": "object",
667      "required": ["repository"],
668      "properties": {
669        "repository": {
670          "type": "string",
671          "pattern": "^[a-z0-9.-/]+$"
672        },
673        "tag": {
674          "type": "string"
675        },
676        "pullPolicy": {
677          "type": "string",
678          "enum": ["Always", "IfNotPresent", "Never"]
679        }
680      }
681    },
682    "service": {
683      "type": "object",
684      "properties": {
685        "type": {
686          "type": "string",
687          "enum": ["ClusterIP", "NodePort", "LoadBalancer"]
688        },
689        "port": {
690          "type": "integer",
691          "minimum": 1,
692          "maximum": 65535
693        }
694      }
695    },
696    "resources": {
697      "type": "object",
698      "properties": {
699        "limits": {
700          "$ref": "#/definitions/resourceRequirements"
701        },
702        "requests": {
703          "$ref": "#/definitions/resourceRequirements"
704        }
705      }
706    }
707  },
708  "definitions": {
709    "resourceRequirements": {
710      "type": "object",
711      "properties": {
712        "cpu": {
713          "type": "string",
714          "pattern": "^[0-9]+m?$"
715        },
716        "memory": {
717          "type": "string",
718          "pattern": "^[0-9]+(Mi|Gi)$"
719        }
720      }
721    }
722  }
723}
724```
725 
726## Chart Repository
727 
728### Create Repository
729 
730```bash
731# Package chart
732helm package mychart/ --version 1.2.0 --destination ./repo
733 
734# Generate index
735helm repo index ./repo --url https://charts.example.com
736 
737# Update index with new chart
738helm repo index ./repo --url https://charts.example.com --merge ./repo/index.yaml
739```
740 
741### GitHub Pages Repository
742 
743```yaml
744# .github/workflows/release.yaml
745name: Release Charts
746on:
747  push:
748    branches: [main]
749    paths: ['charts/**']
750jobs:
751  release:
752    runs-on: ubuntu-latest
753    steps:
754      - uses: actions/checkout@v4
755        with:
756          fetch-depth: 0
757      - name: Configure Git
758        run: |
759          git config user.name "$GITHUB_ACTOR"
760          git config user.email "[email protected]"
761      - name: Install Helm
762        uses: azure/setup-helm@v3
763      - name: Run chart-releaser
764        uses: helm/[email protected]
765        env:
766          CR_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
767```
768 
769### OCI Registry
770 
771```bash
772# Login to registry
773helm registry login myregistry.io -u user -p token
774 
775# Push chart to OCI registry
776helm push mychart-1.2.0.tgz oci://myregistry.io/charts
777 
778# Pull from OCI
779helm pull oci://myregistry.io/charts/mychart --version 1.2.0
780 
781# Install from OCI
782helm install myapp oci://myregistry.io/charts/mychart --version 1.2.0
783```
784 
785## Helm Plugins
786 
787```bash
788# helm-diff - preview upgrades
789helm plugin install https://github.com/databus23/helm-diff
790helm diff upgrade myapp ./mychart -f values-prod.yaml
791 
792# helm-secrets - manage encrypted secrets
793helm plugin install https://github.com/jkroepke/helm-secrets
794helm secrets encrypt secrets.yaml
795helm secrets decrypt secrets.yaml.enc
796helm secrets install myapp ./mychart -f secrets.yaml.enc
797 
798# helm-git - use git repos as chart sources
799helm plugin install https://github.com/aslafy-z/helm-git
800helm repo add mycharts git+https://github.com/myorg/charts@charts?ref=main
801 
802# helm-s3 - S3 as chart repository
803helm plugin install https://github.com/hypnoglow/helm-s3
804helm s3 init s3://my-bucket/charts
805helm s3 push mychart-1.2.0.tgz my-s3-repo
806```
807 
808## Complex Upgrade/Rollback
809 
810```bash
811# Upgrade with atomic (rollback on failure)
812helm upgrade myapp ./mychart \
813  --namespace production \
814  --atomic \
815  --timeout 10m \
816  --wait
817 
818# Upgrade with cleanup on failure
819helm upgrade myapp ./mychart \
820  --namespace production \
821  --cleanup-on-fail
822 
823# Force resource update (recreate)
824helm upgrade myapp ./mychart \
825  --namespace production \
826  --force
827 
828# Dry run before upgrade
829helm upgrade myapp ./mychart \
830  --namespace production \
831  --dry-run \
832  --debug
833 
834# Compare current vs new
835helm get manifest myapp -n production > current.yaml
836helm template myapp ./mychart -f values-prod.yaml > new.yaml
837diff current.yaml new.yaml
838 
839# Rollback to specific revision
840helm rollback myapp 3 --namespace production
841 
842# Rollback with wait
843helm rollback myapp 3 --namespace production --wait --timeout 5m
844 
845# View revision history
846helm history myapp --namespace production
847```
848 
849## Library Charts
850 
851```yaml
852# Chart.yaml for library chart
853apiVersion: v2
854name: mylib
855type: library
856version: 1.0.0
857```
858 
859```yaml
860# templates/_deployment.tpl in library
861{{- define "mylib.deployment" -}}
862apiVersion: apps/v1
863kind: Deployment
864metadata:
865  name: {{ include "mylib.fullname" . }}
866  labels:
867    {{- include "mylib.labels" . | nindent 4 }}
868spec:
869  replicas: {{ .Values.replicaCount }}
870  selector:
871    matchLabels:
872      {{- include "mylib.selectorLabels" . | nindent 6 }}
873  template:
874    metadata:
875      labels:
876        {{- include "mylib.selectorLabels" . | nindent 8 }}
877    spec:
878      containers:
879        - name: {{ .Chart.Name }}
880          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
881{{- end }}
882```
883 
884```yaml
885# Using library chart
886# Chart.yaml
887dependencies:
888  - name: mylib
889    version: "1.x.x"
890    repository: https://charts.example.com
891 
892# templates/deployment.yaml
893{{- include "mylib.deployment" . }}
894```
895 
896## Best Practices
897 
8981. **Versioning**: Follow semantic versioning for charts
8992. **Values**: Provide sensible defaults, allow overrides
9003. **Documentation**: Document all values in README
9014. **Testing**: Include tests in templates/tests/
9025. **Helpers**: Use _helpers.tpl for reusable templates
9036. **Labels**: Include standard Kubernetes labels
9047. **Annotations**: Use annotations for metadata and tools
9058. **Hooks**: Use hooks for migrations, cleanup
9069. **Dependencies**: Pin dependency versions
90710. **Schema**: Validate values with values.schema.json
90811. **Use ct** for comprehensive chart testing in CI
90912. **Use helm-diff** before production upgrades
91013. **Encrypt secrets** with helm-secrets or sealed-secrets
91114. **Use library charts** for shared patterns
91215. **Push to OCI registries** for better artifact management
913