Configuration Model

Configuration Model defines the structured approach Helm uses to manage and customize the deployment of applications through charts. It establishes how configuration values are specified, overridden, and merged during the release lifecycle, enabling flexible and reusable application packaging. This model is key to controlling application behavior without modifying chart templates directly, allowing users to tailor deployments via configuration files and command-line parameters.

Core Concepts of the Configuration Model

Values Files

Values files (commonly values.yaml) serve as the primary source of default configuration data for a Helm chart. They define key-value pairs that represent settings used by chart templates. These files are written in YAML format and provide a hierarchical structure to organize configuration options cleanly.

Multiple values files can be used to represent different environments or deployment scenarios, and users can supply additional custom values files at install or upgrade time to override defaults.

Hierarchical and Nested Configuration

The configuration model supports nested structures, allowing complex settings to be expressed in a hierarchical manner. This nesting is reflected in the YAML indentation and enables grouping related parameters together logically. For example, database connection details or resource limits can be grouped under their respective keys.

Value Precedence and Overriding

Precedence Order

When Helm renders templates, it merges configuration values from various sources in a well-defined precedence order:

1. Chart default values in values.yaml.
2. Values supplied via additional values files using -f or --values flags.
3. Explicit key-value pairs provided with the --set or --set-string flags.
4. Environment variables or Helm release-specific values injected at runtime.

Values specified later in this order override earlier values, enabling fine-grained control of deployment parameters.

Merging Strategy

Helm uses a strategic merge process when combining multiple value sources. For mappings (YAML dictionaries), keys are recursively merged, while for scalar values or arrays, latter values overwrite earlier ones completely. This behavior allows incremental customization without losing unspecified defaults.

Template Access and Usage

Accessing Configuration Values in Templates

Within Helm templates, configuration values are accessed using the .Values object. Dot notation or bracket syntax allows retrieval of nested keys.

Example:

image:
  repository: nginx
  tag: stable

In a template:

image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"

If a value is not specified in user overrides, the template falls back to the default from values.yaml.

Conditional Logic and Defaults

Templates can include conditional statements to handle missing or optional values gracefully using default functions:

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

This ensures robust template rendering even if certain configuration keys are omitted.

Common Configuration Patterns

Parameterizing Deployments

Typical chart values cover parameters such as:

• Replica counts
• Image repository, tag, and pull policies
• Resource requests and limits
• Environment variables
• Service ports and types
• Ingress rules and annotations

Each parameter is defined under a logical key and can be overridden to suit deployment needs.

Using Global Values

Charts may define a global section to hold values shared across subcharts or multiple components. This enables centralized configuration management and reduces duplication.

Example:

global:
  imagePullSecrets:
    - name: my-registry-key

Subcharts can reference .Values.global.imagePullSecrets to inherit these settings.

Configuration Validation and Schema

Helm supports defining a JSON Schema file (values.schema.json) alongside the chart to validate user-supplied values during install or upgrade. This schema enforces type correctness, allowed value ranges, and required fields, improving deployment reliability and user experience by catching errors early.

Summary of the Configuration Model Workflow

1. Provide default values in values.yaml to establish baseline settings.
2. Override values via additional files or --set flags to customize deployments.
3. Merge values according to precedence rules, with latter sources overriding former.
4. Render templates using the resolved .Values context.
5. Optionally validate the values against a schema before applying the release.

This model enables reusable, flexible, and maintainable Helm charts that adapt easily to diverse deployment environments and requirements.