Helm

Helm Values YAML Example: Complete Configuration

Intermediate
13 minutes
Updated October 2026

Comprehensive Helm values.yaml example with all common configuration options explained and best practices.

Table of Contents

Understanding values.yaml

The values.yaml file defines the default configuration for a Helm chart. Values are accessed in templates via .Values.

# values.yaml
replicaCount: 3
image:
  repository: nginx
  tag: "1.25"
# templates/deployment.yaml
replicas: {{ .Values.replicaCount }}
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"

Complete Annotated Example

This is a production-ready values.yaml covering all common sections:

# ---------------------------------------------------------
# Application basics
# ---------------------------------------------------------
nameOverride: ""
fullnameOverride: ""

replicaCount: 3

# ---------------------------------------------------------
# Container image
# ---------------------------------------------------------
image:
  repository: myregistry.io/my-app
  pullPolicy: IfNotPresent   # Always | IfNotPresent | Never
  tag: ""                    # defaults to .Chart.AppVersion
  digest: ""                 # optional: pin by sha256 digest

imagePullSecrets:
  - name: regcred

# ---------------------------------------------------------
# Pod configuration
# ---------------------------------------------------------
podLabels:
  environment: production
  team: platform

podAnnotations:
  prometheus.io/scrape: "true"
  prometheus.io/port: "9090"

podSecurityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 1000

securityContext:
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: true
  capabilities:
    drop:
      - ALL

# ---------------------------------------------------------
# Environment variables
# ---------------------------------------------------------
env:
  - name: LOG_LEVEL
    value: "info"
  - name: DATABASE_URL
    valueFrom:
      secretKeyRef:
        name: db-credentials
        key: url

envFrom:
  - configMapRef:
      name: app-config

# ---------------------------------------------------------
# Service
# ---------------------------------------------------------
service:
  type: ClusterIP          # ClusterIP | NodePort | LoadBalancer
  port: 80
  targetPort: 8080
  annotations: {}

# ---------------------------------------------------------
# Ingress
# ---------------------------------------------------------
ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/rate-limit: "100"
  hosts:
    - host: app.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: app-tls
      hosts:
        - app.example.com

# ---------------------------------------------------------
# Resources
# ---------------------------------------------------------
resources:
  requests:
    memory: "256Mi"
    cpu: "250m"
  limits:
    memory: "512Mi"
    cpu: "500m"

# ---------------------------------------------------------
# Autoscaling
# ---------------------------------------------------------
autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 20
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 80

# ---------------------------------------------------------
# Health probes
# ---------------------------------------------------------
livenessProbe:
  httpGet:
    path: /healthz
    port: http
  initialDelaySeconds: 30
  periodSeconds: 10
  failureThreshold: 3

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

startupProbe:
  httpGet:
    path: /healthz
    port: http
  failureThreshold: 30
  periodSeconds: 5

# ---------------------------------------------------------
# Persistence
# ---------------------------------------------------------
persistence:
  enabled: true
  storageClass: "managed-premium"
  accessMode: ReadWriteOnce
  size: 10Gi
  mountPath: /data

# ---------------------------------------------------------
# Scheduling
# ---------------------------------------------------------
nodeSelector:
  kubernetes.io/os: linux

tolerations:
  - key: "dedicated"
    operator: "Equal"
    value: "workload"
    effect: "NoSchedule"

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchLabels:
              app: my-app
          topologyKey: kubernetes.io/hostname

topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: ScheduleAnyway

# ---------------------------------------------------------
# Pod disruption budget
# ---------------------------------------------------------
podDisruptionBudget:
  enabled: true
  minAvailable: 1

# ---------------------------------------------------------
# Service account
# ---------------------------------------------------------
serviceAccount:
  create: true
  name: ""
  annotations:
    azure.workload.identity/client-id: "xxxx-xxxx-xxxx"   # Azure Workload Identity
    # eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/my-role"  # AWS IRSA

# ---------------------------------------------------------
# Dependencies / subcharts
# ---------------------------------------------------------
postgresql:
  enabled: true
  auth:
    database: myapp
    username: myapp
  primary:
    persistence:
      size: 20Gi

redis:
  enabled: false

Environment-Specific Values

Keep a base values.yaml plus per-environment overrides:

charts/my-app/
├── values.yaml          # defaults
├── values-dev.yaml
├── values-staging.yaml
└── values-prod.yaml

values-dev.yaml

replicaCount: 1
image:
  pullPolicy: Always
  tag: "dev"

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

ingress:
  hosts:
    - host: app.dev.example.com
      paths:
        - path: /
          pathType: Prefix

autoscaling:
  enabled: false

values-prod.yaml

replicaCount: 5
image:
  pullPolicy: IfNotPresent

resources:
  requests:
    memory: "512Mi"
    cpu: "500m"
  limits:
    memory: "1Gi"
    cpu: "1000m"

podDisruptionBudget:
  enabled: true
  minAvailable: 2

Overriding Values

Command Line

# Single value
helm install my-app ./my-app --set image.tag=1.2.3

# Multiple values
helm install my-app ./my-app \
  --set image.tag=1.2.3 \
  --set replicaCount=5

# Array values
helm install my-app ./my-app \
  --set 'ingress.hosts[0].host=app.example.com'

# From file
helm install my-app ./my-app -f values-prod.yaml

# Layered values files (later files take precedence)
helm install my-app ./my-app -f values.yaml -f values-prod.yaml

Priority Order (lowest to highest)

  1. values.yaml (defaults)
  2. -f flag files (in order given)
  3. --set flags (highest precedence)

Common Patterns

Conditional Features

# values.yaml
monitoring:
  enabled: true
# templates/servicemonitor.yaml
{{- if .Values.monitoring.enabled }}
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
...
{{- end }}

Required Values (fail fast)

# templates/deployment.yaml
image: "{{ required "image.repository is required" .Values.image.repository }}"

Deploying without setting image.repository fails with a clear error.

Sensible Defaults in Templates

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

Validation and Schema

Use values.schema.json to validate user-provided values:

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

Values Anti-Patterns

  • Giant flat values files — values.yaml with 200 top-level keys nobody can navigate. Group related values under objects (database.host, database.port, database.name) so the structure documents itself.
  • Duplicating the same value — image.tag set in values.yaml and --set and the environment file. When they disagree, --set wins silently and the file lies about what's deployed.
  • Secrets in values files — password: supersecret committed to git. Values files are for configuration; secrets belong in valueFrom.secretKeyRef or external secret stores.
  • Environment files that rewrite the whole chart — a values-prod.yaml that changes 80% of the defaults means the defaults are wrong. Environment files should only override what actually differs.
  • Values that only make sense together — replicaCount and minReplicas where a caller can set replicaCount: 1 + autoscaling.minReplicas: 5 and get a surprise. Schema validation or required catches the impossible combinations.

Useful Commands

# Show the rendered values that will be used
helm template my-app ./my-app -f values-prod.yaml

# Show computed default values
helm show values ./my-app

# Validate templates without deploying
helm lint ./my-app

# Dry run an install
helm install my-app ./my-app --dry-run --debug

# See what values a release is using
helm get values my-app

Best Practices

  1. Document every value with comments
  2. Never put secrets in values.yaml — use valueFrom.secretKeyRef or external secrets
  3. Use --set sparingly — prefer values files tracked in Git
  4. Define a schema (values.schema.json) to catch mistakes early
  5. Keep environment diffs minimal — only override what differs
  6. Quote strings that look like numbers — port: "8080" is safer than port: 8080 in some contexts
Written & Reviewed by Yasir Masood, CloudOpsGuide Editor

Our tutorials and troubleshooting runbooks are written by a DevOps practitioner with hands-on experience operating Kubernetes, Terraform, CI/CD pipelines, and Linux infrastructure in production. Commands, manifests, and configurations are verified against current tooling releases. Learn more about our editorial process or report a correction or outdated flag.