Helm

values.yaml ─┐
-f, --set  ──┼─► merge ─► templates/ ─► YAML ─► schema + OpenAPI
charts/    ──┘                                   check
                        ┌──────────────────────────┘
                        ▼
      server-side apply ─► --wait (kstatus) ─► store revision

apiVersion: v2                # v2 = Helm 3 and 4 charts
name: api
description: Acme API
type: application             # or library
version: 1.2.0                # chart SemVer; bump on change
appVersion: "1.4.2"           # app version; quote it
kubeVersion: ">=1.33.0-0"     # -0 lets pre-releases match
keywords: [api, acme]
home: https://github.com/acme/api
sources: [https://github.com/acme/api]
maintainers:
  - name: Acme Platform
    email: platform@acme.dev
icon: https://acme.dev/icon.svg
dependencies:
  - name: common
    version: ~2.3.0
    repository: oci://ghcr.io/acme/charts
annotations:
  artifacthub.io/license: MIT

replicaCount: 2
image:
  repository: ghcr.io/acme/api
  tag: ""                     # empty = .Chart.AppVersion
  pullPolicy: IfNotPresent
service:
  port: 80
  targetPort: 3000
env: []
resources:
  requests: { cpu: 100m, memory: 256Mi }
  limits: { memory: 256Mi }
config:
  LOG_LEVEL: info
ingress:
  enabled: false
  className: ""
  annotations: {}
  hosts: []
  tls: []

metadata:
  {{- with .Values.podAnnotations }}
  annotations:
    {{- toYaml . | nindent 4 }}
  {{- end }}
spec:
  containers:
    - name: api
      env:
        {{- range $k, $v := .Values.config }}
        - name: {{ $k }}
          value: {{ $v | quote }}
        {{- end }}
        - name: RELEASE
          value: {{ $.Release.Name }}   # $ = root

{{- define "api.name" -}}
{{- default .Chart.Name .Values.nameOverride
  | trunc 63 | trimSuffix "-" }}
{{- end }}
 
{{- define "api.fullname" -}}
{{- $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 }}
 
{{- define "api.selectorLabels" -}}
app.kubernetes.io/name: {{ include "api.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}
 
{{- define "api.labels" -}}
{{ include "api.selectorLabels" . }}
helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}
 
{{- define "api.image" -}}
{{- $tag := .Values.image.tag | default .Chart.AppVersion }}
{{- printf "%s:%s" .Values.image.repository $tag }}
{{- end }}

apiVersion: batch/v1
kind: Job
metadata:
  name: {{ include "api.fullname" . }}-migrate
  annotations:
    helm.sh/hook: pre-install,pre-upgrade
    helm.sh/hook-weight: "0"
    helm.sh/hook-delete-policy: >-
      before-hook-creation,hook-succeeded
spec:
  backoffLimit: 1
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: migrate
          image: {{ include "api.image" . }}
          command: [bun, run, db:migrate]
          envFrom:
            - secretRef:
                name: {{ .Values.db.existingSecret }}

apiVersion: v1
kind: Pod
metadata:
  name: {{ include "api.fullname" . }}-test
  annotations:
    helm.sh/hook: test
    helm.sh/hook-delete-policy: hook-succeeded
spec:
  restartPolicy: Never
  containers:
    - name: wget
      image: busybox:1.37
      command: [wget, -qO-]
      args:
        - http://{{ include "api.fullname" . }}/healthz

dependencies:
  - name: postgresql
    version: ~16.2.0          # SemVer range
    repository: oci://ghcr.io/acme/charts
    condition: postgresql.enabled
  - name: worker
    alias: emails             # values key becomes emails:
    version: 1.x
    repository: file://../worker
    tags: [workers]

global:                  # all charts: .Values.global
  imageRegistry: ghcr.io/acme
postgresql:              # the subchart's .Values
  enabled: true
  auth: { database: app }
emails:
  replicaCount: 2

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

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: {{ include "api.fullname" . }}-db
spec:
  refreshInterval: 1h
  secretStoreRef: { kind: ClusterSecretStore, name: vault }
  target:
    name: {{ include "api.fullname" . }}-db
  data:
    - secretKey: DATABASE_URL
      remoteRef: { key: apps/api, property: database_url }

echo "$GHCR_TOKEN" | helm registry login ghcr.io \
  -u "$GH_USER" --password-stdin
 
helm package ./api                  # api-1.2.0.tgz
helm push api-1.2.0.tgz oci://ghcr.io/acme/charts
# stored as ghcr.io/acme/charts/api:1.2.0; prints the digest
 
helm show values oci://ghcr.io/acme/charts/api \
  --version 1.2.0
helm upgrade --install api oci://ghcr.io/acme/charts/api \
  --version 1.2.0 -n web
 
# Helm 4: pin by digest
helm install api \
  oci://ghcr.io/acme/charts/api@sha256:9f86d0…

repositories:
  - name: grafana
    url: https://grafana.github.io/helm-charts
releases:
  - name: loki
    namespace: observability
    chart: grafana/loki
    version: ~6.40.0
    values: [values/loki.yaml]
  - name: api
    namespace: web
    chart: oci://ghcr.io/acme/charts/api
    version: 1.2.0
    values: [values/prod.yaml]

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "api.fullname" . }}
  labels: {{- include "api.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      {{- include "api.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "api.selectorLabels" . | nindent 8 }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: {{ include "api.image" . }}
          ports:
            - name: http
              containerPort: {{ .Values.service.targetPort }}
          env: {{- toYaml .Values.env | nindent 12 }}
          resources:
            {{- toYaml .Values.resources | nindent 12 }}

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "api.fullname" . }}
data:
  {{- range $k, $v := .Values.config }}
  {{ $k }}: {{ $v | quote }}
  {{- end }}

  template:
    metadata:
      annotations:
        checksum/config: {{ include
          (print $.Template.BasePath "/configmap.yaml") .
          | sha256sum }}

# helm upgrade --install api ./api -n prod \
#   -f values/prod.yaml --set-string image.tag="$SHA" \
#   --rollback-on-failure --timeout 10m
replicaCount: 4
resources:
  requests: { cpu: 250m, memory: 512Mi }
  limits: { memory: 512Mi }
config:
  LOG_LEVEL: warn
ingress:
  enabled: true
  className: traefik
  hosts:
    - host: api.acme.dev
  tls:
    - secretName: api-tls
      hosts: [api.acme.dev]

apiVersion: v2
name: shop
version: 0.3.0
dependencies:
  - name: api
    version: ~1.2.0
    repository: oci://ghcr.io/acme/charts
  - name: web
    version: ~2.0.0
    repository: file://../web
  - name: worker
    alias: emails
    version: ~1.0.0
    repository: oci://ghcr.io/acme/charts
    condition: emails.enabled

global:
  imageRegistry: ghcr.io/acme
api:
  replicaCount: 3
emails:
  enabled: true

# helm-diff; Helm 4 checks the plugin's GPG signature
curl -sL https://github.com/databus23.gpg | gpg --import
u=https://github.com/databus23/helm-diff/releases/latest
helm plugin install \
  "$u/download/helm-diff-darwin-arm64.tgz"
 
# live release vs. new chart + values; exit 2 on changes
helm diff upgrade api ./api -n prod \
  -f values/prod.yaml --context 3 --detailed-exitcode
 
# no cluster: compare two renders
diff -u \
  <(helm template api ./api -f values/staging.yaml) \
  <(helm template api ./api -f values/prod.yaml)