ContextQMD
Back to Agents

Helm Chart Structure Reference

plugins/kubernetes-operations/skills/helm-chart-scaffolding/references/chart-structure.md

latest11.2 KB
Original Source

Helm Chart Structure Reference

Complete guide to Helm chart organization, file conventions, and best practices.

Standard Chart Directory Structure

my-app/
├── Chart.yaml              # Chart metadata (required)
├── Chart.lock              # Dependency lock file (generated)
├── values.yaml             # Default configuration values (required)
├── values.schema.json      # JSON schema for values validation
├── .helmignore             # Patterns to ignore when packaging
├── README.md               # Chart documentation
├── LICENSE                 # Chart license
├── charts/                 # Chart dependencies (bundled)
│   └── postgresql-12.0.0.tgz
├── crds/                   # Custom Resource Definitions
│   └── my-crd.yaml
├── templates/              # Kubernetes manifest templates (required)
│   ├── NOTES.txt          # Post-install instructions
│   ├── _helpers.tpl       # Template helper functions
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── configmap.yaml
│   ├── secret.yaml
│   ├── serviceaccount.yaml
│   ├── hpa.yaml
│   ├── pdb.yaml
│   ├── networkpolicy.yaml
│   └── tests/
│       └── test-connection.yaml
└── files/                  # Additional files to include
    └── config/
        └── app.conf

Chart.yaml Specification

API Version v2 (Helm 3+)

yaml
apiVersion: v2 # Required: API version
name: my-application # Required: Chart name
version: 1.2.3 # Required: Chart version (SemVer)
appVersion: "2.5.0" # Application version
description: A Helm chart for my application # Required
type: application # Chart type: application or library
keywords: # Search keywords
  - web
  - api
  - backend
home: https://example.com # Project home page
sources: # Source code URLs
  - https://github.com/example/my-app
maintainers: # Maintainer list
  - name: John Doe
    email: [email protected]
    url: https://github.com/johndoe
icon: https://example.com/icon.png # Chart icon URL
kubeVersion: ">=1.24.0" # Compatible Kubernetes versions
deprecated: false # Mark chart as deprecated
annotations: # Arbitrary annotations
  example.com/release-notes: https://example.com/releases/v1.2.3
dependencies: # Chart dependencies
  - name: postgresql
    version: "12.0.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled
    tags:
      - database
    import-values:
      - child: database
        parent: database
    alias: db

Chart Types

Application Chart

yaml
type: application
  • Standard Kubernetes applications
  • Can be installed and managed
  • Contains templates for K8s resources

Library Chart

yaml
type: library
  • Shared template helpers
  • Cannot be installed directly
  • Used as dependency by other charts
  • No templates/ directory

Values Files Organization

values.yaml (defaults)

yaml
# Global values (shared with subcharts)
global:
  imageRegistry: docker.io
  imagePullSecrets: []

# Image configuration
image:
  registry: docker.io
  repository: myapp/web
  tag: "" # Defaults to .Chart.AppVersion
  pullPolicy: IfNotPresent

# Deployment settings
replicaCount: 1
revisionHistoryLimit: 10

# Pod configuration
podAnnotations: {}
podSecurityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 1000

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

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

# Resources
resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 100m
    memory: 128Mi

# Autoscaling
autoscaling:
  enabled: false
  minReplicas: 1
  maxReplicas: 100
  targetCPUUtilizationPercentage: 80

# Node selection
nodeSelector: {}
tolerations: []
affinity: {}

# Monitoring
serviceMonitor:
  enabled: false
  interval: 30s

values.schema.json (validation)

json
{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "replicaCount": {
      "type": "integer",
      "minimum": 1
    },
    "image": {
      "type": "object",
      "required": ["repository"],
      "properties": {
        "repository": {
          "type": "string"
        },
        "tag": {
          "type": "string"
        },
        "pullPolicy": {
          "type": "string",
          "enum": ["Always", "IfNotPresent", "Never"]
        }
      }
    }
  },
  "required": ["image"]
}

Template Files

Template Naming Conventions

  • Lowercase with hyphens: deployment.yaml, service-account.yaml
  • Partial templates: Prefix with underscore _helpers.tpl
  • Tests: Place in templates/tests/
  • CRDs: Place in crds/ (not templated)

Common Templates

_helpers.tpl

yaml
{{/*
Standard naming helpers
*/}}
{{- define "my-app.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
{{- end -}}

{{- define "my-app.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 -}}

{{- define "my-app.chart" -}}
{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" -}}
{{- end -}}

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

{{- define "my-app.selectorLabels" -}}
app.kubernetes.io/name: {{ include "my-app.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end -}}

{{/*
Image name helper
*/}}
{{- define "my-app.image" -}}
{{- $registry := .Values.global.imageRegistry | default .Values.image.registry -}}
{{- $repository := .Values.image.repository -}}
{{- $tag := .Values.image.tag | default .Chart.AppVersion -}}
{{- printf "%s/%s:%s" $registry $repository $tag -}}
{{- end -}}

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 }}

{{- if .Values.ingress.enabled }}

Application URL:
{{- range .Values.ingress.hosts }}
  http{{ if $.Values.ingress.tls }}s{{ end }}://{{ .host }}{{ .path }}
{{- end }}
{{- else }}

Get the application URL by running:
  export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "my-app.name" . }}" -o jsonpath="{.items[0].metadata.name}")
  kubectl port-forward $POD_NAME 8080:80
  echo "Visit http://127.0.0.1:8080"
{{- end }}

Dependencies Management

Declaring Dependencies

yaml
# Chart.yaml
dependencies:
  - name: postgresql
    version: "12.0.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled # Enable/disable via values
    tags: # Group dependencies
      - database
    import-values: # Import values from subchart
      - child: database
        parent: database
    alias: db # Reference as .Values.db

Managing Dependencies

bash
# Update dependencies
helm dependency update

# List dependencies
helm dependency list

# Build dependencies
helm dependency build

Chart.lock

Generated automatically by helm dependency update:

yaml
dependencies:
  - name: postgresql
    repository: https://charts.bitnami.com/bitnami
    version: 12.0.0
digest: sha256:abcd1234...
generated: "2024-01-01T00:00:00Z"

.helmignore

Exclude files from chart package:

# Development files
.git/
.gitignore
*.md
docs/

# Build artifacts
*.swp
*.bak
*.tmp
*.orig

# CI/CD
.travis.yml
.gitlab-ci.yml
Jenkinsfile

# Testing
test/
*.test

# IDE
.vscode/
.idea/
*.iml

Custom Resource Definitions (CRDs)

Place CRDs in crds/ directory:

crds/
├── my-app-crd.yaml
└── another-crd.yaml

Important CRD notes:

  • CRDs are installed before any templates
  • CRDs are NOT templated (no {{ }} syntax)
  • CRDs are NOT upgraded or deleted with chart
  • Use helm install --skip-crds to skip installation

Chart Versioning

Semantic Versioning

  • Chart Version: Increment when chart changes

    • MAJOR: Breaking changes
    • MINOR: New features, backward compatible
    • PATCH: Bug fixes

  • App Version: Application version being deployed

    • Can be any string
    • Not required to follow SemVer
yaml
version: 2.3.1 # Chart version
appVersion: "1.5.0" # Application version

Chart Testing

Test Files

yaml
# templates/tests/test-connection.yaml
apiVersion: v1
kind: Pod
metadata:
  name: "{{ include "my-app.fullname" . }}-test-connection"
  annotations:
    "helm.sh/hook": test
    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
spec:
  containers:
  - name: wget
    image: busybox
    command: ['wget']
    args: ['{{ include "my-app.fullname" . }}:{{ .Values.service.port }}']
  restartPolicy: Never

Running Tests

bash
helm test my-release
helm test my-release --logs

Hooks

Helm hooks allow intervention at specific points:

yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: {{ include "my-app.fullname" . }}-migration
  annotations:
    "helm.sh/hook": pre-upgrade,pre-install
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded

Hook Types

  • pre-install: Before templates rendered
  • post-install: After all resources loaded
  • pre-delete: Before any resources deleted
  • post-delete: After all resources deleted
  • pre-upgrade: Before upgrade
  • post-upgrade: After upgrade
  • pre-rollback: Before rollback
  • post-rollback: After rollback
  • test: Run with helm test

Hook Weight

Controls hook execution order (-5 to 5, lower runs first)

Hook Deletion Policies

  • before-hook-creation: Delete previous hook before new one
  • hook-succeeded: Delete after successful execution
  • hook-failed: Delete if hook fails

Best Practices

  1. Use helpers for repeated template logic
  2. Quote strings in templates: {{ .Values.name | quote }}
  3. Validate values with values.schema.json
  4. Document all values in values.yaml
  5. Use semantic versioning for chart versions
  6. Pin dependency versions exactly
  7. Include NOTES.txt with usage instructions
  8. Add tests for critical functionality
  9. Use hooks for database migrations
  10. Keep charts focused - one application per chart

Chart Repository Structure

helm-charts/
├── index.yaml
├── my-app-1.0.0.tgz
├── my-app-1.1.0.tgz
├── my-app-1.2.0.tgz
└── another-chart-2.0.0.tgz

Creating Repository Index

bash
helm repo index . --url https://charts.example.com