Values Configuration - Douban Helm Charts

Overview

The values.yaml file is the primary configuration interface for Helm charts. It defines default values that can be overridden during installation or upgrade to customize your deployment.

Common Value Patterns

Image Configuration

All charts follow a consistent pattern for image configuration:

image:
  repository: nginx
  pullPolicy: IfNotPresent
  tag: ""  # Defaults to chart appVersion if not set

imagePullSecrets: []

Key Points:

If tag is empty, the chart’s appVersion is used automatically
pullPolicy defaults to IfNotPresent to reduce registry calls
Use imagePullSecrets for private registries

Replica and Scaling

Static Replicas
Autoscaling

replicaCount: 1
autoscaling:
  enabled: false

Use fixed replica count for predictable workloads.

replicaCount: 1  # Ignored when autoscaling enabled
autoscaling:
  enabled: true
  minReplicas: 1
  maxReplicas: 100
  targetCPUUtilizationPercentage: 80
  # targetMemoryUtilizationPercentage: 80

Enable horizontal pod autoscaling based on CPU or memory usage.

Service Configuration

service:
  type: ClusterIP
  port: 80

containerPort: 80

Service Types:

ClusterIP: Internal cluster access only (default)
NodePort: Exposes on each node’s IP at a static port
LoadBalancer: Creates external load balancer

Service Account

serviceAccount:
  create: true
  annotations: {}
  name: ""  # Auto-generated if empty

Best Practices:

Always create a service account for proper RBAC
Use annotations for cloud provider integrations (e.g., AWS IAM roles)
Let the chart generate the name unless you need specific naming

Overriding Values

Using `--set` Flag

For simple overrides during installation:

helm install my-nginx ./nginx \
  --set replicaCount=3

When to use --set:

Quick testing and experimentation
Single value changes
CI/CD pipelines with dynamic values

Using Values Files

For complex configurations, create a custom values file:

replicaCount: 3

image:
  repository: nginx
  tag: "1.25.0"

service:
  type: LoadBalancer
  port: 80

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: myapp.example.com
      paths:
        - path: /
          pathType: Prefix

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

When to use values files:

Production deployments
Environment-specific configurations
Complex multi-value changes
Version-controlled configurations

Combining Methods

# Values files are applied first, then --set overrides
helm install my-nginx ./nginx \
  -f production-values.yaml \
  --set image.tag=1.25.1

Environment Variables

Simple Environment Variables

Most charts support the env field for custom environment variables:

env:
  - name: LOG_LEVEL
    value: "debug"
  - name: FEATURE_FLAG
    value: "true"
  - name: API_ENDPOINT
    value: "https://api.example.com"

Environment Variables from Secrets

env:
  - name: DATABASE_PASSWORD
    valueFrom:
      secretKeyRef:
        name: app-secrets
        key: db-password
  - name: API_KEY
    valueFrom:
      secretKeyRef:
        name: app-secrets
        key: api-key

Environment Variables from ConfigMaps

env:
  - name: APP_CONFIG
    valueFrom:
      configMapKeyRef:
        name: app-config
        key: config.json

Chart-Specific Patterns

Some charts use different naming conventions:

extraEnvs
envs.config/secret
global.extraEnvs

# Used in aliyun-exporter chart
extraEnvs:
  - name: CUSTOM_VAR
    value: "custom-value"

# Used in kafka-ui chart
envs:
  config:
    LOG_LEVEL: debug
    FEATURE_FLAG: "true"
  secret:
    API_KEY: "secret-value"

# Used in dify chart for all components
global:
  extraEnvs:
    - name: SHARED_CONFIG
      value: "shared-value"

Name Overrides

# Partially override the chart name
nameOverride: "my-app"

# Completely override the full name
fullnameOverride: "custom-name"

Impact:

nameOverride: Replaces the chart name in resource names
fullnameOverride: Completely replaces the generated full name
Affects all Kubernetes resources (Deployments, Services, etc.)

Viewing Effective Values

Inspect Default Values

# Show all default values from the chart
helm show values ./nginx

Check Deployed Values

# View values used in a deployed release
helm get values my-nginx

# Include default values
helm get values my-nginx --all

Preview Before Install

# Render templates without installing
helm template my-nginx ./nginx -f custom-values.yaml

# Debug mode shows more details
helm install my-nginx ./nginx -f custom-values.yaml --dry-run --debug

Best Practices

Use Values Files for Production

Always use values files for production deployments. This allows:

Version control integration
Easier review and audit
Consistent deployments
Better documentation

Organize by Environment

Structure your values files by environment:

values/
  base.yaml        # Common to all environments
  dev.yaml         # Development overrides
  staging.yaml     # Staging overrides
  production.yaml  # Production overrides

Never Commit Secrets

Never put sensitive values in values files:

Use Kubernetes Secrets
Reference secrets via valueFrom.secretKeyRef
Consider tools like sealed-secrets or external-secrets

Document Custom Values

Create a README with your custom values:

# Custom values for production deployment
# Last updated: 2024-03-05
# Owner: Platform Team

replicaCount: 3  # High availability

Use Specific Image Tags

Always specify image tags in production:

# Bad - uses latest
image:
  tag: ""

# Good - pinned version
image:
  tag: "1.25.0"

Common Patterns Across Charts

Standard Fields

These fields appear consistently across all charts:

replicaCount: 1
image:
  repository: ""
  pullPolicy: IfNotPresent
  tag: ""
imagePullSecrets: []
nameOverride: ""
fullnameOverride: ""
serviceAccount:
  create: true
  annotations: {}
  name: ""
podAnnotations: {}
podSecurityContext: {}
securityContext: {}
service:
  type: ClusterIP
  port: 80
resources: {}
autoscaling:
  enabled: false
  minReplicas: 1
  maxReplicas: 100
  targetCPUUtilizationPercentage: 80
nodeSelector: {}
tolerations: []
affinity: {}

Optional Components

Many charts include these optional features:

ingress:
  enabled: false
  className: ""
  annotations: {}
  hosts: []
  tls: []

httpRoute:
  enabled: false
  gatewayRef:
    name: envoy-gateway-bundle
    namespace: envoy-gateway-system

serviceMonitor:
  enabled: false

prometheusRule:
  enabled: false

Troubleshooting

Values Not Applied

# Check syntax
helm lint ./nginx -f custom-values.yaml

# Verify rendering
helm template my-nginx ./nginx -f custom-values.yaml | grep -A 10 "kind: Deployment"

Type Mismatches

# Wrong - string instead of number
replicaCount: "3"

# Correct
replicaCount: 3

# Wrong - missing quotes for special values
service:
  type: ClusterIP
  annotations:
    value: true  # YAML interprets as boolean

# Correct
service:
  type: ClusterIP
  annotations:
    value: "true"  # Quoted string

Debugging Template Rendering

# Show what values are actually used
helm get values my-nginx

# See full manifest
helm get manifest my-nginx

# Test template rendering
helm template my-nginx ./nginx \
  -f custom-values.yaml \
  --debug

Next Steps

Customization

Learn advanced customization techniques

Ingress

Configure ingress and routing

Monitoring

Set up Prometheus monitoring

Chart Development

Create your own charts

Get Started

Web Services

Monitoring & Exporters

Infrastructure

Applications

Configuration

Contributing

​Overview

​Common Value Patterns

​Image Configuration

​Replica and Scaling

​Service Configuration

​Service Account

​Overriding Values

​Using --set Flag

​Using Values Files

​Combining Methods

​Environment Variables

​Simple Environment Variables

​Environment Variables from Secrets

​Environment Variables from ConfigMaps

​Chart-Specific Patterns

​Name Overrides

​Viewing Effective Values

​Inspect Default Values

​Check Deployed Values

​Preview Before Install

​Best Practices

​Common Patterns Across Charts

​Standard Fields

​Optional Components

​Troubleshooting

​Values Not Applied

​Type Mismatches

​Debugging Template Rendering

​Next Steps