Skip to content

10.07 Customizing Chart Parameters

Abstract

Helm charts come with default configuration values, but real deployments usually need customization.

Helm allows customization using:

  • --set command-line parameters
  • custom values files with --values or -f
  • editing the chart locally after helm pull --untar

In production, prefer version-controlled values files for repeatable and auditable deployments.

Why Customize Chart Parameters?

When you install a chart, Helm uses the chart's default values.yaml.

Example WordPress chart values:

wordpressUsername: user
wordpressPassword: ""
wordpressEmail: user@example.com
wordpressFirstName: FirstName
wordpressLastName: LastName
wordpressBlogName: User's Blog!

These values are injected into Kubernetes manifests using Helm templates.

Example deployment template:

env:
  - name: WORDPRESS_USERNAME
    value: {{ .Values.wordpressUsername | quote }}

  - name: WORDPRESS_EMAIL
    value: {{ .Values.wordpressEmail | quote }}

  - name: WORDPRESS_BLOG_NAME
    value: {{ .Values.wordpressBlogName | quote }}

Note

The chart template does not hardcode every value.
It reads values from values.yaml and renders final Kubernetes YAML during installation.

How Helm Values Work

Helm uses values in this order:

Chart default values.yaml
        ↓
Custom values file
        ↓
--set command-line overrides
        ↓
Rendered Kubernetes manifests

Tip

Values passed with --set override values from the default values.yaml.

Method 1: Customize with --set

Use --set for quick command-line overrides.

helm install my-release bitnami/wordpress   --set wordpressBlogName="Helm Tutorials"   --set wordpressEmail="john@example.com"

This overrides:

wordpressBlogName: User's Blog!
wordpressEmail: user@example.com

With:

wordpressBlogName: Helm Tutorials
wordpressEmail: john@example.com

Example

Use --set for small changes, quick labs, or one-time testing.

Method 2: Customize with a Values File

Create a custom values file.

custom-values.yaml
wordpressBlogName: Helm Tutorials
wordpressEmail: john@example.com

Install using the custom file:

helm install my-release bitnami/wordpress   --values custom-values.yaml

Short form:

helm install my-release bitnami/wordpress   -f custom-values.yaml

Success

In production, use a custom values file because it is easier to review, reuse, and store in Git.

Method 3: Pull and Edit the Chart Locally

Sometimes you may want to inspect or modify the chart before installing it.

Pull the chart:

helm pull bitnami/wordpress

Pull and extract it:

helm pull --untar bitnami/wordpress

List files:

ls
ls wordpress

Example chart contents:

wordpress/
├── Chart.yaml
├── values.yaml
├── values.schema.json
├── templates/
├── charts/
├── README.md
└── .helmignore

Edit the chart's values.yaml:

vi wordpress/values.yaml

Install from the local chart directory:

helm install my-release ./wordpress

Warning

Editing downloaded charts directly is useful for learning, but it is not the best production workflow unless the chart is maintained in your own source control.

Comparing the Three Methods

Method Best For Production Recommendation
--set Quick overrides Use only for small non-sensitive values
--values / -f Repeatable configuration Preferred
helm pull --untar Inspecting or modifying chart source Use only when maintaining your own chart copy

Example: WordPress Blog Name

Default value:

wordpressBlogName: User's Blog!

Override using --set:

helm install my-release bitnami/wordpress   --set wordpressBlogName="Helm Tutorials"

Override using values file:

custom-values.yaml
wordpressBlogName: Helm Tutorials

helm install my-release bitnami/wordpress   -f custom-values.yaml

Note

Both approaches update the rendered Kubernetes manifests before Helm applies them to the cluster.

Example: Multiple Custom Parameters

custom-values.yaml
wordpressBlogName: Helm Tutorials
wordpressEmail: john@example.com
wordpressUsername: admin

Install:

helm install my-release bitnami/wordpress   -f custom-values.yaml

Dry run before applying:

helm install my-release bitnami/wordpress   -f custom-values.yaml   --dry-run   --debug

Tip

Always test values with --dry-run --debug before applying changes to production.

View Chart Values Before Installing

Show default values:

helm show values bitnami/wordpress

Save default values to a file:

helm show values bitnami/wordpress > values.yaml

Edit the file:

vi values.yaml

Install with the customized file:

helm install my-release bitnami/wordpress   -f values.yaml

Success

This is a clean workflow for production because your final configuration is visible in one file.

Upgrade with Custom Values

If the release already exists, use helm upgrade.

helm upgrade my-release bitnami/wordpress   -f custom-values.yaml

Install if missing, upgrade if existing:

helm upgrade --install my-release bitnami/wordpress   -f custom-values.yaml

Tip

helm upgrade --install is commonly used in CI/CD pipelines.

Value Precedence

When multiple values are provided, Helm applies the later override with higher priority.

Example:

helm install my-release bitnami/wordpress   -f custom-values.yaml   --set wordpressBlogName="CLI Blog"

If custom-values.yaml contains:

wordpressBlogName: File Blog

Final value:

wordpressBlogName: CLI Blog

Warning

--set has higher priority than values files. Be careful in CI/CD pipelines where command-line overrides may silently replace file values.

Handling Secrets

Avoid this:

helm install my-release bitnami/wordpress   --set wordpressPassword="MyPassword123"

Why?

  • It may appear in shell history
  • It may be visible in process lists
  • It may be stored in CI/CD logs

Better options:

helm install my-release bitnami/wordpress   -f secure-values.yaml

Or use an existing Kubernetes Secret when the chart supports it:

existingSecret: wordpress-secret

Danger

Do not store production passwords, tokens, or private keys in plain text Git repositories.

Production Workflow

Recommended production workflow:

Review chart documentation
        ↓
Export default values
        ↓
Create environment-specific values file
        ↓
Run helm template / dry-run
        ↓
Install or upgrade release
        ↓
Store values file in Git

Example:

helm show values bitnami/wordpress > values-prod.yaml

helm template my-release bitnami/wordpress   -f values-prod.yaml

helm upgrade --install my-release bitnami/wordpress   -f values-prod.yaml   --namespace wordpress   --create-namespace

Environment-Specific Values

Use separate files per environment.

values-dev.yaml
values-test.yaml
values-prod.yaml

Install development:

helm upgrade --install wordpress-dev bitnami/wordpress   -f values-dev.yaml   -n dev

Install production:

helm upgrade --install wordpress-prod bitnami/wordpress   -f values-prod.yaml   -n prod

Success

Separate values files reduce accidental production changes.

Do's

  • Use helm show values before installing a chart
  • Use -f custom-values.yaml for repeatable deployments
  • Store non-sensitive values files in Git
  • Use --dry-run --debug before production changes
  • Use helm template to inspect generated manifests
  • Use separate values files for dev, test, and prod
  • Pin chart versions for production
  • Use existing Kubernetes Secrets for sensitive values when supported

Don'ts

  • Don't rely only on default chart values
  • Don't pass secrets using --set
  • Don't edit downloaded charts manually without source control
  • Don't use the same values file for every environment
  • Don't upgrade production charts without reviewing rendered manifests
  • Don't assume every chart uses the same value names
  • Don't skip chart documentation

Useful Commands

Task Command
Show default values helm show values <chart>
Install with --set helm install <release> <chart> --set key=value
Install with values file helm install <release> <chart> -f values.yaml
Pull chart helm pull <chart>
Pull and extract chart helm pull --untar <chart>
Install local chart helm install <release> ./chart-dir
Render templates helm template <release> <chart> -f values.yaml
Dry run install helm install <release> <chart> -f values.yaml --dry-run --debug
Upgrade with values helm upgrade <release> <chart> -f values.yaml
Upgrade or install helm upgrade --install <release> <chart> -f values.yaml

Troubleshooting

Question

Values are not changing after install?

Check:

  • Did you use the correct value key?
  • Did you pass the correct file with -f?
  • Did --set override your file value?
  • Did you run helm upgrade instead of helm install for an existing release?
  • Did you inspect rendered YAML with helm template?

Summary

Quote

  • Helm charts use values.yaml for configurable parameters
  • --set is useful for quick command-line overrides
  • --values or -f is better for production
  • helm pull --untar lets you inspect and edit charts locally
  • Use dry-run and rendered manifests before production deployment
  • Avoid passing secrets directly through command-line parameters