mychart/
  Chart.yaml     # Chart metadata
  values.yaml    # Default configuration values
  templates/     # Template directory

apiVersion: v2
name: mychart
description: A Helm chart for Kubernetes
type: application  # or 'library' for helper charts
version: 0.1.0     # Chart version (SemVer)
appVersion: "1.16.0"  # Version of the app

# Optional but recommended
keywords:
  - web
  - application
home: https://github.com/example/mychart
sources:
  - https://github.com/example/mychart
maintainers:
  - name: Your Name
    email: your.email@example.com

# Dependencies
dependencies:
  - name: postgresql
    version: "~11.6.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled

# Kubernetes version constraint
kubeVersion: ">=1.21.0-0"

{{- define "mychart.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}

metadata:
  name: {{ include "mychart.fullname" . }}

metadata:
  labels:
    {{- include "mychart.labels" . | nindent 4 }}

metadata:
  labels:
    {{- template "mychart.labels" . }}

env:
  - name: DATABASE_HOST
    value: {{ .Values.database.host | quote }}

env:
  - name: DATABASE_HOST
    value: {{ .Values.database.host }}

apiVersion: v1
kind: Secret
metadata:
  name: {{ include "mychart.fullname" . }}
data:
  password: {{ required "A valid .Values.password is required!" .Values.password | b64enc }}

replicas: {{ .Values.replicaCount | default 1 }}

spec:
  template:
    metadata:
      labels:
        {{- include "mychart.labels" . | nindent 8 }}

spec:
  template:
    metadata:
      labels:
{{ include "mychart.labels" . | indent 8 }}

{{- with .Values.resources }}
resources:
  {{- toYaml . | nindent 2 }}
{{- end }}

{{- if .Values.ingress.enabled -}}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ include "mychart.fullname" . }}
# ... ingress definition
{{- end }}

{{- with .Values.nodeSelector }}
nodeSelector:
  {{- toYaml . | nindent 2 }}
{{- end }}

{{- /*
This helper creates the fullname for resources.
It supports nameOverride and fullnameOverride values.
*/ -}}
{{- define "mychart.fullname" -}}
{{- end }}

# This creates the fullname
{{- define "mychart.fullname" -}}
{{- end }}

replicaCount: 1
imagePullPolicy: IfNotPresent

image:
  repository: nginx
  pullPolicy: IfNotPresent
  tag: "1.21.0"

app:
  deployment:
    pod:
      container:
        image:
          repository: nginx

# replicaCount is the number of pod replicas for the deployment
replicaCount: 1

# image configures the container image
image:
  # image.repository is the container image registry and name
  repository: nginx
  # image.pullPolicy is the image pull policy
  pullPolicy: IfNotPresent
  # image.tag overrides the image tag (default is chart appVersion)
  tag: "1.21.0"

replicaCount: 1

service:
  type: ClusterIP
  port: 80

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

ingress:
  enabled: false
  className: ""
  annotations: {}
  hosts:
    - host: chart-example.local
      paths:
        - path: /
          pathType: ImplementationSpecific
  tls: []

autoscaling:
  enabled: false
  minReplicas: 1
  maxReplicas: 100
  targetCPUUtilizationPercentage: 80
  targetMemoryUtilizationPercentage: 80

nodeSelector: {}
tolerations: []
affinity: {}

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

metadata:
  labels:
    app.kubernetes.io/name: {{ include "mychart.name" . }}
    app.kubernetes.io/instance: {{ .Release.Name }}
    app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
    app.kubernetes.io/managed-by: {{ .Release.Service }}
    helm.sh/chart: {{ include "mychart.chart" . }}

securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 2000
  capabilities:
    drop:
      - ALL
  readOnlyRootFilesystem: true

livenessProbe:
  httpGet:
    path: /healthz
    port: http
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /ready
    port: http
  initialDelaySeconds: 5
  periodSeconds: 5

# ConfigMap for non-sensitive config
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "mychart.fullname" . }}
data:
  app.conf: |
    {{- .Values.config | nindent 4 }}

# Secret for sensitive data
apiVersion: v1
kind: Secret
metadata:
  name: {{ include "mychart.fullname" . }}
type: Opaque
data:
  password: {{ .Values.password | b64enc }}

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

helm test <release-name>

# Test with production values
helm template my-release ./mychart -f values-prod.yaml

# Test with development values
helm template my-release ./mychart -f values-dev.yaml

# Test with overrides
helm template my-release ./mychart --set replicaCount=3

# Lint the chart
helm lint ./mychart

# Dry-run install
helm install my-release ./mychart --dry-run --debug

# Validate against cluster
helm install my-release ./mychart --dry-run

data:
  password: cGFzc3dvcmQ=  # Don't do this!

data:
  password: {{ .Values.password | b64enc }}

{{- if .Values.serviceAccount.create -}}
apiVersion: v1
kind: ServiceAccount
metadata:
  name: {{ include "mychart.serviceAccountName" . }}
{{- end }}

securityContext:
  runAsNonRoot: true
  runAsUser: 1000

securityContext:
  capabilities:
    drop:
      - ALL

# .helmignore
.git/
.gitignore
*.md
.DS_Store
*.swp
test/

{{- with .Values.resources }}
resources:
  {{- toYaml . | nindent 2 }}
{{- end }}

resources:
  {{- if .Values.resources.limits }}
  limits:
    {{- if .Values.resources.limits.cpu }}
    cpu: {{ .Values.resources.limits.cpu }}
    {{- end }}
    {{- if .Values.resources.limits.memory }}
    memory: {{ .Values.resources.limits.memory }}
    {{- end }}
  {{- end }}
  # ... more nested conditionals

git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

{{ if .Values.enabled }}
  key: value
{{ end }}

{{- if .Values.enabled }}
  key: value
{{- end }}

name: {{ .Release.Name }}-{{ .Chart.Name }}-deployment

name: {{ include "mychart.fullname" . | trunc 63 | trimSuffix "-" }}

replicas: {{ .Values.replicaCount }}

replicas: {{ required "replicaCount is required" .Values.replicaCount }}

image: nginx:1.21.0

image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"

metadata:
  annotations:
    "helm.sh/hook": pre-upgrade
    "helm.sh/hook-weight": "1"
    "helm.sh/hook-delete-policy": hook-succeeded

# Show what would change
helm diff upgrade my-release ./mychart

# Dry-run upgrade
helm upgrade my-release ./mychart --dry-run --debug

{{- /*
mychart.fullname generates a fully qualified application name.
It supports fullnameOverride and nameOverride values.
Maximum length is 63 characters per DNS naming spec.
Usage: {{ include "mychart.fullname" . }}
*/ -}}
{{- define "mychart.fullname" -}}
{{- end }}

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 }}://{{ . }}{{ $.Values.ingress.path }}
{{- end }}
{{- end }}

helm package ./mychart

# Create index
helm repo index .

# Serve repository
helm serve

repositoryID: <uuid>
owners:
  - name: Your Name
    email: your.email@example.com

Kubernetes YAML Best Practices

This reference provides comprehensive best practices for creating, maintaining, and validating Kubernetes resources in Helm charts.

General YAML Best Practices

Formatting and Style

• Use 2 spaces for indentation (not tabs)
• Keep lines under 120 characters when possible
• Use lowercase for keys
• Quote string values containing special characters
• Always specify apiVersion and kind
• Include metadata.name for all resources
• Use consistent naming conventions (lowercase, hyphens for separators)

Resource Organization

• One resource per file for clarity (unless logically grouped)
• Use --- to separate multiple resources in a single file
• Name files descriptively: <resource-type>-<name>.yaml
• Group related resources together (e.g., deployment + service + configmap)

Metadata Best Practices

Standard Metadata Structure

metadata:
  name: my-app
  namespace: production
  labels:
    app.kubernetes.io/name: my-app
    app.kubernetes.io/instance: my-app-prod
    app.kubernetes.io/version: "1.0.0"
    app.kubernetes.io/component: backend
    app.kubernetes.io/part-of: my-system
    app.kubernetes.io/managed-by: helm
    helm.sh/chart: my-app-1.0.0
  annotations:
    description: "Backend service for my-app"
    prometheus.io/scrape: "true"
    prometheus.io/port: "8080"

Kubernetes Recommended Labels

Always include these standard labels for better tooling integration:

Label	Description	Example
app.kubernetes.io/name	Application name	nginx
app.kubernetes.io/instance	Unique instance identifier	nginx-prod
app.kubernetes.io/version	Application version	1.21.0
app.kubernetes.io/component	Component within architecture	frontend
app.kubernetes.io/part-of	Higher-level application	wordpress
app.kubernetes.io/managed-by	Tool managing the resource	helm

Helm-Specific Labels

labels:
  helm.sh/chart: {{ include "mychart.chart" . }}
  app.kubernetes.io/managed-by: {{ .Release.Service }}

Labels and Selectors

Selector Best Practices

• Selectors must match pod labels exactly
• Use immutable selectors (they cannot be changed after creation)
• Keep selector labels minimal but unique

Good:

spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: my-app
      app.kubernetes.io/instance: my-app-prod
  template:
    metadata:
      labels:
        app.kubernetes.io/name: my-app
        app.kubernetes.io/instance: my-app-prod
        app.kubernetes.io/version: "1.0.0"  # Additional labels OK

Bad:

spec:
  selector:
    matchLabels:
      app: my-app
      version: "1.0.0"  # Version in selector prevents rolling updates!

Label Key Conventions

• Use DNS subdomain format for prefixed keys: prefix/key
• Keys without prefix are private to the user
• Standard prefixes: app.kubernetes.io/, helm.sh/, kubernetes.io/

Resource Limits and Requests

Why They Matter

• Requests: Minimum resources guaranteed to the container
• Limits: Maximum resources the container can use
• Required for proper scheduling, QoS class assignment, and cluster stability

Recommended Configuration

resources:
  requests:
    memory: "64Mi"
    cpu: "100m"
  limits:
    memory: "128Mi"
    cpu: "500m"

Guidelines by Resource Type

Resource Type	Requests	Limits	Notes
CPU	Set always	Optional	Consider burstable workloads
Memory	Set always	Set always	Prevents OOM kills
Ephemeral Storage	Optional	Recommended	For disk-intensive apps

QoS Classes

Kubernetes assigns Quality of Service classes based on resource settings:

1. Guaranteed: requests == limits for all containers
2. Burstable: At least one container has requests < limits
3. BestEffort: No requests or limits set (not recommended)

# Guaranteed QoS
resources:
  requests:
    memory: "128Mi"
    cpu: "500m"
  limits:
    memory: "128Mi"
    cpu: "500m"

Memory Guidelines

• Set memory limits to prevent OOM kills affecting other pods
• Memory is incompressible - exceeding limits causes termination
• Monitor actual usage before setting production values

CPU Guidelines

• CPU is compressible - exceeding limits causes throttling, not termination
• Consider not setting CPU limits for burstable workloads
• Use millicores: 100m = 0.1 CPU core

Probes Configuration

Liveness Probe

Determines if the container should be restarted:

livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
    httpHeaders:
      - name: X-Health-Check
        value: liveness
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3
  successThreshold: 1

Readiness Probe

Determines if the container can receive traffic:

readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 5
  timeoutSeconds: 3
  failureThreshold: 3
  successThreshold: 1

Startup Probe

For slow-starting containers (Kubernetes 1.18+):

startupProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 0
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 30  # 30 * 10 = 300s max startup time
  successThreshold: 1

Probe Types

Type	Use Case	Example
httpGet	HTTP endpoints	REST APIs, web apps
tcpSocket	TCP connections	Databases, message queues
exec	Custom scripts	Complex health checks
grpc	gRPC services	gRPC health protocol

Probe Best Practices

• Liveness: Check if app is running, not dependencies
• Readiness: Check if app can serve traffic (including dependencies)
• Startup: Use for slow-starting apps instead of long initialDelaySeconds
• Set appropriate timeouts to prevent false positives
• Don’t make probes too aggressive (high CPU overhead)

Security Context

Pod-Level Security Context

spec:
  securityContext:
    runAsNonRoot: true
    runAsUser: 1000
    runAsGroup: 3000
    fsGroup: 2000
    fsGroupChangePolicy: "OnRootMismatch"
    seccompProfile:
      type: RuntimeDefault

Container-Level Security Context

containers:
  - name: app
    securityContext:
      allowPrivilegeEscalation: false
      readOnlyRootFilesystem: true
      runAsNonRoot: true
      runAsUser: 1000
      capabilities:
        drop:
          - ALL
        add:
          - NET_BIND_SERVICE  # Only if needed
      seccompProfile:
        type: RuntimeDefault

Security Context Fields Explained

Field	Level	Description
runAsNonRoot	Pod/Container	Prevents running as root
runAsUser	Pod/Container	Specifies UID to run as
runAsGroup	Pod/Container	Specifies GID to run as
fsGroup	Pod	Group ownership for volumes
readOnlyRootFilesystem	Container	Makes root filesystem read-only
allowPrivilegeEscalation	Container	Prevents privilege escalation
capabilities	Container	Linux capabilities management
seccompProfile	Pod/Container	Syscall filtering

Recommended Security Baseline

spec:
  securityContext:
    runAsNonRoot: true
    seccompProfile:
      type: RuntimeDefault
  containers:
    - name: app
      securityContext:
        allowPrivilegeEscalation: false
        readOnlyRootFilesystem: true
        capabilities:
          drop:
            - ALL

Image Management

Image Specification Best Practices

containers:
  - name: app
    image: registry.example.com/my-app:v1.2.3
    imagePullPolicy: IfNotPresent

Image Pull Policy

Policy	When to Use
Always	For :latest tags or mutable tags
IfNotPresent	For immutable tags (recommended)
Never	For pre-loaded images (rare)

Image Best Practices

• Always use specific tags: Never use :latest in production
• Use digest for immutability: image@sha256:abc123...
• Use private registries: For security and reliability
• Scan images: Implement vulnerability scanning in CI/CD

# Recommended: Specific tag
image: nginx:1.21.6

# Better: Digest for immutability
image: nginx@sha256:2834dc507516af02784808c5f48b7cbe38b8ed5d0f4837f16e78d00deb7e7767

# Avoid: Mutable tags
image: nginx:latest  # Don't do this in production

Pod Disruption Budgets

Why PDBs Matter

Pod Disruption Budgets ensure high availability during voluntary disruptions like:

• Node drains
• Cluster upgrades
• Deployment rollouts

PDB Configuration

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: my-app-pdb
spec:
  # Option 1: Minimum available pods
  minAvailable: 2

  # Option 2: Maximum unavailable pods (use one, not both)
  # maxUnavailable: 1

  selector:
    matchLabels:
      app.kubernetes.io/name: my-app

PDB Best Practices

• Set PDB for all production workloads with multiple replicas
• Use minAvailable when you need minimum capacity guarantee
• Use maxUnavailable when you want to limit disruption rate
• Don’t set minAvailable equal to replicas (blocks all disruptions)

# Good: Allows 1 pod to be unavailable
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: {{ include "mychart.fullname" . }}-pdb
spec:
  maxUnavailable: 1
  selector:
    matchLabels:
      {{- include "mychart.selectorLabels" . | nindent 6 }}

Horizontal Pod Autoscaler

HPA Configuration

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: my-app-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: my-app
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
        - type: Percent
          value: 10
          periodSeconds: 60
    scaleUp:
      stabilizationWindowSeconds: 0
      policies:
        - type: Percent
          value: 100
          periodSeconds: 15
        - type: Pods
          value: 4
          periodSeconds: 15
      selectPolicy: Max

HPA Best Practices

• Always set resource requests (required for CPU/memory-based scaling)
• Set appropriate minReplicas for base capacity
• Use stabilization windows to prevent flapping
• Consider custom metrics for business-specific scaling
• Don’t use HPA with replicas field in Deployment (conflicts)

Helm Template for HPA

{{- if .Values.autoscaling.enabled }}
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: {{ include "mychart.fullname" . }}
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: {{ include "mychart.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 }}

Network Policies

Default Deny All

Start with a default deny policy, then allow specific traffic:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny-all
  namespace: my-namespace
spec:
  podSelector: {}
  policyTypes:
    - Ingress
    - Egress

Allow Specific Ingress

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-frontend-to-backend
spec:
  podSelector:
    matchLabels:
      app: backend
  policyTypes:
    - Ingress
  ingress:
    - from:
        - podSelector:
            matchLabels:
              app: frontend
      ports:
        - protocol: TCP
          port: 8080

Allow Egress to External Services

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-egress-to-database
spec:
  podSelector:
    matchLabels:
      app: backend
  policyTypes:
    - Egress
  egress:
    - to:
        - ipBlock:
            cidr: 10.0.0.0/8
      ports:
        - protocol: TCP
          port: 5432
    # Allow DNS resolution
    - to:
        - namespaceSelector: {}
          podSelector:
            matchLabels:
              k8s-app: kube-dns
      ports:
        - protocol: UDP
          port: 53

Network Policy Best Practices

• Start with default deny, then allow specific traffic
• Always allow DNS egress (UDP port 53)
• Use namespace selectors for cross-namespace communication
• Label namespaces for policy targeting
• Test policies in staging before production

Service Configuration

Service Types

Type	Use Case
ClusterIP	Internal cluster communication (default)
NodePort	External access via node ports (30000-32767)
LoadBalancer	Cloud provider load balancers
ExternalName	DNS CNAME for external services

Service Best Practices

apiVersion: v1
kind: Service
metadata:
  name: my-app
  labels:
    {{- include "mychart.labels" . | nindent 4 }}
spec:
  type: ClusterIP
  ports:
    - port: 80
      targetPort: http
      protocol: TCP
      name: http
  selector:
    {{- include "mychart.selectorLabels" . | nindent 4 }}

Named Ports

Always use named ports for clarity:

# In Deployment
ports:
  - name: http
    containerPort: 8080
    protocol: TCP
  - name: metrics
    containerPort: 9090
    protocol: TCP

# In Service
ports:
  - name: http
    port: 80
    targetPort: http  # References named port

ConfigMaps and Secrets

ConfigMap Best Practices

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "mychart.fullname" . }}-config
data:
  # For simple key-value pairs
  LOG_LEVEL: "info"
  MAX_CONNECTIONS: "100"

  # For file content
  app.properties: |
    server.port=8080
    server.host=0.0.0.0

Secret Best Practices

apiVersion: v1
kind: Secret
metadata:
  name: {{ include "mychart.fullname" . }}-secret
type: Opaque
data:
  # Base64 encoded values
  password: {{ .Values.password | b64enc | quote }}
  api-key: {{ .Values.apiKey | b64enc | quote }}
stringData:
  # Plain text (will be encoded)
  config.yaml: |
    database:
      host: {{ .Values.database.host }}

Mounting as Environment Variables

env:
  - name: LOG_LEVEL
    valueFrom:
      configMapKeyRef:
        name: my-config
        key: LOG_LEVEL
  - name: DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: my-secret
        key: password

Mounting as Files

volumes:
  - name: config
    configMap:
      name: my-config
  - name: secrets
    secret:
      secretName: my-secret
      defaultMode: 0400

volumeMounts:
  - name: config
    mountPath: /etc/config
    readOnly: true
  - name: secrets
    mountPath: /etc/secrets
    readOnly: true

Common Validation Issues

Missing Required Fields

Issue	Fix
Missing apiVersion	Add appropriate API version
Missing kind	Add resource kind
Missing metadata.name	Add resource name
Missing spec.selector	Add pod selector for Deployments/Services
Empty containers	Add at least one container

Selector Mismatches

# Error: Selector doesn't match pod labels
spec:
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        application: my-app  # Wrong label key!

Invalid Values

Field	Valid Format	Example
CPU	Millicores or decimal	500m, 0.5
Memory	Binary units	512Mi, 1Gi
Port	1-65535	8080
DNS names	Lowercase alphanumeric with hyphens	my-app-service

Namespace Issues

• Not all resources are namespaced (e.g., ClusterRole, PersistentVolume)
• Services must be in the same namespace as pods they target
• Default namespace is “default” if not specified

Deprecation Warnings

Deprecated APIs

Old API	New API	K8s Version
extensions/v1beta1 Deployment	apps/v1	1.16+
extensions/v1beta1 Ingress	networking.k8s.io/v1	1.19+
networking.k8s.io/v1beta1 Ingress	networking.k8s.io/v1	1.19+
policy/v1beta1 PodDisruptionBudget	policy/v1	1.21+
policy/v1beta1 PodSecurityPolicy	Removed (use PSA)	1.25+
autoscaling/v2beta1 HPA	autoscaling/v2	1.23+
batch/v1beta1 CronJob	batch/v1	1.21+

Checking API Versions

# List available API versions
kubectl api-versions

# Check if resource supports specific version
kubectl api-resources | grep deployments

CRD-Specific Considerations

API Version Compatibility

• Check the CRD version installed in the cluster
• Use the correct apiVersion for the CRD
• Be aware of deprecations (e.g., v1alpha1 → v1beta1 → v1)

Required Fields

• CRDs often have custom required fields in spec
• Check the CRD documentation for field requirements
• Use kubectl explain <kind> to see field documentation

Validation

• CRDs may have custom validation rules
• OpenAPI schema validation is stricter in newer K8s versions
• Use dry-run to catch validation errors before applying

# Explain CRD fields
kubectl explain certificate.spec
kubectl explain certificate.spec.issuerRef

Anti-Patterns to Avoid

1. Running as Root

# Bad
securityContext:
  runAsUser: 0

# Good
securityContext:
  runAsNonRoot: true
  runAsUser: 1000

2. Using Latest Tag

# Bad
image: nginx:latest

# Good
image: nginx:1.21.6

3. No Resource Limits

# Bad - No limits
containers:
  - name: app
    image: my-app:1.0

# Good - With limits
containers:
  - name: app
    image: my-app:1.0
    resources:
      limits:
        memory: "256Mi"
        cpu: "500m"

4. Privileged Containers

# Bad
securityContext:
  privileged: true

# Good
securityContext:
  privileged: false
  allowPrivilegeEscalation: false

5. No Probes

# Bad - No health checks
containers:
  - name: app

# Good - With probes
containers:
  - name: app
    livenessProbe:
      httpGet:
        path: /health
        port: 8080
    readinessProbe:
      httpGet:
        path: /ready
        port: 8080

Summary Checklist

Before deploying Kubernetes resources, verify:

Required

• apiVersion and kind are correct
• metadata.name follows naming conventions
• Labels include recommended Kubernetes labels
• Selectors match pod labels exactly
• At least one container is defined

Recommended

• Resource requests and limits are set
• Liveness and readiness probes are configured
• Security context is defined (non-root, read-only fs)
• Image uses specific tag (not latest)
• Secrets are used for sensitive data (not ConfigMaps)

Production

• Pod Disruption Budget is configured
• Network Policies are in place
• HPA is configured for scalable workloads
• Service accounts are properly scoped
• Pod anti-affinity for high availability

Helm Template Functions Reference

This reference provides a comprehensive guide to Helm template functions, including built-in functions and Sprig library functions.

Essential Helm Functions

include

Includes a named template and allows piping the output to other functions.

Syntax:

{{ include "template.name" . }}

Examples:

# Include and indent
metadata:
  labels:
    {{- include "mychart.labels" . | nindent 4 }}

# Include and quote
value: {{ include "mychart.value" . | quote }}

# Include with custom context
{{- include "mychart.container" (dict "root" . "container" .Values.mainContainer) }}

When to use: Prefer include over template when you need to manipulate the output with functions.

tpl

Evaluates a string as a template, allowing dynamic template rendering.

Syntax:

{{ tpl <string> <context> }}

Examples:

# Render a value as template
{{ tpl .Values.customConfig . }}

# Render external file as template
{{ tpl (.Files.Get "config/app.conf") . }}

# values.yaml
customConfig: |
  server:
    host: {{ .Values.server.host }}
    port: {{ .Values.server.port }}

When to use: When users need to provide template strings in values or external files.

required

Enforces that a value must be provided, failing with a custom error message if missing.

Syntax:

{{ required "error message" .Values.path }}

Examples:

# Require a critical value
apiVersion: v1
kind: Service
metadata:
  name: {{ required "A valid service name is required!" .Values.service.name }}

# Require database password
data:
  password: {{ required "database.password must be set" .Values.database.password | b64enc }}

# Require multiple values
env:
  - name: API_KEY
    value: {{ required "apiKey must be provided" .Values.apiKey | quote }}

When to use: For critical values that have no sensible default.

lookup

Queries existing Kubernetes resources in the cluster during template rendering.

Syntax:

{{ lookup "apiVersion" "kind" "namespace" "name" }}

Examples:

# Look up existing secret
{{- $secret := lookup "v1" "Secret" .Release.Namespace "my-secret" }}
{{- if $secret }}
  # Secret exists, use existing password
  password: {{ $secret.data.password }}
{{- else }}
  # Create new password
  password: {{ randAlphaNum 16 | b64enc }}
{{- end }}

# List all pods in namespace
{{- $pods := lookup "v1" "Pod" .Release.Namespace "" }}

# Get specific resource
{{- $cm := lookup "v1" "ConfigMap" "default" "my-config" }}

⚠️ Cautions:

• Only works during helm install and helm upgrade, not with helm template
• Requires cluster access
• Can slow down rendering
• Creates tight coupling between chart and cluster state

When to use: When you need to check for existing resources or migrate from existing deployments.

String Functions

quote / squote

Wraps a string in double or single quotes.

Examples:

# Double quotes
env:
  - name: HOST
    value: {{ .Values.host | quote }}  # Output: "localhost"

# Single quotes
value: {{ .Values.name | squote }}  # Output: 'myapp'

default

Provides a fallback value if the input is empty.

Examples:

# Simple default
replicas: {{ .Values.replicaCount | default 1 }}

# Chain with other functions
image: {{ .Values.image.tag | default .Chart.AppVersion | quote }}

# Default for nested values
{{ .Values.server.port | default 8080 }}

trim / trimSuffix / trimPrefix

Removes whitespace or specific strings.

Examples:

# Remove whitespace
name: {{ .Values.name | trim }}

# Remove suffix
name: {{ .Release.Name | trimSuffix "-dev" }}

# Remove prefix
name: {{ .Values.fullName | trimPrefix "app-" }}

# Common pattern for resource names
name: {{ include "mychart.fullname" . | trunc 63 | trimSuffix "-" }}

upper / lower / title

Changes string case.

Examples:

# Uppercase
env: {{ .Values.environment | upper }}  # Output: PRODUCTION

# Lowercase
name: {{ .Values.name | lower }}  # Output: myapp

# Title case
label: {{ .Values.label | title }}  # Output: My Application

trunc

Truncates a string to a specified length.

Examples:

# Truncate to 63 chars (K8s DNS limit)
name: {{ .Release.Name | trunc 63 | trimSuffix "-" }}

# Truncate to 20 chars
shortName: {{ .Values.name | trunc 20 }}

repeat

Repeats a string N times.

Examples:

# Repeat string
value: {{ "=" | repeat 10 }}  # Output: ==========

# Create separator
comment: {{ "#" | repeat 20 }}  # Output: ####################

replace

Replaces occurrences of a substring.

Examples:

# Replace underscores with hyphens
name: {{ .Values.name | replace "_" "-" }}

# Replace spaces
label: {{ .Values.label | replace " " "-" | lower }}

# Chart label (replace + with _)
chart: {{ printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" }}

substr

Extracts a substring.

Examples:

# Get first 10 characters
short: {{ .Values.name | substr 0 10 }}

# Get characters 5-15
middle: {{ .Values.name | substr 5 15 }}

nospace

Removes all whitespace from a string.

Examples:

# Remove all spaces
compact: {{ .Values.value | nospace }}  # "hello world" → "helloworld"

contains / hasPrefix / hasSuffix

Checks if a string contains, starts with, or ends with a substring.

Examples:

# Check if contains
{{- if contains "prod" .Values.environment }}
  # Production configuration
{{- end }}

# Check prefix
{{- if hasPrefix "app-" .Values.name }}
  name: {{ .Values.name }}
{{- else }}
  name: {{ printf "app-%s" .Values.name }}
{{- end }}

# Check suffix
{{- if hasSuffix "-service" .Values.name }}
  # Already has suffix
{{- end }}

Type Conversion Functions

toYaml / fromYaml

Converts between Go objects and YAML strings.

Examples:

# Convert to YAML
{{- with .Values.resources }}
resources:
  {{- toYaml . | nindent 2 }}
{{- end }}

# Parse YAML string
{{- $config := .Values.configYaml | fromYaml }}
{{- $config.database.host }}

toJson / fromJson

Converts between Go objects and JSON strings.

Examples:

# Convert to JSON
data:
  config.json: |
    {{- .Values.config | toJson | nindent 4 }}

# Parse JSON
{{- $data := .Values.jsonString | fromJson }}
{{- $data.key }}

toString

Converts any value to a string.

Examples:

# Convert number to string
port: {{ .Values.port | toString | quote }}

# Convert boolean to string
enabled: {{ .Values.enabled | toString }}

List/Array Functions

list

Creates a list.

Examples:

# Create list
{{- $myList := list "a" "b" "c" }}

# Pass multiple arguments to template
{{- include "mychart.template" (list . "arg1" "arg2") }}

append / prepend

Adds elements to a list.

Examples:

# Append to list
{{- $list := list "a" "b" }}
{{- $list = append $list "c" }}  # ["a", "b", "c"]

# Prepend to list
{{- $list := list "b" "c" }}
{{- $list = prepend $list "a" }}  # ["a", "b", "c"]

first / rest / last

Gets elements from a list.

Examples:

# Get first element
{{- $first := first $myList }}

# Get all but first
{{- $rest := rest $myList }}

# Get last element
{{- $last := last $myList }}

has

Checks if a list contains an element.

Examples:

{{- if has "production" .Values.environments }}
  # Production configuration
{{- end }}

compact

Removes empty/nil elements from a list.

Examples:

{{- $list := list "a" "" "b" nil "c" }}
{{- $cleaned := compact $list }}  # ["a", "b", "c"]

uniq

Removes duplicate elements.

Examples:

{{- $list := list "a" "b" "a" "c" "b" }}
{{- $unique := uniq $list }}  # ["a", "b", "c"]

sortAlpha

Sorts list alphabetically.

Examples:

{{- $sorted := .Values.items | sortAlpha }}

Dictionary/Map Functions

dict

Creates a dictionary.

Examples:

# Create dict
{{- $myDict := dict "key1" "value1" "key2" "value2" }}

# Pass custom context to template
{{- include "mychart.template" (dict "root" . "custom" "value") }}

# Complex context
{{- $ctx := dict "top" . "container" .Values.mainContainer "port" .Values.service.port }}
{{- include "mychart.container" $ctx }}

merge / mergeOverwrite

Merges dictionaries.

Examples:

# Merge dictionaries (dest, src1, src2, ...)
{{- $defaults := dict "replicas" 1 "port" 80 }}
{{- $overrides := dict "replicas" 3 }}
{{- $final := merge $overrides $defaults }}
# Result: {"replicas": 3, "port": 80}

# mergeOverwrite (right-most wins)
{{- $result := mergeOverwrite $dict1 $dict2 }}

keys / values

Gets keys or values from a dictionary.

Examples:

# Get all keys
{{- $keys := keys .Values.config }}

# Get all values
{{- $vals := values .Values.config }}

# Iterate over keys
{{- range $key := keys .Values.labels | sortAlpha }}
  {{ $key }}: {{ index $.Values.labels $key }}
{{- end }}

pick / omit

Selects or excludes keys from a dictionary.

Examples:

# Pick specific keys
{{- $subset := pick .Values.config "host" "port" }}

# Omit specific keys
{{- $filtered := omit .Values.config "password" "secret" }}

hasKey

Checks if a dictionary has a key.

Examples:

{{- if hasKey .Values "database" }}
  {{- if hasKey .Values.database "password" }}
    # Password is configured
  {{- end }}
{{- end }}

pluck

Gets a value by key from multiple dictionaries.

Examples:

# Get "name" from first dict that has it
{{- $name := pluck "name" .Values.override .Values.defaults | first }}

Encoding Functions

b64enc / b64dec

Base64 encode/decode.

Examples:

# Encode secret
apiVersion: v1
kind: Secret
data:
  password: {{ .Values.password | b64enc }}

# Decode existing secret
{{- $secret := lookup "v1" "Secret" .Release.Namespace "my-secret" }}
{{- if $secret }}
  {{- $decoded := $secret.data.password | b64dec }}
{{- end }}

sha256sum

Generates SHA256 hash.

Examples:

# Create checksum annotation to trigger rolling update
annotations:
  checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}

# Hash password
data:
  passwordHash: {{ .Values.password | sha256sum }}

uuidv4

Generates a random UUID v4.

Examples:

# Generate unique ID
id: {{ uuidv4 }}

Mathematical Functions

add / sub / mul / div / mod

Basic arithmetic operations.

Examples:

# Addition
replicas: {{ add .Values.baseReplicas 2 }}

# Subtraction
port: {{ sub .Values.maxPort 100 }}

# Multiplication
memory: {{ mul .Values.memoryPerPod .Values.replicas }}

# Division
cpuPerPod: {{ div .Values.totalCpu .Values.replicas }}

# Modulo
remainder: {{ mod .Values.value 10 }}

max / min

Gets maximum or minimum value.

Examples:

# Ensure at least 1 replica
replicas: {{ max 1 .Values.replicaCount }}

# Cap at 10 replicas
replicas: {{ min 10 .Values.replicaCount }}

floor / ceil / round

Rounding functions.

Examples:

# Round down
value: {{ floor 3.7 }}  # 3

# Round up
value: {{ ceil 3.2 }}  # 4

# Round to nearest
value: {{ round 3.5 }}  # 4

Date Functions

now

Gets current time.

Examples:

# Current timestamp
annotations:
  timestamp: {{ now | date "2006-01-02T15:04:05Z" }}

date

Formats a date/time.

Examples:

# Format date
date: {{ now | date "2006-01-02" }}  # 2024-01-15

# Full timestamp
timestamp: {{ now | date "2006-01-02T15:04:05Z07:00" }}

# Custom format
generated: {{ now | date "Monday, 02-Jan-06 15:04:05 MST" }}

dateModify

Modifies a date.

Examples:

# Add 24 hours
tomorrow: {{ now | dateModify "24h" }}

# Subtract 7 days
lastWeek: {{ now | dateModify "-168h" }}

Comparison Functions

eq / ne

Equality and inequality.

Examples:

{{- if eq .Values.environment "production" }}
  # Production settings
{{- end }}

{{- if ne .Values.replicaCount 1 }}
  # Multiple replicas
{{- end }}

lt / le / gt / ge

Less than, less than or equal, greater than, greater than or equal.

Examples:

{{- if gt .Values.replicaCount 1 }}
  # Multiple replicas
{{- end }}

{{- if le .Values.maxConnections 100 }}
  # Low connection count
{{- end }}

and / or / not

Logical operations.

Examples:

{{- if and .Values.ingress.enabled .Values.ingress.tls.enabled }}
  # Ingress with TLS
{{- end }}

{{- if or (eq .Values.env "dev") (eq .Values.env "staging") }}
  # Non-production environment
{{- end }}

{{- if not .Values.production }}
  # Development mode
{{- end }}

Flow Control Functions

fail

Fails template rendering with an error message.

Examples:

{{- if not .Values.required }}
  {{- fail "required value is not set" }}
{{- end }}

{{- if lt .Values.replicas 1 }}
  {{- fail "replicas must be at least 1" }}
{{- end }}

coalesce

Returns the first non-empty value.

Examples:

# Use first non-empty value
name: {{ coalesce .Values.nameOverride .Values.name .Chart.Name }}

# Multiple fallbacks
host: {{ coalesce .Values.database.host .Values.defaultHost "localhost" }}

ternary

Inline if-then-else.

Examples:

# Ternary operator
type: {{ ternary "LoadBalancer" "ClusterIP" .Values.production }}

# With comparison
replicas: {{ ternary 3 1 (eq .Values.env "production") }}

Indentation Functions

indent

Indents each line by N spaces.

Examples:

# Indent by 4 spaces
metadata:
  labels:
{{ include "mychart.labels" . | indent 4 }}

nindent

Adds a newline then indents.

Examples:

# Newline + indent (preferred)
metadata:
  labels:
    {{- include "mychart.labels" . | nindent 4 }}

Why prefer nindent: Most YAML structures need a newline before the indented content, making nindent the right choice in most cases.

Random Functions

randAlphaNum

Generates random alphanumeric string.

Examples:

# Generate random password
{{- $password := randAlphaNum 16 }}

# Generate unique suffix
name: {{ printf "%s-%s" .Release.Name (randAlphaNum 5) }}

randAlpha / randNumeric

Generates random alphabetic or numeric string.

Examples:

# Random letters only
code: {{ randAlpha 8 }}

# Random numbers only
id: {{ randNumeric 6 }}

randAscii

Generates random ASCII string.

Examples:

# Random ASCII characters
token: {{ randAscii 32 }}

File Functions

Files.Get

Reads a file from the chart.

Examples:

# Read configuration file
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "mychart.fullname" . }}
data:
  config.yaml: |
    {{- .Files.Get "config/app.yaml" | nindent 4 }}

Files.GetBytes

Reads a file as bytes (for binary files).

Examples:

# Include binary file
data:
  image.png: {{ .Files.GetBytes "files/image.png" | b64enc }}

Files.Glob

Reads multiple files matching a pattern.

Examples:

# Include all YAML files
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "mychart.fullname" . }}
data:
  {{- range $path, $content := .Files.Glob "config/*.yaml" }}
  {{ base $path }}: |
    {{- $content | nindent 4 }}
  {{- end }}

Files.Lines

Reads a file line by line.

Examples:

# Process file line by line
{{- range .Files.Lines "config/servers.txt" }}
  - {{ . }}
{{- end }}

Files.AsConfig / Files.AsSecrets

Creates ConfigMap or Secret data from files.

Examples:

# ConfigMap from files
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "mychart.fullname" . }}
data:
  {{- (.Files.Glob "config/*").AsConfig | nindent 2 }}

# Secret from files
apiVersion: v1
kind: Secret
metadata:
  name: {{ include "mychart.fullname" . }}
data:
  {{- (.Files.Glob "secrets/*").AsSecrets | nindent 2 }}

Path Functions

base / dir / ext / clean

Path manipulation functions.

Examples:

# Get filename
{{- $filename := base "/path/to/file.yaml" }}  # file.yaml

# Get directory
{{- $dir := dir "/path/to/file.yaml" }}  # /path/to

# Get extension
{{- $ext := ext "file.yaml" }}  # .yaml

# Clean path
{{- $clean := clean "/path//to/../file" }}  # /path/file

Regex Functions

regexMatch

Tests if a string matches a regex.

Examples:

{{- if regexMatch "^[0-9]+$" .Values.port }}
  # Port is numeric
{{- end }}

regexFind / regexFindAll

Finds regex matches.

Examples:

# Find first match
{{- $match := regexFind "[0-9]+" .Values.version }}

# Find all matches
{{- $matches := regexFindAll "[A-Z]+" .Values.name -1 }}

regexReplaceAll

Replaces regex matches.

Examples:

# Replace all digits
name: {{ regexReplaceAll "[0-9]" .Values.name "" }}

# Replace pattern
clean: {{ regexReplaceAll "[^a-z0-9-]" .Values.name "" }}

regexSplit

Splits string by regex.

Examples:

# Split by delimiter
{{- $parts := regexSplit ":" .Values.imageTag -1 }}

Semantic Version Functions

semver / semverCompare

Work with semantic versions.

Examples:

# Parse semantic version
{{- $version := semver "1.2.3" }}
{{- $version.Major }}  # 1
{{- $version.Minor }}  # 2
{{- $version.Patch }}  # 3

# Compare versions
{{- if semverCompare ">=1.20.0" .Capabilities.KubeVersion.Version }}
  # Kubernetes 1.20 or higher
{{- end }}

Advanced Patterns

Custom Context Passing

{{- define "mychart.container" -}}
{{- $root := .root }}
{{- $container := .container }}
{{- $port := .port }}
name: {{ $container.name }}
image: {{ $container.image }}
ports:
  - containerPort: {{ $port }}
{{- end }}

# Usage
{{- include "mychart.container" (dict "root" . "container" .Values.mainContainer "port" 8080) }}

Multi-Stage Processing

{{- $config := .Values.configYaml | fromYaml }}
{{- $merged := merge .Values.overrides $config }}
{{- $filtered := omit $merged "internalKey" }}
{{- toYaml $filtered | nindent 2 }}

Conditional Value Selection

{{- $value := "" }}
{{- if .Values.custom }}
{{- $value = .Values.custom }}
{{- else if .Values.default }}
{{- $value = .Values.default }}
{{- else }}
{{- $value = "fallback" }}
{{- end }}

Pipeline Composition

# Chain multiple functions
value: {{ .Values.name | trim | lower | replace " " "-" | trunc 63 | trimSuffix "-" | quote }}

# Multi-line pipeline
{{- .Values.config
  | toYaml
  | indent 2
  | trim }}

Function Combination Examples

Resource Name Generation

{{- define "mychart.resourceName" -}}
{{- $name := include "mychart.fullname" . -}}
{{- $suffix := .suffix | default "" -}}
{{- if $suffix }}
{{- printf "%s-%s" $name $suffix | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}

Safe Value Extraction

{{- $password := "" }}
{{- if and .Values.database (hasKey .Values.database "password") }}
{{- $password = .Values.database.password }}
{{- else }}
{{- $password = randAlphaNum 16 }}
{{- end }}

Configuration Merging

{{- $defaults := .Files.Get "config/defaults.yaml" | fromYaml }}
{{- $overrides := .Values.config | default (dict) }}
{{- $final := merge $overrides $defaults }}
config: |
  {{- $final | toYaml | nindent 2 }}

Performance Tips

1. Cache template results - Use variables to avoid recalculating:

{{- $fullname := include "mychart.fullname" . }}
name: {{ $fullname }}
matchLabels:
  app: {{ $fullname }}

2. Minimize lookups - lookup queries are expensive:

{{- $secret := lookup "v1" "Secret" .Release.Namespace "my-secret" }}
{{- if $secret }}
  # Use $secret multiple times
{{- end }}

3. Use with for scoping - Reduces template complexity:

{{- with .Values.ingress }}
  {{- if .enabled }}
    host: {{ .host }}
  {{- end }}
{{- end }}

Debugging Functions

printf

Formatted string output for debugging.

Examples:

# Debug values
{{- printf "Debug: name=%s, replicas=%d" .Values.name .Values.replicas | fail }}

toYaml for inspection

# Inspect values
{{- toYaml .Values | fail }}

Common Gotchas

1. Nil vs Empty String

# This fails if value is nil
{{- if .Values.optional }}  # Error if nil!

# This works
{{- if .Values.optional | default "" }}  # Safe

2. Type Conversion

# Port is integer in values but needs string comparison
{{- if eq (.Values.port | toString) "80" }}

3. Pipeline Precedence

# Wrong - quote applies to "true", not the result
{{- if .Values.enabled | quote }}

# Right - use parentheses
{{- if (.Values.enabled | quote) }}

4. Whitespace in Conditionals

# Creates extra whitespace
{{ if .Values.enabled }}
  value: true
{{ end }}

# Better - chomp whitespace
{{- if .Values.enabled }}
  value: true
{{- end }}